No commit activity in last 3 years
No release in over 3 years
There's a lot of open issues
A minimal implementation of integration testing within RSpec. Allows you to build sequential specs, each with a description, but where state is maintained between tests and before/after actions are only triggered at the beginning and end of the entire sequence. Cool things you can do with this: * Build multi-step user stories in plain RSpec syntax. Locate the point of failure quickly, and break up large integrations into sensible steps * Speed up groups of related tests by running your factories only once before the whole group.


>= 0.4.0
~> 4.11.1


< 3.99, >= 3.0
 Project Readme

RSpec Steps

( or: why would I want to relearn how to write specs? )

RSpec Steps allows you to chain examples into a series of steps that run in sequence and which stop when a step fails. It's often incredibly useful to be able to aseemble a series of tests that should all pass, but where completely isolating them is less than sensible.

( RSpec Steps has gone on with the tide of progress - it only supports RSpec 3.x. If you need Rspec 2 suport, check out two-step: https://github.com/LRDesign/two-step )

One excellent example is web site integration tests. With RSpec steps you can do:

RSpec::Steps.steps "Login and change password" do
  it "should show the login form" do
    visit root
    page.should have_text "Login"

  it "should successfully log in" do
    fill_in :name, "Johnny User"
    click "Login"
    page.should have_text "Welcome, Johnny!"

  it "should load the password change form" do
    click "My Settings"
    click "Update Password"
    page.should have_selector("form#update_password")

  it "should change the user's password successfully" do
    fill_in :password, "foobar"
    fill_in :password_confirmation, "foobar"
    click "Change Password"
    page.should have_text "Password changed successfully!"
    User.find_by_name("Johnny User").valid_password?("foobar").should be_true

The examples above will be run in order. State is preserved between examples inside a "steps" block: any DB transactions will not roll back until the entire sequence has been complete.

If any example inside the "steps" block fails, all remaining steps will be marked pending and therefore skipped.


RSpec's philosophy is that all examples should be completely independent. This is a great philosophy for most purposes, and we recommend you stick to it in almost all cases. BUT, that complete separation of examples really sucks when you're trying to write long stories involving many requests. You are usually stuck with three choices:

  1. Write a sequence of examples, each of which repeats the behavior of all previous examples. Downside: horrendously inefficient.
  2. Write a single huge example which performs the entire story. Downside: only one description, no independent reporting of the steps of the story.
  3. Use Cucumber. Downside: We agree totally with this guy: http://bit.ly/dmXqnY

RSpec-steps intentionally breaks RSpec's "independent" philosophy to let us get the only thing we really want from Cucumber - the ability to execute some examples in sequence, and skip subsequent steps after a failure.

Caveats and cautions

Don't call "describe" inside of "steps". As of 2.0, this is an error.

As of 2.0, Steps no longer automatically adds its DSL to the top level. If you want that behavior (especially if you're updating an older project) add:

require 'rspec-steps/monkeypatching'

to e.g. spec_helper.rb.

If you're using RSpec-Steps with Rails (for instance, with Capybara), you will absolutely need to make sure you have transactional fixtures off. Otherwise, you'll experience problems where the tests and the application appear to see completely different databases.

While Steps 2.0 retains it's shift in lifecycle hooks (:each become :all, there's a :step hook), this shift no longer applies to config.before et al -- you'll need to use config.before :each to run around each step. This is the primary change to the Steps interface that called for a major version bump.

If you're migrating a project from a previous version: be sure that any dependency on Waterpig is at least at 0.12. Then remove any before :step calls in spec support files.

Advanced stuff: shared steps

If you have (for example) two user stories that share the same first N steps but then diverge, you can DRY your code out with shared_steps blocks, like so:

   shared_steps "For a logged-in user" do
     it "should have login form" do
       visit root
       page.should have_selector "form#login"

     it "should log the user in" do
       fill_in :name, "Johnny User"
       page.should have_text "Welcome, Johnny!"

   steps "updating password" do
     perform_steps "For a logged-in user"

     it "should update the password" do

   steps "uploading a profile picture" do
     perform_steps "For a logged-in user"

     it "should upload a picture" do

Versions and Dependencies

The goal is to try to be compatible with as many versions of RSpec 3.x as possible.

We make good use of Travis to check compatibility, however. You can check what versions of RSpec and Ruby RSpec-Steps works with here: https://travis-ci.org/LRDesign/rspec-steps