Skip to content
Pull request Compare This branch is 242 commits behind rspec:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

RSpec is a Behaviour-Driven Development tool for Ruby programmers. BDD is an approach to software development that combines Test-Driven Development, Domain Driven Design, and Acceptance Test-Driven Planning. RSpec helps you do the TDD part of that equation, focusing on the documentation and design aspects of TDD.

Getting started

$ gem install rspec

Start with a very simple example that expresses some basic desired behaviour.

# bowling_spec.rb

describe Bowling do
  describe "#score" do
    it "returns 0 for all gutter game" do
      bowling =
      20.times { bowling.hit(0) }
      bowling.score.should == 0

Run the example and watch it fail.

$ rspec bowling_spec.rb 
  uninitialized constant Object::Bowling (NameError)

Now write just enough code to make it pass.

# bowling_spec.rb

require './bowling'
# bowling.rb

class Bowling
  def hit(pins)

  def score

Run the example and bask in the joy that is green.

$ rspec bowling_spec.rb --color --format doc

    returns 0 for all gutter game

Finished in 0.00057 seconds
1 example, 0 failures


This is the official documentation site for RSpec-2. Much of the documentation you see here is written with another BDD tool called Cucumber, which, like RSpec, provides executable documentation. The Cucumber features you see here have all been run against RSpec's codebase, serving as specification, documentation and regression tests of the behaviour.

Release Policy

Since the release of RSpec-2.0, RSpec follows the Rubygems Rational Versioning Policy. We are working toward compliance with Semantic Versioning, but that is a bit down the road. You can read those documents for more detail, but the short version is this:

Release numbers have three parts:

  • Major
  • Minor
  • Patch

For example, the recent 2.3.0 release means:

  • Major: 2
  • Minor: 3
  • Patch: 0

The different parts follow the following conventions:

  • Patch releases have only bug fixes.
  • Minor releases have bug fixes and/or new functionality.
  • Major releases have bug fixes and/or new functionality possibly including breaking changes.

What this means for RSpec users

The first thing you'll notice is more frequent minor and major releases. We are already at rspec-2.3.0 instead of 2.0.5 because we've steadily added new features, so the 2.1, 2.2, and 2.3 releases were inappropriate for a patch release.

The real benefit is that you can now safely use a Pessamistic Version Constraint (e.g. "~> 2.3") with confidence that you won't accidentally absorb breaking changes.

Upgrading from RSpec-1

If you are upgrading from rspec-1, or beta versions of rspec-2, be sure to review the Upgrade information for each project:

Help make this documentation better!

Please submit feedback (and patches!) on this documentation to:

Something went wrong with that request. Please try again.