guard-jasmine 0.1.0 → 0.2.0

data/LICENSE.BSD

@@ -0,0 +1,22 @@
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+  * Neither the name of the <organization> nor the
+    names of its contributors may be used to endorse or promote products
+    derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -38,21 +38,15 @@ Please be sure to have [Guard][] installed.
 
 Install the gem:
 
-```bash
-$ gem install guard-jasmine
-```
+    $ gem install guard-jasmine
 
 Add it to your `Gemfile`, preferably inside the development group:
 
-```ruby
-gem 'guard-jasmine'
-```
+    gem 'guard-jasmine'
 
 Add guard definition to your `Guardfile` by running this command:
 
-```bash
-$ guard init jasmine
-```
+    $ guard init jasmine
 
 ### Rails 3.1
 
@@ -63,26 +57,20 @@ Please read the detailed installation and configuration instructions at [Jasmine
 
 In short, you add it to your `Gemfile`:
 
-```ruby
-group :development, :test do
-  gem 'jasmine'
-end
-```
+    group :development, :test do
+      gem 'jasmine'
+    end
 
 and add a route for the Jasmine Test Runner to `config/routes.rb`:
 
-```ruby
-if ["development", "test"].include? Rails.env
-  mount Jasminerice::Engine => "/jasmine"
-end
-```
+    if ["development", "test"].include? Rails.env
+      mount Jasminerice::Engine => "/jasmine"
+    end
 
 Next you create the directory `spec/javascripts` where your CoffeeScript tests go into. You define the Rails 3.1
 asset pipeline manifest in `spec/javascripts/spec.js.coffee`:
 
-```ruby
-#=require_tree ./
-```
+    #=require_tree ./
 
 ### Rails 2 & 3
 
@@ -96,17 +84,13 @@ You need the PhantomJS browser installed on your system. You can download binari
 
 Alternatively you can install [Homebrew][] on Mac OS X and install it with:
 
-```bash
-$ brew install phantomjs
-```
+    $ brew install phantomjs
 
 If you are using Ubuntu 10.10, you can install it with apt:
 
-```bash
-$ sudo add-apt-repository ppa:jerome-etienne/neoip
-$ sudo apt-get update
-$ sudo apt-get install phantomjs
-```
+    $ sudo add-apt-repository ppa:jerome-etienne/neoip
+    $ sudo apt-get update
+    $ sudo apt-get install phantomjs
 
 You can also build it from source for several other operating systems, please consult the
 [PhantomJS build instructions][].
@@ -122,42 +106,41 @@ Guard::Jasmine can be adapted to all kind of projects. Please read the
 
 ### Rails 3.1 with Jasminerice
 
-```ruby
-guard 'jasmine' do
-  watch(%r{app/assets/javascripts/(.+)\.(js\.coffee|js)}) { |m| "spec/javascripts/#{m[1]}_spec.#{m[2]}" }
-  watch(%r{spec/javascripts/(.+)_spec\.(js\.coffee|js)})  { |m| "spec/javascripts/#{m[1]}_spec.#{m[2]}" }
-  watch(%r{spec/javascripts/spec\.(js\.coffee|js)})       { "spec/javascripts" }
-end
-```
+    guard 'jasmine' do
+      watch(%r{app/assets/javascripts/(.+)\.(js\.coffee|js)}) { |m| "spec/javascripts/#{m[1]}_spec.#{m[2]}" }
+      watch(%r{spec/javascripts/(.+)_spec\.(js\.coffee|js)})  { |m| "spec/javascripts/#{m[1]}_spec.#{m[2]}" }
+      watch(%r{spec/javascripts/spec\.(js\.coffee|js)})       { "spec/javascripts" }
+    end
 
 ### Rails 2 & 3 with the Jasmine gem
 
-```ruby
-guard 'jasmine', :url => 'http://127.0.0.1:8888' do
-  watch(%r{public/javascripts/(.+)\.js})                  { |m| "spec/javascripts/#{m[1]}_spec.js" }
-  watch(%r{spec/javascripts/(.+)_spec\.js})               { |m| "spec/javascripts/#{m[1]}_spec.js" }
-  watch(%r{spec/javascripts/support/jasmine\.yml})        { "spec/javascripts" }
-  watch(%r{spec/javascripts/support/jasmine_config\.rb})  { "spec/javascripts" }
-end
-```
+    guard 'jasmine', :url => 'http://127.0.0.1:8888' do
+      watch(%r{public/javascripts/(.+)\.js})                  { |m| "spec/javascripts/#{m[1]}_spec.js" }
+      watch(%r{spec/javascripts/(.+)_spec\.js})               { |m| "spec/javascripts/#{m[1]}_spec.js" }
+      watch(%r{spec/javascripts/support/jasmine\.yml})        { "spec/javascripts" }
+      watch(%r{spec/javascripts/support/jasmine_config\.rb})  { "spec/javascripts" }
+    end
 
 ## Options
 
 There following options can be passed to Guard::Jasmine:
 
-```ruby
-:jasmine_url => 'http://192.168.1.5/jasmine'  # URL where Jasmine is served.
-                                              # default: http://127.0.0.1/jasmine
 
-:phantomjs_bin => '~/bin/phantomjs'           # Path to phantomjs.
-                                              # default: '/usr/local/bin/phantomjs'
+    :jasmine_url => 'http://192.168.1.5/jasmine'  # URL where Jasmine is served.
+                                                  # default: http://127.0.0.1/jasmine
 
-:notifications => false                       # Show success and error messages.
-                                              # default: true
+    :phantomjs_bin => '~/bin/phantomjs'           # Path to phantomjs.
+                                                  # default: '/usr/local/bin/phantomjs'
+
+    :all_on_start => false                        # Run all specs on start.
+                                                  # default: true
+
+    :notifications => false                       # Show success and error messages.
+                                                  # default: true
+
+    :hide_success => true                         # Disable successful compilation messages.
+                                                  # default: false
 
-:hide_success => true                         # Disable successful compilation messages.
-                                              # default: false
-```
 
 ## Alternatives
 
@@ -169,6 +152,7 @@ featured browser environment.
 
 ## Development
 
+- Documentation hosted at [RubyDoc](http://rubydoc.info/gems/guard-jasmine/file/README.md)
 - Source hosted at [GitHub](https://github.com/netzpirat/guard-Jasmine)
 - Report issues and feature requests to [GitHub Issues](https://github.com/netzpirat/guard-Jasmine/issues)
 

data/lib/guard/jasmine.rb

@@ -3,28 +3,65 @@ require 'guard/guard'
 require 'guard/watcher'
 
 module Guard
+
+  # The Jasmine guard that gets notifications about the following
+  # Guard events: `start`, `stop`, `reload`, `run_all` and `run_on_change`.
+  #
   class Jasmine < Guard
 
     autoload :Formatter, 'guard/jasmine/formatter'
     autoload :Inspector, 'guard/jasmine/inspector'
     autoload :Runner, 'guard/jasmine/runner'
 
+    # Initialize Guard::Jasmine.
+    #
+    # @param [Array<Guard::Watcher>] watchers the watchers in the Guard block
+    # @param [Hash] options the options for the Guard
+    # @option options [String] :jasmine_url the url of the Jasmine test runner
+    # @option options [String] :phantomjs_bin the location of the PhantomJS binary
+    # @option options [Boolean] :notification show notifications
+    # @option options [Boolean] :hide_success hide success message notification
+    # @option options [Boolean] :all_on_start run all suites on start
+    #
     def initialize(watchers = [], options = { })
       defaults = {
           :jasmine_url   => 'http://localhost:3000/jasmine',
           :phantomjs_bin => '/usr/local/bin/phantomjs',
-          :notification => true,
-          :hide_success  => false
+          :notification  => true,
+          :hide_success  => false,
+          :all_on_start  => true
       }
+
       super(watchers, defaults.merge(options))
     end
 
+    # Gets called once when Guard starts.
+    #
+    # @return [Boolean] when the start was successful
+    #
+    def start
+      run_all if options[:all_on_start]
+
+      true
+    end
+
+    # Gets called when all specs should be run.
+    #
+    # @return [Boolean] when running all specs was successful
+    #
     def run_all
-      run_on_change(Watcher.match_files(self, Dir.glob(File.join('spec', '**', '*.js(.coffee)?'))))
+      Runner.run(['spec/javascripts'], options)
     end
 
+    # Gets called when watched paths and files have changes.
+    #
+    # @param [Array<String>] paths the changed paths and files
+    # @return [Boolean] when running the changed specs was successful
+    #
     def run_on_change(paths)
       Runner.run(Inspector.clean(paths), options)
+
+      #TODO: Evaluate result
     end
 
   end

data/lib/guard/jasmine/inspector.rb

@@ -1,8 +1,18 @@
 module Guard
   class Jasmine
+
+    # The inspector verifies of the changed paths are valid
+    # for Guard::Jasmine.
+    #
     module Inspector
       class << self
 
+        # Clean the changed paths and return only valid
+        # Jasmine specs in either JavaScript or CoffeeScript.
+        #
+        # @param [Array<String>] paths the changed paths
+        # @return [Array<String>] the valid spec files
+        #
         def clean(paths)
           paths.uniq!
           paths.compact!
@@ -13,14 +23,28 @@ module Guard
 
         private
 
+        # Tests if the file is valid.
+        #
+        # @param [String] file the file
+        # @return [Boolean] when the file valid
+        #
         def jasmine_spec?(path)
           jasmine_specs.include?(path)
         end
 
+        # Scans the project and keeps a list of all
+        # JavaScript and CoffeeScript files in the `spec`
+        # directory.
+        #
+        # @see #clear_jasmine_specs
+        # @return [Array<String>] the valid files
+        #
         def jasmine_specs
           @jasmine_specs ||= Dir.glob('spec/**/*_spec.{js,js.coffee}')
         end
 
+        # Clears the list of Jasmine specs in this project.
+        #
         def clear_jasmine_specs
           @jasmine_specs = nil
         end

data/lib/guard/jasmine/runner.rb

@@ -2,17 +2,32 @@ require 'multi_json'
 
 module Guard
   class Jasmine
+
+    # The Jasmine runner handles the execution of the spec through the PhantomJS binary,
+    # evaluates the JSON response from the PhantomJS Script `run_jasmine.coffee`,
+    # writes the result to the console and triggers optional system notifications.
+    #
     module Runner
       class << self
 
-        def run(files, options = { })
-          return false if files.empty?
-
-          message = options[:message] || (files == ['spec/javascripts'] ? 'Run all specs' : "Run specs #{ files.join(' ') }")
+        # Run the supplied specs.
+        #
+        # @param [Array<String>] paths the spec files or directories
+        # @param [Hash] options the options for the execution
+        # @option options [String] :jasmine_url the url of the Jasmine test runner
+        # @option options [String] :phantomjs_bin the location of the PhantomJS binary
+        # @option options [Boolean] :notification show notifications
+        # @option options [Boolean] :hide_success hide success message notification
+        # @return [Array<Object>] the result for each suite
+        #
+        def run(paths, options = { })
+          return false if paths.empty?
+
+          message = options[:message] || (paths == ['spec/javascripts'] ? 'Run all specs' : "Run specs #{ paths.join(' ') }")
           UI.info message, :reset => true
 
-          files.inject([]) do |results, file|
-            results << notify_result(run_jasmine(file, options), options)
+          paths.inject([]) do |results, file|
+            results << evaluate_result(run_jasmine_spec(file, options), options)
 
             results
           end.compact
@@ -20,26 +35,55 @@ module Guard
 
         private
 
-        def run_jasmine(file, options)
-            suite = jasmine_suite(file, options)
-            Formatter.info("Run Jasmine tests: #{ suite }")
-            IO.popen(phantomjs_command(options) + ' ' + suite)
+        # Run the Jasmine spec by executing the PhantomJS script.
+        #
+        # @param [String] path the path of the spec
+        #
+        def run_jasmine_spec(file, options)
+          suite = jasmine_suite(file, options)
+          Formatter.info("Run Jasmine tests: #{ suite }")
+          IO.popen(phantomjs_command(options) + ' ' + suite)
         end
 
+        # Get the PhantomJS binary and script to execute.
+        #
+        # @param [Hash] options the options for the execution
+        # @return [String] the command
+        #
         def phantomjs_command(options)
-           options[:phantomjs_bin] + ' ' + phantomjs_script
+          options[:phantomjs_bin] + ' ' + phantomjs_script
         end
 
+        # Get the Jasmine test runner URL with the appended suite name
+        # that acts as the spec filter.
+        #
+        # @param [Hash] options the options for the execution
+        # @return [String] the Jasmine url
+        #
         def jasmine_suite(file, options)
-          options[:jasmine_url] + suite_query_for(file)
+          options[:jasmine_url] + suite_name_for(file)
         end
 
+        # Get the PhantomJS script that executes the spec and extracts
+        # the result from the headless DOM.
+        #
+        # @return [String] the path to the PhantomJS script
+        #
         def phantomjs_script
           File.expand_path(File.join(File.dirname(__FILE__), 'phantomjs', 'run-jasmine.coffee'))
         end
 
-        def suite_query_for(file)
+        # The suite name must be extracted from the spec that
+        # will be run. This is done by parsing from the head of
+        # the spec file until the first `describe` function is
+        # found.
+        #
+        # @param [String] file the spec file
+        # @return [String] the suite name
+        #
+        def suite_name_for(file)
           return '' if file == 'spec/javascripts'
+
           query_string = ''
 
           File.foreach(file) do |line|
@@ -52,7 +96,15 @@ module Guard
           URI.encode(query_string)
         end
 
-        def notify_result(output, options)
+        # Evaluates the JSON response that the PhantomJS script
+        # writes to stdout. The results triggers further notification
+        # actions.
+        #
+        # @param [String] output the JSON output the spec run
+        # @param [Hash] options the options for the execution
+        # @return [Hash] the suite result
+        #
+        def evaluate_result(output, options)
           result = MultiJson.decode(output.read)
           output.close
 
@@ -65,12 +117,27 @@ module Guard
           result
         end
 
+        # Notification when a system error happens that
+        # prohibits the execution of the Jasmine spec.
+        #
+        # @param [Hash] the suite result
+        # @param [Hash] options the options for the execution
+        # @option options [Boolean] :notification show notifications
+        #
         def notify_runtime_error(result, options)
           message = "An error occurred: #{ result['error'] }"
           Formatter.error(message)
           Formatter.notify(message, :title => 'Jasmine error', :image => :failed, :priority => 2) if options[:notification]
         end
 
+        # Notification about a spec run, success or failure,
+        # and some stats.
+        #
+        # @param [Hash] result the suite result
+        # @param [Hash] options the options for the execution
+        # @option options [Boolean] :notification show notifications
+        # @option options [Boolean] :hide_success hide success message notification
+        #
         def notify_spec_result(result, options)
           specs    = result['stats']['specs']
           failures = result['stats']['failures']
@@ -87,6 +154,14 @@ module Guard
           end
         end
 
+        # Notification about spec failures. This combines the suite
+        # error messages into a single notification.
+        #
+        # @param [Hash] result the suite result
+        # @param [String] stats the status information
+        # @param [Hash] options the options for the execution
+        # @option options [Boolean] :notification show notifications
+        #
         def notify_spec_failures(result, stats, options)
           messages = result['suites'].inject('') do |messages, suite|
             suite['specs'].each do |spec|

data/lib/guard/jasmine/version.rb

@@ -1,5 +1,5 @@
 module Guard
   module JasmineVersion
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: guard-jasmine
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Michael Kessler
@@ -93,6 +93,22 @@ dependencies:
         version: "2.6"
   type: :development
   version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 0
+        - 7
+        - 2
+        version: 0.7.2
+  type: :development
+  version_requirements: *id006
 description: Guard::Jasmine automatically tests your Jasmine specs on PhantomJS
 email: 
 - michi@netzpiraten.ch
@@ -110,7 +126,8 @@ files:
 - lib/guard/jasmine/templates/Guardfile
 - lib/guard/jasmine/version.rb
 - lib/guard/jasmine.rb
-- LICENSE
+- LICENSE.MIT
+- LICENSE.BSD
 - README.md
 homepage: http://github.com/netzpirat/guard-jasmine
 licenses: []