Getting Started with Story Runner

1. Decide a directory structure and fill out helper.rb

Presently there isn't a stories generator or established conventions for arranging your directories. I create a stories/ subfolder that contains subfolders for each set of features or parts of the site that I'm storying.

stories/
├─── steps/
│ └─── bar_steps.rb
├─── stories/
│ ├─── foo/
│ │ ├─── a_foo_story
│ │ ├─── a_foo_story.rb
│ │ ├─── another_foo_story
│ │ └─── another_foo_story.rb

├─── all.rb
└─── helper.rb

The helper.rb file needs some help finding your stuff. Here's how I've fleshed it out.

File: stories/helper.rb:

ENV["RAILS_ENV"] = "test"
require File.expand_path(File.dirname(__FILE__) + "/../config/environment")
require 'spec/rails/story_adapter'

Dir['stories/steps/**/*.rb'].each do |steps_file|
   require steps_file
end

# add extra include's and helper methods here
include FixtureReplacement

2. Write a short text story

This is just an example, of course.

File: stories/stories/users/a_user_logs_in

Story: a user logs in

    As a user on the site

    I log in

    So I can do cool stuff

Scenario: I log in and see a welcome message

    Given a registered user John

    When I log in as John

    Then the browser should show "Welcome John!"

3. Write an rb script for the story

File: stories/stories/users/a_user_logs_in.rb

require File.join(File.dirname(__FILE__), "../../helper")

with_steps_for :misc do

   run File.expand_path(__FILE__).gsub(".rb",""), :type => RailsStory

end

For other stories, just copy this file, and add/change the steps
groups as required. The rest of the file is unchanged (it gets the
text story filename from its own name.)

And run it:

$ ruby stories/stories/users/a_user_logs_in.rb

should show 1 scenarios: 0 succeeded, 0 failed, 1 pending

4. Code the Steps

To start, I put all my steps into a "miscellaneous" steps file until
patterns emerge when I'll separate them out into different steps files

File: stores/steps/misc_steps.rb

steps_for(:misc) do

  Given "a registered user $login" do |login|

    @user = create_user( :login => login )

  end

  When "I log in as $login" do |login|

    post_via_redirect '/login', :login => login, :password => 'secret'

    response.should be_success

    session[:user].should == @user.id

  end

  Then "the browser should show $text" do |text|

    response.should have_text(text)

  end
end

And run it

$ ruby stories/stories/users/a_user_logs_in.rb

or

$ ruby stories/all.rb