turnip 0.2.0 → 0.3.0

data/.gitignore

@@ -2,4 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
-.rvmrc
+.rvmrc
+.rbx

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+ - 1.9.2
+ - 1.9.3
+ - ruby-head
+ - rbx-2.0

data/README.md

@@ -1,5 +1,7 @@
 # Turnip
 
+[![Build Status](https://secure.travis-ci.org/jnicklas/turnip.png)](http://travis-ci.org/jnicklas/turnip)
+
 Turnip is a [Gherkin](https://github.com/cucumber/cucumber/wiki/Gherkin)
 extension for RSpec. It allows you to write tests in Gherkin and run them
 through your RSpec environment. Basically you can write cucumber features in
@@ -28,6 +30,17 @@ exist), and add the following line:
 -r turnip
 ```
 
+## Development
+
+* Source hosted at [GitHub](http://github.com/jnicklas/turnip).
+* Please direct questions, discussion or problems to the [mailing list](http://groups.google.com/group/ruby-turnip).
+  Please do not open an issue on GitHub if you have a question.
+* If you found a reproducible bug, open a [GitHub Issue](http://github.com/jnicklas/turnip/issues) to submit a bug report.
+* Please do not contact any of the maintainers directly, unless you have found a security related issue.
+
+Pull requests are very welcome (and even better than bug reports)!
+Please create a topic branch for every separate change you make.
+
 ## Compatibility
 
 Turnip does not work on Ruby 1.8.X.
@@ -60,9 +73,33 @@ Yes, that's really it.
 
 ## Defining steps
 
-You might want to define some steps. You can put them anywhere. Turnip
-automatically requires your `spec_helper`, so you can add them there or put
-them in separate files (recommended). Define them like this:
+You might want to define some steps.  Just as in cucumber, your step files
+should be named `[something]_steps.rb`.  All files ending in `*steps.rb`
+will be automatically required if they are under the Turnip step directory.
+
+The default step directory for Turnip is `spec/`.  You can override this
+in your `spec_helper` by setting `Turnip::Config.step_dirs`.  For example:
+
+``` ruby
+# spec/spec_helper.rb
+RSpec.configure do |config|
+  Turnip::Config.step_dirs = 'examples'
+  Turnip::StepLoader.load_steps
+end
+```
+
+This would set the Turnip step dirs to `examples/` and automatically load
+all `*steps.rb` files anywhere under that directory.
+
+The steps you define in your step files can be global or they can be scoped
+to certain features (or scenarios)...
+
+### Global steps
+Global steps can be used by any feature/scenario you write since they are
+unscoped.  The names must be unique across all step files in the global
+namespace.
+
+Define them in your step file like this:
 
 ``` ruby
 step "there is a monster" do
@@ -96,89 +133,204 @@ end
 
 That will match both "there is X monster" or "there are X monsters".
 
-## Defining placeholders
+You can also define custom step placeholders.  More on that later.
+
+### Scoped steps
+Scoped steps help you to organize steps that are specific to
+certain features or scenarios.  They only need to be unique within
+the scopes being used by the running scenario.
 
-But what if you want to be more specific in what to match in those
-placeholders, and it is bothersome to have to constantly cast them to the
-correct type. Turnip's placeholder solve both problems, like this:
+To define scoped steps use `steps_for`:
 
 ``` ruby
-step "there are :count monsters" do |count|
-  count.times { Monster.new(name) }
+steps_for :interface do
+  step "I do it" do
+    ...
+  end
 end
 
-placeholder :count do
-  match /\d+/ do |count|
-    count.to_i
+steps_for :database do
+  step "I do it" do
+    ...
   end
+end
+```
 
-  match /no/ do
-    0
+Even though the step is named the same, you can now use it in
+your feature files like so:
+
+``` cucumber
+@interface
+Scenario: do it through the interface
+
+@database
+Scenario: do it through the database
+```
+
+Note that this would still cause an error if you tagged a Scenario
+with both `@interface` and `@database` at the same time.
+
+Scoped steps are really just Ruby modules under the covers so you
+can do anything you'd normally want to do including defining
+helper/utility methods and variables.  Check out
+[features/alignment_steps.rb](https://github.com/jnicklas/turnip/blob/master/examples/alignment_steps.rb)
+and
+[features/evil_steps.rb](https://github.com/jnicklas/turnip/blob/master/examples/evil_steps.rb) for basic examples.
+
+### Reusing steps
+When using scoped steps in Turnip, you can tell it to also include steps
+defined in another `steps_for` block.  The syntax for that is `use_steps`:
+
+``` ruby
+# dragon_steps.rb
+steps_for :dragon do
+  use_steps :knight
+
+  attr_accessor :dragon
+
+  def dragon_attack
+    dragon * 10
+  end
+
+  step "there is a dragon" do
+    self.dragon = 1
+  end
+
+  step "the dragon attacks the knight" do
+    knight.attacked_for(dragon_attack)
+  end
+end
+
+# red_dragon_steps.rb
+steps_for :red_dragon do
+  use_steps :dragon
+
+  attr_accessor :red_dragon
+
+  def dragon_attack
+    attack = super
+    if red_dragon
+      attack + 15
+    else
+      attack
+    end
+  end
+
+  step "the dragon breathes fire" do
+    self.red_dragon = 1
   end
 end
 ```
 
-You would now be able to use these steps like this:
+
+In this example we are making full use of Ruby's modules including using super
+to call the included module's version of `dragon_attack`, for example with the
+following feature file:
 
 ``` cucumber
-Given there are 4 monsters
-Given there are no monsters
+Feature: Red Dragons are deadly
+
+  @dragon
+  Scenario:
+    Given there is a dragon
+    And there is a knight
+    When the dragon attacks the knight
+    Then the knight is alive
+
+  @red_dragon
+  Scenario:
+    Given there is a dragon
+    And the dragon breathes fire
+    And there is a knight
+    When the dragon attacks the knight
+    Then the knight is dead
 ```
 
-Placeholders can extract matches from the regular expressions as well. For
-example:
+### Auto-included steps
+By default, Turnip will automatically make available any steps defined in
+a `steps_for` block with the same name as the feature file being run.  For
+example, given this step file:
 
 ``` ruby
-placeholder :monster do
-  match /(blue|green|red) (furry|bald) monster/ do |color, hair|
-    Monster.new(color, hair)
+# user_signup_steps.rb
+steps_for :user_signup do
+  step "I am on the homepage" do
+    ...
+  end
+
+  step "I signup with valid info" do
+    ...
+  end
+
+  step "I should see a welcome message" do
   end
 end
 ```
 
-These regular expressions must not use anchors, e.g. `^` or `$`. They may not
-contain named capture groups, e.g. `(?<color>blue|green)`.
+Then the following feature file would run just fine even though we
+did not explicitly tag it with `@user_signup`.
 
-## Specific steps
+``` cucumber
+# user_signup.feature
+Feature: A user can signup
+  Scenario: with email address
+    Given I am on the homepage
+    When I signup with valid info
+    Then I should see a welcome message
+```
+
+Note that the `steps_for :user_signup` did not technically have to
+appear in the user_signup_steps.rb file; it could have been located
+in any `steps.rb` file that was autoloaded by Turnip.
+
+This feature can be turned off using the `Turnip::Config.autotag_features`
+option if desired.
 
-Sometimes you might want to limit where steps are matched. Turnip allows you to
-do this, through the `:for` option on your steps:
+## Custom step placeholders
+Do you want to be more specific in what to match in your step
+placeholders?  Do you find it bothersome to have to constantly cast them to the
+correct type?  Turnip supports custom placeholders to solve both problems, like this:
 
 ``` ruby
-step "I do it", :for => :interface do
-  click_link('Do it')
+step "there are :count monsters" do |count|
+  count.times { Monster.new(name) }
 end
 
-step "I do it", :for => :database do
-  Do.it!
+placeholder :count do
+  match /\d+/ do |count|
+    count.to_i
+  end
+
+  match /no/ do
+    0
+  end
 end
 ```
 
-Not you can use tags in your feature files to decide which step is going to get
-run:
+You would now be able to use these steps like this:
 
 ``` cucumber
-@interface
-Scenario: do it through the interface
-
-@database
-Scenario: do it through the database
+Given there are 4 monsters
+Given there are no monsters
 ```
 
-If you have many steps for the same tag, you can use the `steps_for` helper:
+Placeholders can extract matches from the regular expressions as well. For
+example:
 
 ``` ruby
-steps_for :interface do
-  step "I do it" do
-    ...
+placeholder :monster do
+  match /(blue|green|red) (furry|bald) monster/ do |color, hair|
+    Monster.new(color, hair)
   end
 end
 ```
 
+These regular expressions must not use anchors, e.g. `^` or `$`. They may not
+contain named capture groups, e.g. `(?<color>blue|green)`.
+
 ## Using with Capybara
 
-Just require `turnip/capybara`, either in your `spec_helper` or by
-adding `-r turnip/capybara` to your `.rspec` file. You can now use the
+Just require `turnip/capybara` in your `spec_helper`. You can now use the
 same tags you'd use in Cucumber to switch between drivers e.g.
 `@javascript` or `@selenium`. Your Turnip features will also be run
 with the `:type => :request` metadata, so that Capybara is included and

data/Rakefile

@@ -1 +1,9 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+desc "Run all examples"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = %w[--color]
+end
+
+task :default => :spec

data/examples/alignment_steps.rb

@@ -0,0 +1,7 @@
+steps_for :alignment do
+  attr_accessor :alignment
+
+  step "that alignment should be :alignment" do |expected_alignment|
+    alignment.should eq(expected_alignment)
+  end
+end

data/examples/autoload_steps.feature

@@ -0,0 +1,5 @@
+Feature: Auto-loaded steps
+  
+  @scenario_tag
+  Scenario:
+    Given an auto-loaded step is available

data/examples/autoload_steps.rb

@@ -0,0 +1,5 @@
+steps_for :autoload_steps do
+  step 'an auto-loaded step is available' do
+    true.should be
+  end
+end

data/examples/dragon_steps.rb

@@ -0,0 +1,17 @@
+steps_for :dragon do
+  use_steps :knight
+
+  attr_accessor :dragon
+
+  def dragon_attack
+    dragon * 10
+  end
+
+  step "there is a dragon" do
+    self.dragon = 1
+  end
+
+  step "the dragon attacks the knight" do
+    knight.attacked_for(dragon_attack)
+  end
+end

data/examples/evil_steps.rb

@@ -0,0 +1,7 @@
+steps_for :evil do
+  use_steps :alignment
+
+  step "the monster has an alignment" do
+    self.alignment = 'Evil'
+  end
+end

data/examples/knight_steps.rb

@@ -0,0 +1,29 @@
+steps_for :knight do
+  attr_accessor :knight
+
+  class Knight
+    def initialize
+      @hp = 20
+    end
+
+    def alive?
+      @hp > 0
+    end
+
+    def attacked_for(amount)
+      @hp -= amount
+    end
+  end
+
+  step "there is a knight" do
+    self.knight = Knight.new
+  end
+
+  step "the knight is alive" do
+    knight.should be_alive
+  end
+
+  step "the knight is dead" do
+    knight.should_not be_alive
+  end
+end

data/examples/more_steps.rb

@@ -0,0 +1,7 @@
+step "there are :count monkeys with :color hair" do |count, color|
+  @monkeys = Array.new(count) { color }
+end
+
+step "there should be 3 monkeys with blue hair" do
+  @monkeys.should == [:blue, :blue, :blue]
+end

data/examples/neutral_steps.rb

@@ -0,0 +1,7 @@
+steps_for :neutral do
+  use_steps :alignment
+
+  step "the monster has an alignment" do
+    self.alignment = 'Neutral'
+  end
+end

data/examples/red_dragon_steps.rb

@@ -0,0 +1,18 @@
+steps_for :red_dragon do
+  use_steps :dragon
+
+  attr_accessor :red_dragon
+
+  def dragon_attack
+    attack = super
+    if red_dragon
+      attack + 15
+    else
+      attack
+    end
+  end
+
+  step "the dragon breathes fire" do
+    self.red_dragon = 1
+  end
+end