= 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