story

Unless you are still using the now deprecated rspec story runner, this project is useless to you. Cucumber’s command line interface is more than sufficient to do most of what this project provided.

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.