Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
RSpec runner and formatters
branch: master
Failed to load latest commit information.
benchmarks benchmark demonstrating that `#keys.each` performs marginally better …
exe Drop the custom load error message in exe/rspec.
features Beef up tests for when rspec-expectations is not available.
lib/rspec Merge pull request #1887 from rspec/fix-rake-task-windows-escaping
script Lower JRuby coverage threshold.
spec Merge pull request #1887 from rspec/fix-rake-task-windows-escaping
.document doc/file listings/configs
.gitignore Ignore .rspec-local.
.rspec Require spec_helper only once from .rspec.
.rubocop.yml Update `rspec --help` to include more detail about filtering.
.rubocop_rspec_base.yml Updated travis build scripts (from rspec-dev)
.travis.yml Updated travis build scripts (from rspec-dev)
.yardopts Move filtering docs to a place where YARD will actually render them. Add missing paren. cleanup white space Improve doc formatting.
Gemfile Test::Unit is not bundled in ruby 2.2.
Gemfile-custom.sample ruby-prof 0.13 (in Gemfile-custom.sample)
Guardfile dev: use regexps in Guardfile
License.txt Update authors and copyright. Include details on how to run against `master`.
Rakefile Add support for relish staging environment.
appveyor.yml Updated travis build scripts (from rspec-dev)
cucumber.yml Add some regression tests for some popular custom formatter gems.
maintenance-branch Updated travis build scripts (from rspec-dev)
rspec-core.gemspec Stop using aruba’s removed `regexp`.

rspec-core Build Status Code Climate

rspec-core provides the structure for writing executable examples of how your code should behave, and an rspec command with tools to constrain which examples get run and tailor the output.


gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
gem install rspec-core # for rspec-core only
rspec --help

Want to run against the master branch? You'll need to include the dependent RSpec repos as well. Add the following to your Gemfile:

%w[rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib|
  gem lib, :git => "git://{lib}.git", :branch => 'master'

basic structure

RSpec uses the words "describe" and "it" so we can express concepts like a conversation:

"Describe an order."
"It sums the prices of its line items."
RSpec.describe Order do
  it "sums the prices of its line items" do
    order =
    order.add_entry( =>
      :price =>, :USD)
    order.add_entry( =>
      :price =>, :USD),
      :quantity => 2
    expect( eq(, :USD))

The describe method creates an ExampleGroup. Within the block passed to describe you can declare examples using the it method.

Under the hood, an example group is a class in which the block passed to describe is evaluated. The blocks passed to it are evaluated in the context of an instance of that class.

nested groups

You can also declare nested nested groups using the describe or context methods:

RSpec.describe Order do
  context "with no items" do
    it "behaves one way" do
      # ...

  context "with one item" do
    it "behaves another way" do
      # ...


You can declare example groups using either describe or context. For a top level example group, describe and context are available off of RSpec. For backwards compatibility, they are also available off of the main object and Module unless you disable monkey patching.

You can declare examples within a group using any of it, specify, or example.

shared examples and contexts

Declare a shared example group using shared_examples, and then include it in any group using include_examples.

RSpec.shared_examples "collections" do |collection_class|
  it "is empty when first created" do
    expect( be_empty

RSpec.describe Array do
  include_examples "collections", Array

RSpec.describe Hash do
  include_examples "collections", Hash

Nearly anything that can be declared within an example group can be declared within a shared example group. This includes before, after, and around hooks, let declarations, and nested groups/contexts.

You can also use the names shared_context and include_context. These are pretty much the same as shared_examples and include_examples, providing more accurate naming when you share hooks, let declarations, helper methods, etc, but no examples.


rspec-core stores a metadata hash with every example and group, which contains their descriptions, the locations at which they were declared, etc, etc. This hash powers many of rspec-core's features, including output formatters (which access descriptions and locations), and filtering before and after hooks.

Although you probably won't ever need this unless you are writing an extension, you can access it from an example like this:

it "does something" do
  expect(example.metadata[:description]).to eq("does something")


When a class is passed to describe, you can access it from an example using the described_class method, which is a wrapper for example.metadata[:described_class].

RSpec.describe Widget do
  example do
    expect(described_class).to equal(Widget)

This is useful in extensions or shared example groups in which the specific class is unknown. Taking the collections shared example group from above, we can clean it up a bit using described_class:

RSpec.shared_examples "collections" do
  it "is empty when first created" do
    expect( be_empty

RSpec.describe Array do
  include_examples "collections"

RSpec.describe Hash do
  include_examples "collections"

the rspec command

When you install the rspec-core gem, it installs the rspec executable, which you'll use to run rspec. The rspec command comes with many useful options. Run rspec --help to see the complete list.

store command line options .rspec

You can store command line options in a .rspec file in the project's root directory, and the rspec command will read them as though you typed them on the command line.

autotest integration

rspec-core no longer ships with an Autotest extension, if you require Autotest integration, please use the rspec-autotest gem and see rspec/rspec-autotest for details

get started

Start with a simple example of behavior you expect from your system. Do this before you write any implementation code:

# in spec/calculator_spec.rb
RSpec.describe Calculator do
  describe '#add' do
    it 'returns the sum of its arguments' do
      expect(, 2)).to eq(3)

Run this with the rspec command, and watch it fail:

$ rspec spec/calculator_spec.rb
./spec/calculator_spec.rb:1: uninitialized constant Calculator

Implement the simplest solution:

# in lib/calculator.rb
class Calculator
  def add(a,b)
    a + b

Be sure to require the implementation file in the spec:

# in spec/calculator_spec.rb
# - RSpec adds ./lib to the $LOAD_PATH
require "calculator"

Now run the spec again, and watch it pass:

$ rspec spec/calculator_spec.rb

Finished in 0.000315 seconds
1 example, 0 failures

Use the documentation formatter to see the resulting spec:

$ rspec spec/calculator_spec.rb --format doc
    returns the sum of its arguments

Finished in 0.000379 seconds
1 example, 0 failures

Also see

Something went wrong with that request. Please try again.