Some background links:

• “Introducing RBehave”:http://dannorth.net/2007/06/introducing-rbehave
• “User stories with RSpec’s Story Runner”:http://evang.eli.st/blog/2007/9/1/user-stories-with-rspec-s-story-runner
• “Story Runner in Plain English”:http://blog.davidchelimsky.net/articles/2007/10/21/story-runner-in-plain-english
• “Plain Text Stories: Part III”:http://blog.davidchelimsky.net/articles/2007/10/25/plain-text-stories-part-iii

Story Runner itself hasn’t officially been released and while it has been becoming more polished myself and a colleague (Drew Colthorp) wanted higher level acceptance tests in my ruby projects (including rails).

Story Runner also has two implementations (or at least APIs). The latest is the plain text Story Runner. This requires that for every story you have at least two files. One that is plain text for the customer to write and one that is a “matcher” file developers write. Information on this can be found “here”:http://blog.davidchelimsky.net/articles/2007/10/25/plain-text-stories-part-iii

The older version of Story Runner uses the original RBehave style syntax. Lots of blocks and lots of argument passing. There is also a bug in this implementation regarding sharing blocks given to story parts. But enough about rspec, this post is on a lighter weight and simpler Story Runner.

So here’s to a working and testing implementation of a Story Runner in test/unit.

test/unit Story Runner

To start, an example:

class EventCreationTest < ActionController::IntegrationTest
  fixtures :all

  Story "As a user I should be able to create an event so that others can RSVP and attend."

  Scenario "Creating an event unsuccessfully with insufficient input" do
    Given :a_user_at_the_create_an_event_page
    When :they_submit_the_create_an_event_form_with_insufficient_input
    Then :they_will_see_an_error_explanation
    And :they_will_see_the_create_an_event_page
  end 

   #
   # HELPERS
   #
   def a_user_at_the_create_an_event_page
       # ....
   end

   def submit_the_create_an_event_form_with_insufficient_input
       # ...
   end

   def see_an_error_explanation
       # ...
   end

   def see_the_create_an_event_page
      # ...
   end
end

Some important things to note on the structure:

• the Story takes a description of the story. It does NOT take a block.
• multiple Story’s can be defined in a file although I prefer organizing them in separate files
• all Scenario’s which follow a Story will belong to that Story.
• the Scenario takes a description of the particular scenario or acceptance test for a story. It does take a block.
• inside of a Scenario you describe the story parts. These are Given, When, Then, and And.

Some important things to note on the story part descriptions:

• Each story part can take a string or symbol description
• helper method calls are generated off from the story part description

Helper method calls are generated by taking the full story part description and then removing the leading word until a helper method is found. If there are no helper methods found then an exception is raised.

Some important things to note on the goals of this implementation:

• in theory customers write acceptance tests
• in practice developers translate customer desires into acceptance tests
• ideally the acceptance tests should be high level enough that a customer can read/write them
• since developers will most likely write these acceptance tests this implementation should allow for developer shortcuts
• this should just work on a test/unit project, projects updating to this shouldn’t have to convert or make changes up front to existing code

script/plugin install

script/plugin install \
  http://continuous.rubyforge.org/svn/tags/test_unit_story_runner-0.1.0

Final Thoughts

Before I forget you can do argument passing as well on story parts:

Scenario "a user successfully making a guess in the game" do
  Given :a_user_at_the_game
  When :they_make_a_guess_of, 20_000
  Then :they_will_win_a_car
end

This feature is there, but I would advocate only using it when it helps the readability of your tests.

This is a stable (tested) experiment. It’s a thin wrapper around the test/unit framework and it works with any Test::Unit::TestCase. The price to pay for higher level acceptance tests is now next to nothing so give it a shot.

This is the creation of a trip to Madison, WI where Drew and I had a chance to discuss and vent about the state of acceptance tests in Rails projects specifically. A few days later we had this implementation, and about a month later you’ve got this post…

Suggestions and feedbacks are warmly welcomed.

Happy rubying!