= StepSpecr
 
by Matthias Hennemeyer <mhennemeyer@gmail.com>
 
== Introduction
 
StepSpecr is a Rails plugin intended to be used with Rspec User Stories.
It provides a 'testing' framework for speccing Given/When/Then steps within Rspec examples. This lets you implement GWT-steps the BDD way.
 
 
== Examples
 
=== A rather trivial one
 
In a plaintext story the following step is needed:  
  Given 1 articles
Instead of 'just implement' and 'running the story as a test': write a spec:
 
in PROJECT_HOME/spec/steps/article_steps_spec.rb
 
  require File.expand_path(File.dirname(__FILE__) + "/stepspecr_helper.rb")
  
  describe "Given $count articles" do
    it "should create 1 articles for count=1" do
      class Article
      end
      Article.should_receive :create
      step_eval "Given 1 article", :articles
    end
  end
    
Running the example will perform the following actions:
  
1. It will (try to) collect the steps supplied to step_group :articles 
2. It will run the step
3. It will FAIL ...
 
  $  script/spec --format specdoc spec/steps/article_steps_spec.rb
 
Implement the step:
  
in PROJECT_HOME/stories/steps/article_steps.rb
 
  steps_for :articles do
    Given "$count articles" do |count|
      count.to_i.times { Article.create }
    end
  end
  
 
Run the example again and it should PASS.
 
=== A more complex example
 
You want a step that creates modelobjects that are specified in the story:
  Given 5 articles
  Given 1 post
  Given 17 lists
  ...
 
Using StepSpecr.step is a little bit more involved than plain step_eval but gives you 
a facility to configure the thing so that you can DRY it up.
This will be more than one example: (Just showing the description - BDD doesn't mean to write more than one example at a time)
 
   describe "Given $count $models" do
     before(:all) do 
       StepSpecr.configure do
         step_group :resources
       end
     end
     
     it "should create the specified model" do
       StepSpecr.spec "Given 1 specific_model" do
         before do 
           class SpecificModel
           end
           SpecificModel.should_receive(:create)
         end
       end
     end
     
     it "should create the specified number of models" do
        StepSpecr.spec "Given 5 specific_models" do
          before do
            class SpecificModel
            end
            SpecificModel.should_receive(:create).exactly(5).times
          end
        end
      end
     
     it "should create 17 lists for count=17, models=lists" do
       StepSpecr.spec "Given 17 lists" do
         before do
           class List
           end
           List.should_receive(:create).exactly(17).times
         end
       end
     end
   end
   
The implementation could look like this:
 
   steps_for :resources do
     Given "$count $models" do |count, name|
       klass = eval "#{name.singularize.camelize}"
       count.to_i.times { klass.create }
     end
   end
 
== REQUIREMENTS:
 
* Rspec >= 1.1.3
* rspec_on_rails
 
 
== INSTALL:
 
  $ ruby script/plugin install git://github.com/mhennemeyer/stepspecr.git
  $ script/generate stepspecr
  
 
Copyright (c) 2008 Matthias Hennemeyer, released under the MIT license