Executable Code Examples

RSpec provides a Domain Specific Language with which you can express executable examples of the expected behaviour of your code.

Imagine that you were talking to a customer requesting software for her bank. Part of that conversation might well look like this:

You:      Describe an account when it is first created.
Customer: It should have a balance of $0.

Here’s how we express that conversation in RSpec:

describe Account, "when first created" do
  it "should have a balance of $0" do
    ...
  end
end

The describe() method returns an ExampleGroup class, which contains a group of examples of a particular behaviour of the system that you wish to describe.

The it() method returns an instance of the ExampleGroup in which that example is run.

When you run this example, RSpec can provide a report like this:

Account when first created
- should have a balance of $0

before() and after()

You can use before() and/or after() to define code that executes before and after each example or only once per ExampleGroup:

describe Thing do
  before(:all) do
    # This is run once and only once, before all of the examples
    # and before any before(:each) blocks.
  end

  before(:each) do
    # This is run before each example.
  end

  before do
    # :each is the default, so this is the same as before(:each)
  end

  it "should do stuff" do
    ...
  end

  it "should do more stuff" do
    ...
  end

  after(:each) do
    # this is after each example
  end
  
  after do
    # :each is the default, so this is the same as after(:each)
  end

  after(:all) do
    # this is run once and only once after all of the examples
    # and after any after(:each) blocks
  end
  
end

Warning: The use of before(:all) and after(:all) is generally discouraged because it introduces dependencies between the Examples. Still, it might prove useful for very expensive operations if you know what you are doing.

Helper Methods

You can write helper methods directly within an Example Group:

describe "..." do

  it "..." do
    helper_method
  end
  
  def helper_method
    ...
  end

end

Reusable Helper Methods

You can include helper methods in multiple ExampleGroups by expressing them within a module, and then including that module in your ExampleGroup:

module AccountExampleHelperMethods
  def helper_method
    ...
  end
end

describe "A new account" do
  include AccountExampleHelperMethods
  before do
    @account = Account.new
  end

  it "should have a balance of $0" do
    helper_method
    @account.balance.should eql(Money.new(0, :dollars))
  end
end

Shared Example Groups

You can create shared example groups and include those groups into other groups.

Suppose you have some behavior that applies to all editions of your product, both large and small.

First, factor out the “shared” behavior:

shared_examples_for "all editions" do
  it "should behave like all editions" do
  end
end

then when you need define the behavior for the Large and Small editions,
reference the shared behavior using the it_should_behave_like()
method.

describe "SmallEdition" do
  it_should_behave_like "all editions"

  it "should also behave like a small edition" do
  end
end

describe "LargeEdition" do
  it_should_behave_like "all editions"

  it "should also behave like a large edition" do
  end
end

it_should_behave_like will search for an ExampleGroup by its
description string, in this case, “all editions”

All of the following are included from a shared group:

Shared example groups may not extend classes.

Multiple shared example groups may be referenced in one (non-shared) group.

Shared example groups may be included in other shared groups:

shared_examples_for "All Employees" do
  it "should be payable" do
    @employee.should respond_to(:calculate_pay)
  end
end

shared_examples_for "All Managers" do
  it_should_behave_like "All Employees"
  it "should be bonusable" do
    @employee.should respond_to(:apply_bonus)
  end
end

describe Officer do
  before(:each) do
    @employee = Officer.new
  end

  it_should_behave_like "All Managers"

  it "should be optionable" do
    @employee.should respond_to(:grant_options)
  end
end

$ spec officer_spec.rb

Officer
- should be payable
- should be bonusable
- should be optionable

Pending Examples

There are three ways to mark an example as “pending.”

Leave out the block:

it "should say foo"

The output will say PENDING (Not Yet Implemented).

Use the pending method with no block:

it "should say foo" do
  pending("get the vocal chords working")
  subject.should say("foo")
end

The output will say PENDING (get the vocal chords working).

Use the pending method with a block:

it "should say foo" do
  pending("get the vocal chords working") do
    subject.should say("foo")
  end
end

The output will say PENDING (get the vocal chords working), and the example will fail telling you to it is FIXED as soon as the body of the block raises no errors.