story

This project provides an executable, named story, that can be used to run suites of rspec plain text user stories.

The command line runner expects a project layout like so:

  stories/stories/logging_in.story
  stories/stories/feature.story
  stories/stories/feature/topic.story

Given the path stories/stories/feature/topic.story, this story runner will automatically provide it with the following step groups when run:

  feature, topic, feature/topic

The step groups should be loaded from your helper, typically in stories/helper.rb with a line such as:

  Dir['steps/**/*.rb'].each { |f| require f }

To be clear, the file stories/steps/feature/topic.rb might contain something like:

  steps_for('feature/topic') do
    Given('...') do ... end
  end

You are not, however, limited to this naming scheme. It could just as well contain:

  steps_for('when topic within some feature') do ... end

And, provided your stories include that step group name, the steps will be available.

Command line usage

Command line arguments include:

  -R, --rails
    run stories as type RailsStory
    default: --no-rails

  -s, --step-group NAME
    add step groups which will be provided to every story run.
    specify multiple times to add more.
    default: NONE

  -H, --helper
    specify the path to the story helper file to load
    default: stories/helper

  -S, --story-dir
    specifies the root path for your plain text stories; this
    is stripped from path names before inferring step group names.
    default: stories/stories

  -O, --options
    specify a .opts file to load command line arguments from
    default: stories/story.opts is always loaded if present

  -h, --help
    display help

Specifying required steps inside the story

As the first line of a .story file, you can specify steps to be loaded in addition to those deduced from its pathname:

  # +steps: auth, data creation

When run, this story will expect to have step groups named ‘auth’ and ‘data creation’ available in the environment.

Configuration file

If the file stories/story.opts is present, or another file was specified with the command line option -O, then options are loaded from the file in the same manner as spec/spec.opts.

An example story.opts for a Rails project might be:

  --rails
  --step-group
  auth
  --step-group
  webrat

Any lines following a line containing ’—’ will be passed on to rspec’s option parser:

  --rails
  --
  --colour

Will run the stories with colours enabled. This feature is not yet available from the command line, and requires an rspec >= 1.1.4.

Credits

Bryan Helmkamp wrote the original version of this file, script/story, and posted it to the rspec-users mailing list. He gave his okay for the MIT license this thing rocks.