= StepSpecr

by Matthias Hennemeyer <mhennemeyer@gmail.com>

== Introduction

Stephelper 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

By running 
  $ script/generate stepspecr
a example_step and a example_step_spec are generated.
PROJECT_HOME/spec/steps/example_step_spec.rb is ready to run!

=== A rather trivial one

In a plaintext story the following step is needed:  
  Given 5 articles
Instead of 'just implement' and 'running the story as a test': write a spec:

in PROJECT_HOME/spec/steps/article_story_spec.rb

  require File.expand_path(File.dirname(__FILE__) + "/stepspecr_helper.rb")
  
  describe "Given $count articles" do
    it "should create 5 articles for count=5" do
      StepSpecr.run do
        steps_for :articles
        step "Given 5 articles"
        spec "Article.count.should >= 5"
      end
    end
  end
    
Running the example will perform the following actions:
  
1. It will generate a plaintext story file containing the following:
   Given 5 articles
   Then _spec_step_
2. It will generate a runnable story file:
     steps_for(:_spec_steps_) do
        # ...
       Then("_spec_step_") do
         Article.count.should >= 5  #<---- Here is the specification
       end
     end
   with_steps_for(:articles # ...
3. It will run the story
4. It will FAIL ... 

Now you're going to 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
  ...

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.setup do
         steps_for :resources
       end
     end
     
     it "should create the specified model" do
       StepSpecr.run do
         step "Given 1 specific_model"
         initial "class SpecificModel ; end ; SpecificModel.should_receive(:create)"
       end
     end
     
     it "should create the specified number of models" do
        StepSpecr.run do
          step "Given 5 specific_models"
          initial "class SpecificModel ; end ; SpecificModel.should_receive(:create).exactly(5).times"
        end
      end
     
     it "should create 17 lists for count=17, models=lists" do
       StepSpecr.run do
          step "Given 17 lists"
          spec "List.count.should >= 17"
        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
  $ ruby script/plugin stepspecr
  

Copyright (c) 2008 Matthias Hennemeyer, released under the MIT license