guard-cucumber 0.6.2 → 0.6.3

data/README.md

@@ -1,10 +1,8 @@
-# Guard::Cucumber
-
-![travis-ci](http://travis-ci.org/netzpirat/guard-cucumber.png)
+# Guard::Cucumber [![Build Status](https://secure.travis-ci.org/netzpirat/guard-cucumber.png)](http://travis-ci.org/netzpirat/guard-cucumber)
 
 Guard::Cucumber allows you to automatically run Cucumber features when files are modified.
 
-Tested on MRI Ruby 1.8.7, 1.9.2 and the latest versions of JRuby & Rubinius.
+Tested on MRI Ruby 1.8.7, 1.9.2, REE and the latest versions of JRuby & Rubinius.
 
 If you have any questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
 
@@ -14,21 +12,15 @@ Please be sure to have [Guard](https://github.com/guard/guard) installed before
 
 Install the gem:
 
-```bash
-$ gem install guard-cucumber
-```
+    $ gem install guard-cucumber
 
 Add it to your `Gemfile`, preferably inside the test group:
 
-```ruby
-gem 'guard-cucumber'
-```
+    gem 'guard-cucumber'
 
 Add the default Guard::Cucumber template to your `Guardfile` by running this command:
 
-```bash
-$ guard init cucumber
-```
+    $ guard init cucumber
 
 ## Usage
 
@@ -38,13 +30,11 @@ Please read the [Guard usage documentation](https://github.com/guard/guard#readm
 
 Guard::Cucumber can be adapted to all kind of projects and comes with a default template that looks like this:
 
-```ruby
-guard 'cucumber' do
-  watch(%r{^features/.+\.feature$})
-  watch(%r{^features/support/.+$})                      { 'features' }
-  watch(%r{^features/step_definitions/(.+)_steps\.rb$}) { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'features' }
-end
-```
+    guard 'cucumber' do
+      watch(%r{^features/.+\.feature$})
+      watch(%r{^features/support/.+$})                      { 'features' }
+      watch(%r{^features/step_definitions/(.+)_steps\.rb$}) { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'features' }
+    end
 
 Expressed in plain English, this configuration tells Guard::Cucumber:
 
@@ -60,44 +50,39 @@ Please read the [Guard documentation](http://github.com/guard/guard#readme) for
 
 You can pass any of the standard Cucumber CLI options using the :cli option:
 
-```ruby
-guard 'cucumber', :cli => '-c --drb --port 1234 --profile guard' do
-end
-```
+    guard 'cucumber', :cli => '-c --drb --port 1234 --profile guard'
 
 Former `:color`, `:drb`, `:port` and `:profile` options are thus deprecated and have no effect anymore.
 
 ### List of available options
 
-```ruby
-:cli => '--profile guard -c'      # Pass arbitrary Cucumber CLI arguments, 
-                                  # default: '--no-profile --color --format progress --strict'
+    :cli => '--profile guard -c'      # Pass arbitrary Cucumber CLI arguments,
+                                      # default: '--no-profile --color --format progress --strict'
 
-:bundler => false                 # Don't use "bundle exec" to run the Cucumber command
-                                  # default: true
+    :bundler => false                 # Don't use "bundle exec" to run the Cucumber command
+                                      # default: true
 
-:rvm => ['1.8.7', '1.9.2']        # Directly run your features on multiple ruby versions
-                                  # default: nil
+    :rvm => ['1.8.7', '1.9.2']        # Directly run your features on multiple ruby versions
+                                      # default: nil
 
-:notification => false            # Don't display Growl (or Libnotify) notification
-                                  # default: true
+    :notification => false            # Don't display Growl (or Libnotify) notification
+                                      # default: true
 
-:all_after_pass => false          # Don't run all features after changed features pass
-                                  # default: true
+    :all_after_pass => false          # Don't run all features after changed features pass
+                                      # default: true
 
-:all_on_start => false            # Don't run all the features at startup
-                                  # default: true
+    :all_on_start => false            # Don't run all the features at startup
+                                      # default: true
 
-:keep_failed => false             # Keep failed features until them pass
-                                  # default: true
+    :keep_failed => false             # Keep failed features until they pass
+                                      # default: true
 
-:run_all => { :cli => "-p" }      # Override any option when running all specs
-                                  # default: {}
+    :run_all => { :cli => "-p" }      # Override any option when running all specs
+                                      # default: {}
 
-:change_format => 'pretty'        # Use a different cucumber format when running individual features
-                                  # This replaces the Cucumber --format option within the :cli option
-                                  # default: nil
-```
+    :change_format => 'pretty'        # Use a different cucumber format when running individual features
+                                      # This replaces the Cucumber --format option within the :cli option
+                                      # default: nil
 
 ## Cucumber configuration
 
@@ -117,9 +102,7 @@ If you want to configure Cucumber from Guard solely, then you should pass `--no-
 
 Since guard-cucumber version 0.3.2, the default `:cli` options are:
 
-```ruby
-:cli => '--no-profile --color --format progress --strict'
-```
+    :cli => '--no-profile --color --format progress --strict'
 
 This default configuration has been chosen to avoid strange behavior when mixing configurations form
 the cucumber.yml default profile with the guard-cucumber `:cli` option.
@@ -131,9 +114,7 @@ You can safely remove `config/cucumber.yml`, since all configuration is done in
 If you're using different profiles with Cucumber then you should create a profile for Guard in cucumber.yml,
 something like this:
 
-```
-guard: --format progress --strict --tags ~@wip
-```
+    guard: --format progress --strict --tags ~@wip
 
 Now you want to make guard-cucumber use that profile by passing '--profile guard' to the `:cli`.
 
@@ -142,30 +123,34 @@ Now you want to make guard-cucumber use that profile by passing '--profile guard
 To use Guard::Cucumber with [Spork](https://github.com/timcharper/spork), you should install
 [Guard::Spork](https://github.com/guard/guard-spork) and use the following configuration:
 
-```ruby
-guard 'spork' do
-  watch('config/application.rb')
-  watch('config/environment.rb')
-  watch(%r{^config/environments/.*\.rb$})
-  watch(%r{^config/initializers/.*\.rb$})
-  watch('spec/spec_helper.rb')
-end
-
-guard 'cucumber', :cli => '--drb --format progress --no-profile' do
-  watch(%r{^features/.+\.feature$})
-  watch(%r{^features/support/.+$})                      { 'features' }
-  watch(%r{^features/step_definitions/(.+)_steps\.rb$}) { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'features' }
-end
-```
+    guard 'spork' do
+      watch('config/application.rb')
+      watch('config/environment.rb')
+      watch(%r{^config/environments/.*\.rb$})
+      watch(%r{^config/initializers/.*\.rb$})
+      watch('spec/spec_helper.rb')
+    end
+
+    guard 'cucumber', :cli => '--drb --format progress --no-profile' do
+      watch(%r{^features/.+\.feature$})
+      watch(%r{^features/support/.+$})                      { 'features' }
+      watch(%r{^features/step_definitions/(.+)_steps\.rb$}) { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'features' }
+    end
 
 There is a section with alternative configurations on the [Wiki](https://github.com/netzpirat/guard-cucumber/wiki/Spork-configurations).
 
 ## Development
 
-- Source hosted at [GitHub](https://github.com/netzpirat/guard-cucumber)
-- Report issues and feature requests to [GitHub Issues](https://github.com/netzpirat/guard-cucumber/issues)
+- Documentation hosted at [RubyDoc](http://rubydoc.info/gems/guard-cucumber/frames).
+- Source hosted at [GitHub](https://github.com/netzpirat/guard-cucumber).
+- Report issues and feature requests to [GitHub Issues](https://github.com/netzpirat/guard-cucumber/issues).
+
+Pull requests are very welcome! Please try to follow these simple "rules", though:
 
-Pull requests are very welcome! Make sure your patches are well tested.
+- Please create a topic branch for every separate change you make.
+- Make sure your patches are well tested.
+- Update the README (if applicable).
+- Please **do not change** the version number.
 
 For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
 

data/lib/guard/cucumber.rb

@@ -3,30 +3,56 @@ require 'guard/guard'
 require 'cucumber'
 
 module Guard
+
+  # The Cucumber guard that gets notifications about the following
+  # Guard events: `start`, `stop`, `reload`, `run_all` and `run_on_change`.
+  #
   class Cucumber < Guard
 
     autoload :Runner, 'guard/cucumber/runner'
     autoload :Inspector, 'guard/cucumber/inspector'
 
-    def initialize(watchers=[], options={})
+    # Initialize Guard::Cucumber.
+    #
+    # @param [Array<Guard::Watcher>] watchers the watchers in the Guard block
+    # @param [Hash] options the options for the Guard
+    # @option options [String] :cli any arbitrary Cucumber CLI arguments
+    # @option options [Boolean] :bundler use bundler or not
+    # @option options [Array<String>] :rvm a list of rvm version to use for the test
+    # @option options [Boolean] :notification show notifications
+    # @option options [Boolean] :all_after_pass run all features after changed features pass
+    # @option options [Boolean] :all_on_start run all the features at startup
+    # @option options [Boolean] :keep_failed Keep failed features until they pass
+    # @option options [Boolean] :run_all run override any option when running all specs
+    # @option options [Boolean] :change_format use a different cucumber format when running individual features
+    #
+    def initialize(watchers = [], options = { })
       super
       @options = {
           :all_after_pass => true,
-          :all_on_start => true,
-          :keep_failed => true,
-          :cli => '--no-profile --color --format progress --strict'
+          :all_on_start   => true,
+          :keep_failed    => true,
+          :cli            => '--no-profile --color --format progress --strict'
       }.update(options)
 
-      @last_failed = false
+      @last_failed  = false
       @failed_paths = []
     end
 
+    # Gets called once when Guard starts.
+    #
+    # @return [Boolean] when the start was successful
+    #
     def start
       run_all if @options[:all_on_start]
     end
 
+    # Gets called when all specs should be run.
+    #
+    # @return [Boolean] when running all specs was successful
+    #
     def run_all
-      passed = Runner.run(['features'], options.merge(options[:run_all] || {}).merge(:message => 'Running all features'))
+      passed = Runner.run(['features'], options.merge(options[:run_all] || { }).merge(:message => 'Running all features'))
 
       if passed
         @failed_paths = []
@@ -35,21 +61,30 @@ module Guard
       end
 
       @last_failed = !passed
-      
+
       passed
     end
 
+    # Gets called when the Guard should reload itself.
+    #
+    # @return [Boolean] when reloading was successful
+    #
     def reload
       @failed_paths = []
-      
+
       true
     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)
       paths += @failed_paths if @options[:keep_failed]
-      paths = Inspector.clean(paths)
+      paths   = Inspector.clean(paths)
       options = @options[:change_format] ? change_format(@options[:change_format]) : @options
-      passed = Runner.run(paths, paths.include?('features') ? options.merge({ :message => 'Running all features' }) : options)
+      passed  = Runner.run(paths, paths.include?('features') ? options.merge({ :message => 'Running all features' }) : options)
 
       if passed
         # clean failed paths memory
@@ -62,12 +97,15 @@ module Guard
         # track whether the changed feature failed for the next change
         @last_failed = true
       end
-      
-      passed
     end
 
     private
 
+    # Read the failed features that from `rerun.txt`
+    #
+    # @see Guard::Cucumber::NotificationFormatter#write_rerun_features
+    # @return [Array<String>] the list of features
+    #
     def read_failed_features
       failed = []
 
@@ -79,6 +117,11 @@ module Guard
       failed
     end
 
+    # Change the `--format` cli option.
+    #
+    # @param [String] format the new format
+    # @return [Hash] the new options
+    #
     def change_format(format)
       cli_parts = @options[:cli].split(" ")
       cli_parts.each_with_index do |part, index|

data/lib/guard/cucumber/inspector.rb

@@ -1,8 +1,18 @@
 module Guard
   class Cucumber
+
+    # The inspector verifies of the changed paths are valid
+    # for Guard::Cucumber.
+    #
     module Inspector
       class << self
 
+        # Clean the changed paths and return only valid
+        # Cucumber features.
+        #
+        # @param [Array<String>] paths the changed paths
+        # @return [Array<String>] the valid feature files
+        #
         def clean(paths)
           paths.uniq!
           paths.compact!
@@ -12,24 +22,48 @@ module Guard
           paths
         end
 
-      private
+        private
 
+        # Tests if the file is the features folder.
+        #
+        # @param [String] file the file
+        # @return [Boolean] when the file is the feature folder
+        #
         def cucumber_folder?(path)
           path.match(/^\/?features/) && !path.match(/\..+$/)
         end
 
+        # Tests if the file is valid.
+        #
+        # @param [String] file the file
+        # @return [Boolean] when the file valid
+        #
         def cucumber_file?(path)
           cucumber_files.include?(path.split(':').first)
         end
 
+        # Scans the project and keeps a list of all
+        # feature files in the `features` directory.
+        #
+        # @see #clear_jasmine_specs
+        # @return [Array<String>] the valid files
+        #
         def cucumber_files
           @cucumber_files ||= Dir.glob('features/**/*.feature')
         end
 
+        # Clears the list of features in this project.
+        #
         def clear_cucumber_files_list
           @cucumber_files = nil
         end
 
+        # Checks if the given path is already contained
+        # in the paths list.
+        #
+        # @param [Sting] path the path to test
+        # @param [Array<String>] paths the list of paths
+        #
         def included_in_other_path?(path, paths)
           paths = paths.select { |p| p != path }
           paths.any? { |p| path.include?(p) && (path.gsub(p, '')).include?('/') }

data/lib/guard/cucumber/notification_formatter.rb

@@ -5,27 +5,52 @@ require 'cucumber/formatter/io'
 
 module Guard
   class Cucumber
+
+    # The notification formatter is a Cucumber formatter that Guard::Cucumber
+    # passes to the Cucumber binary. It writes the `rerun.txt` file with the failed features
+    # an creates system notifications.
+    #
+    # @see https://github.com/cucumber/cucumber/wiki/Custom-Formatters
+    #
     class NotificationFormatter
       include ::Cucumber::Formatter::Console
 
       attr_reader :step_mother
 
+      # Initialize the formatter.
+      #
+      # @param [Cucumber::Runtime] step_mother the step mother
+      # @param [String, IO] path_or_io the path or IO to the feature file
+      # @param [Hash] options the options
+      #
       def initialize(step_mother, path_or_io, options)
         @options = options
         @file_names = []
         @step_mother = step_mother
       end
 
+      # Notification after all features have completed.
+      #
+      # @param [Array[Cucumber::Ast::Feature]] features the ran features
+      #
       def after_features(features)
         notify_summary
         write_rerun_features if !@file_names.empty?
       end
 
+      # Before a feature gets run.
+      #
+      # @param [Cucumber::Ast::FeatureElement] feature_element
+      #
       def before_feature_element(feature_element)
         @rerun = false
         @feature_name = feature_element.name
       end
 
+      # After a feature gets run.
+      #
+      # @param [Cucumber::Ast::FeatureElement] feature_element
+      #
       def after_feature_element(feature_element)
         if @rerun
           @file_names << feature_element.file_colon_line
@@ -33,16 +58,28 @@ module Guard
         end
       end
 
+      # Gets called when a step is done.
+      #
+      # @param [String] keyword the keyword
+      # @param [Cucumber::StepMatch] step_match the step match
+      # @param [Symbol] status the status of the step
+      # @param [Integer] source_indent the source indentation
+      # @param [Cucumber::Ast::Background] background the feature background
+      #
       def step_name(keyword, step_match, status, source_indent, background)
         if [:failed, :pending, :undefined].index(status)
           @rerun = true
           step_name = step_match.format_args(lambda { |param| "*#{ param }*" })
+
           ::Guard::Notifier.notify step_name, :title => @feature_name, :image => icon_for(status)
         end
       end
 
       private
 
+      # Notify the user with a system notification about the
+      # result of the feature tests.
+      #
       def notify_summary
         icon, messages = nil, []
 
@@ -57,12 +94,19 @@ module Guard
         ::Guard::Notifier.notify messages.reverse.join(', '), :title => 'Cucumber Results', :image => icon
       end
 
+      # Writes the `rerun.txt` file containing all failed features.
+      #
       def write_rerun_features
         File.open('rerun.txt', 'w') do |f|
           f.puts @file_names.join(' ')
         end
       end
 
+      # Gives the icon name to use for the status.
+      #
+      # @param [Symbol] status the cucumber status
+      # @return [Symbol] the Guard notification symbol
+      #
       def icon_for(status)
         case status
           when :passed