Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
261 lines (175 sloc) 7.75 KB

Upgrade to 1.3.0

What's changed

be_true and be_false

These methods now align with Ruby's conditional semantics:

  • be_false passes for false and nil

  • be_true passes for everything else

This is a change from the previous behaviour (which wasn't working correctly anyway), which was supposed to treat be_true as equal(true), and be_false as equal(false).

If the actual values true and false are meaningful to your examples, you'll want to change the to use equal(true) and equal(false) (or ==(true) and ==(false)).


We changed the raise_error matcher to raise_exception, and aliased it with raise_error. This maintains backward compatibility, and also gives you the option of being more precise in specs about what is expected.

Matcher DSL

match rescues from ExpectationNotMetErrror by default

This allows you to wrap other expectations in the match method. Consider this matcher:

Spec::Matchers.define :teach do |subject|
  match do |teacher|
    teacher.subjects.should include(subject)

The block passed to match is called internally by Rspec, and is expected to return a boolean value. In this case, if should include(subject) fails, it raises an ExpectationNotMetError.

Beginning with rspec-1.3.0, when the match block raises an ExpectationNotMetError, it is captured and the block returns false. Otherwise it returns true, so it works like any other matcher.


The new match_unless_raises method allows you to wrap Test::Unit assertions by capturing AssertionFailedError and returning false, just as the match method now does with ExpectationNotMetError.

Spec::Matchers.define :teach do |subject|
  match_unless_raises Test::Unit::AssertionFailedError do |teacher|
    assert teacher.subjects.include?(subject)

Upgrade to rspec-1.2.9

What's new


If you have a spec/spec.opts file, the spec command will now use that automatically as long as you don't include any options on the command line.


Writing specs tends to follow a regular pattern of using local variables, discovering duplication, and then having to convert to local variables to instance variables by adding an “@” symbol. The let() method assigns the result of a lazy eval'd block as the return value of an instance method using the same name. This way you can go from this:

describe Subscription do
  it "does something" do
    subscription = Subscription.create :limit => 1

  it "does something else" do
    subscription = Subscription.create :limit => 1

to this:

describe Subscription do
  let(:subscription) { Subscription.create :limit => 1 }

  it "does something" do

  it "does something else" do


If you're in the habit of writing one-liners using implicit subject, this new its() feature is for you. Here's the basic idea:

describe Array do
  its(:length) { should == 0 }

Upgrade to rspec-1.2.3-1.2.7

What's Changed

Matcher DSL

Use Spec::Matchers.define instead of Spec::Matchers.create (which is now deprecated).

Explicit Predicate Matchers are deprecated

With the addition of the new Matcher DSL the old, confusing, and almost-nobody-uses-it explicit predicate matcher functionality's days are now numbered.

If you're not familiar with this feature, don't worry about it. If you have anything that looks like this:

predicate_matchers[:swim] = :can_swim?

Or this

config.predicate_matchers[:swim] = :can_swim?

Change it to this:

Spec::Matchers.define :swim do
  match do |potential_swimmer|

Custom Formatters

If you have an custom formatter, the add_example_group method has been changed to example_group_started, and kept as an alias so your formatters will still work. Though not yet, add_example_group will be deprecated in a future minor release, and removed in a future major release, so we recommend you make this change now.

Upgrade to rspec-1.2.2

What's Changed

require 'rubygems' unless ENV['NO_RUBYGEMS']

After minor public outcry and confusion, we restored necessary references to rubygems in rspec. If you use a different mechanism for managing gems, just set a NO_RUBYGEMS environment variable (to any non-nil value).

Proxies and locations

This is probably only interesting to you if you use custom formatters.

Formatters now receive Spec::Example::ExampleGroupProxy and Spec::Example::ExampleGroup objects with cohesive APIs for reporting. See the RDoc for those classes and Spec::Runner::Formatter::BaseFormatter for more information.

What's new

The new matcher DSL works with test/unit (without the rest of rspec)

We'll be separating this out to its own gem for rspec 2.0, but for now, just install rspec >= 1.2.1 and add the following to your test_helper file:

require 'spec/expectations'
class Test::Unit::TestCase
  include Spec::Matchers

This will add should() and should_not() to your objects, make all of rspec's built-in matchers available to your tests, INCLUDING rspec's DSL for creating matchers (see below, under Upgrade to rspec-1.2.0)


If you have ruby-debug installed, you can set a breakpoint by adding debugger() in your code:

# some code .....
# some more code ....

… and using the --debugger or -u command line option.

spec path/to/file.rb --debugger

Upgrade to rspec-1.2.0

What's Changed


  • If you use the ruby command to run specs instead of the spec command, you'll need to require 'spec/autorun' or they won't run. This won't affect you if you use the spec command or the Spec::Rake::SpecTask that ships with RSpec.

  • require 'spec/test/unit' to invoke test/unit interop if you're using RSpec's core (this is handled implicitly with spec-rails)

  • setup and teardown are gone - use before and after instead

    • you can still use setup and teardown if you're using Test::Unit::TestCase as the base ExampleGroup class (which is implicit in rspec-rails)

  • The matcher protocol has been improved. The old protocol is still supported, but we added support for two new methods that speak a bit more clearly:

    failure_message          => failure_message_for_should
    negative_failure_message => failure_message_for_should_not
  • All references to rubygems have been removed from within rspec's code.

What's New

Ruby 1.9

RSpec now works with Ruby 1.9.1. See for useful information.

Improved heckle integration

RSpec works with heckle again! Gotta use heckle >= 1.4.2 for this to work though, and it only works with ruby-1.8.6 and 1.8.7 (heckle doesn't support 1.9.1 yet).

[sudo] gem install heckle --version ">=1.4.2"
spec spec/game/mastermind.rb --heckle Game::Mastermind

New Matcher DSL

We've added a new DSL for generating custom matchers very simply and cleanly. We'll still support the simple_matcher method, so never fear if you're using that, but we recommend that you start developing your new matchers with this new syntax.

Spec::Matchers.create :be_a_multiple_of do |smaller|
  match do |bigger|
    bigger % smaller == 0

9.should be_a_multiple_of(3)

See features/matchers/define_matcher.feature for more examples

Jump to Line
Something went wrong with that request. Please try again.