RSpec stories introduction

I have played a bit with RSpec specs and now want to check out stories.
note that there is no generator for rspec stories pre se (unless I
to miss all references to one ) and that the only directory relating to
stories added by installing rspec is ./stories itself.

The documentation at seems to presume a great deal of prior
knowledge. What I am looking for is a guided tour of what should go
and how each file should be called to implement stories.

For the moment I have placed everything in ./stories, although I am
certain that this is not the way to go.

I have created a file called “new_job.txt” in ./stories that contains

Story: open a new job
As an authorized user
I want to open a new job
So that I can do work
For a client

Scenario: client is active
Given client exists in database
And client status is active
When I add a new job
Then a job number is automatically assigned
And a job_parties entry is added for job and client with type “bill”
And job_parties status is set to “quote”

Scenario: client is held for administrative approval


I infer that I should also create a file called new_job.rb in stories
that it should contain:

with_steps_for :new_jobs_steps do
run ‘./new_job.txt’

Then I believe that I require yet another file called “new_job_steps.rb”
that has code that looks somewhat like this:

steps_for(:new_job_steps) do
Given “client exists in database” do
Client.destroy_all “short_name == ‘test client exists’”
Client.create!(:short_name => ‘test client exists’,
:status => ‘active’)

and at this point I am lost. Do I really need more than one step file,
say one or more to create the test client with the necessary attributes
and another to add the job and perhaps a third to create an authorized
user login? Does that mean that new_job.rb should look like this:

with_steps_for :login, :client_active, :new_jobs_steps do
run ‘./new_job.txt’

Can someone show me how they would wire this together? and with what
directories and file names that they would use? I am having a deal of
trouble getting my head wrapped around this approach.

*** E-Mail is NOT a SECURE channel ***
James B. Byrne mailto:[email protected]
Harte & Lyne Limited
9 Brockley Drive vox: +1 905 561 1241
Hamilton, Ontario fax: +1 905 561 0757
Canada L8E 3C3

Check out the UserStories video on PeepCode.
Cost = $9US - a bargain with your strong currency.

Cheers, Andy

to miss all references to one ) and that the only directory relating to
stories added by installing rspec is ./stories itself.

I had a bit of trouble with this as well, and here’s what I’ve come up

 „€€€vinfo

Lib contains the project, under the vinfo folder (that’s the project
name, substitute freely), organized like any other ruby module.
Spec contains specs, module_spec.rb, etc.
Stories contains an all.rb, which sets up the local search paths and
loads all story runners from the stories\stories folder. Stories also
contain a helper.rb which loads all steps and helper modules from steps
and helpers.
RUBYLIB points to my lib folder above when developing.

Dir[File.join(File.dirname(FILE), “stories”, “*.rb”)].each do |file|
require File.join(File.dirname(file), File.basename(file))

require ‘rubygems’
Dir[File.dirname(FILE) + “/helpers//*.rb"].each do |file|
require File.join(File.dirname(file), File.basename(file))
Dir[File.dirname(FILE) + "/steps/
/*.rb”].each do |file|
require File.join(File.dirname(file), File.basename(file))
def runStory file
run File.expand_path(file).gsub(".rb", “.story”)

require File.join(File.dirname(FILE), ‘…’, ‘helper’)
with_steps_for(:versiontool) do
runStory FILE

Then the steps are defined just as you describe in the various
steps*.rb files with utility code in the helpers*.rb files.

I have no idea if it’s the best way to set things up, but it works for
me. I’ve got a Rakefile in the root to run specs, stories, or all.


require ‘rubygems’
require ‘rcov/rcovtask’
require ‘spec/rake/spectask’

task :default => [:rcov_vinfo]
task :rcov_vinfo => [:spec, :stories]

desc “Run the unit tests with rcovrt.” do |t|
html = ‘…/doc/vinfo_specs.html’
t.warning = true
t.rcov_dir = ‘…/doc/coverage’
t.rcov = true
t.spec_opts = ["–color", “–format”, “progress”, “–format”,

desc “Run all stories”
task :stories do
html = ‘…/doc/vinfo_stories.html’
ruby “stories/all.rb --color --format plain --format

Hope this helps,

On 15 Jan 2008, at 09:00, Andreas Axelsson wrote:

I had a bit of trouble with this as well, and here’s what I’ve come
up with:

We use something fairly similar to Andreas’ method here. For
reference, here’s a post from last month by David on how he organises
his stories by feature:

It’s important to note though that there isn’t a ‘right way’ agreed yet.


Sorry, but the formatting seems to have gone bad below. You’ll most
surely figure out how to fix it though.


I can get to the RSpec list through ruby-forum. Yes! The things you
discover googling for help!

I followed the advice to go to, which was somewhat ironic
because that is where I started to look last week, before episode 18 for
RSpec-Stories was released. However, better late than never.

So I have followed the video through to the end, twice, and have a much
better idea of where I am going now. I added fixture_replacement to my
project as well.

I have yet to deeply consider what directory structure makes sense for
stories and their associated steps scripts, so I will leave everything
in ./stories for now. I have adopted a recommended practice of calling
things in the form X_story.txt and X_step.rb however.

The rake file example given above is very helpful. Thanks!

I wrote up a primitive aide memorie for stories and steps which I will
post here when I have more confidence that it actually describes what is

similarly, here’s my write up: