We've developed a new syntax for message expectations in RSpec, which brings message expectations in line with the new expect syntax for state based expectations. This change required us to make a number of internal refactorings, so we're cutting a release candidate of RSpec, 2.14rc1, so that early adopters can try this new feature out. We encourage you to try out the release candidate and report any issues to https://github.com/rspec/rspec-mocks/issues.

In 2.14rc1 both the new syntax and old syntax are enabled by default. This is in line with state based expectations, where both syntaxes are also enabled by default.

With the old syntax message expectations were set like this:

foo.should_receive(:bar)
foo.should_receive(:bar).with(:buzz)
foo.should_receive(:bar).exactly(3).times

The new syntax for message expectations looks like this:

expect(foo).to receive(:bar)
expect(foo).to receive(:bar).with(:buzz)
expect(foo).to receive(:bar).exactly(3).times

This syntax also adds new ways to stub methods. Previously you may have stubbed like this:

d = double(:message1 => true)
d.stub(:message2).and_return(:value)
real_object.stub(:message).and_return(:value)

You can now stub like this:

d = double(:message1 => true)
allow(d).to receive(:message2).and_return(:value)
allow(real_object).to receive(:message).and_return(:value)

If you want to configure which syntaxes are enabled you can do so as follows (see your spec_helper.rb file):

RSpec.configure do |configuration|
  configuration.mock_with :rspec do |configuration|
    configuration.syntax = [:expect, :should]
    #configuration.syntax = :should
    #configuration.syntax = :expect
  end
end

Myron's post explains why using the expect syntax is preferable to the should syntax in some cases. The problem here is that the :should syntax that RSpec uses can fail in the case of proxy objects, and objects that include the delegate module. Essentially it requires that we define methods on every object in the system. Not owning every object means that we cannot ensure this works in a consistent manner. The expect syntax gets around this problem by not relying on RSpec specific methods being defined on every object in the system.

We think that the new :expect syntax for message expectations is an improvement, and that you should try it in your fresh and existing spec suites. You can get the new syntax by upgrading to RSpec 2.14rc1, and we encourage you to do so.