c7ae5cc May 13, 2013
617 lines (456 sloc) 13.8 KB

API overview

To create a double on an object, you can use the following methods:

  • #mock / #mock!
  • #stub / #stub!
  • #dont_allow / #dont_allow!
  • #proxy / #proxy!
  • #instance_of / #instance_of!

These methods are composable. #mock, #stub, and #dont_allow can be used by themselves and are mutually exclusive. #proxy and #instance_of must be chained with #mock or #stub. You can also chain #proxy and #instance_of together.

The ! (bang) version of these methods causes the subject object of the Double to be instantiated.


#mock replaces the method on the object with an expectation and implementation. The expectations are a mock will be called with certain arguments a certain number of times (the default is once). You can also set the return value of the method invocation.

Learn more:

The following example sets an expectation that the view will receive a method call to #render with the arguments {:partial => "user_info"} once. When the method is called, "Information" is returned.

view = controller.template
mock(view).render(:partial => "user_info") {"Information"}

You can also allow any number of arguments to be passed into the mock like this:

mock(view).render.with_any_args.twice do |*args|
  if args.first == {:partial => "user_info"}
    "User Info"
    "Stuff in the view #{args.inspect}"


#stub replaces the method on the object with only an implementation. You can still use arguments to differentiate which stub gets invoked.

Learn more:

The following example makes the User.find method return jane when passed "42" and returns bob when passed "99". If another id is passed to User.find, an exception is raised.

jane =
bob =
stub(User).find('42') {jane}
stub(User).find('99') {bob}
stub(User).find do |id|
  raise "Unexpected id #{id.inspect} passed to me"

#dont_allow (aliased to #do_not_allow, #dont_call, and #do_not_call)

#dont_allow is the opposite of #mock -- it sets an expectation on the Double that it will never be called. If the Double actually does end up being called, a TimesCalledError is raised.

User.find('42') # raises a TimesCalledError


mock.proxy replaces the method on the object with an expectation, implementation, and also invokes the actual method. mock.proxy also intercepts the return value and passes it into the return value block.

The following example makes sets an expectation that view.render({:partial => "right_navigation"}) gets called once and returns the actual content of the rendered partial template. A call to view.render({:partial => "user_info"}) will render the "user_info" partial template and send the content into the block and is represented by the html variable. An assertion is done on the value of html and "Different html" is returned.

view = controller.template
mock.proxy(view).render(:partial => "right_navigation")
mock.proxy(view).render(:partial => "user_info") do |html|
  html.should include("John Doe")
  "Different html"

You can also use mock.proxy to set expectations on the returned value. In the following example, a call to User.find('5') does the normal ActiveRecord implementation and passes the actual value, represented by the variable bob, into the block. bob is then set with a mock.proxy for projects to return only the first 3 projects. bob is also mocked so that #valid? returns false.

mock.proxy(User).find('5') do |bob|
  mock.proxy(bob).projects do |projects|
  mock(bob).valid? { false }


Intercept the return value of a method call. The following example verifies render(:partial) will be called and renders the partial.

view = controller.template
stub.proxy(view).render(:partial => "user_info") do |html|
  html.should include("Joe Smith")


Allows stubs to be added to all instances of a class. It works by binding to methods from the class itself, rather than the eigenclass. This allows all instances (excluding instances with the method redefined in the eigenclass) to get the change.

Due to Ruby runtime limitations, mocks will not work as expected. It's not obviously feasible (without an ObjectSpace lookup) to support all of RR's methods (such as mocking). ObjectSpace is not readily supported in JRuby, since it causes general slowness in the interpreter. I'm of the opinion that test speed is more important than having mocks on all instances of a class. If there is another solution, I'd be willing to add it.

any_instance_of(User) do |u|
  stub(u).valid? { false }
any_instance_of(User, :valid? => false)
any_instance_of(User, :valid? => lambda { false })


Adding a DoubleInjection to an object + method (done by #stub, #mock, or #dont_allow) causes RR to record any method invocations to the object + method. Assertions can then be made on the recorded method calls.


subject =
assert_received(subject) {|subject| }
assert_received(subject) {|subject| }  # This fails


subject =
subject.should  # This fails

Block syntax

The block syntax has two modes:

  • A normal block mode with a DoubleDefinitionCreatorProxy argument:

    script =
    mock(script) do |expect|
      expect.system("cd #{RAILS_ENV}") {true}
      expect.system("rake foo:bar") {true}
      expect.system("rake baz") {true}
  • An instance_eval mode where the DoubleDefinitionCreatorProxy is instance_eval'ed:

    script =
    mock(script) do
      system("cd #{RAILS_ENV}") {true}
      system("rake foo:bar") {true}
      system("rake baz") {true}

Double graphs

RR has a method-chaining API support for double graphs. For example, let's say you want an object to receive a method call to #foo, and have the return value receive a method call to #bar.

In RR, you would do:

stub(object).foo.stub!.bar { :baz }  #=> :baz
stub(object).foo { stub!.bar {:baz} }  #=> :baz
bar = stub!.bar { :baz }
stub(object).foo { bar }  #=> :baz

Modifying doubles

Whenever you create a double by calling a method on an object you've wrapped, you get back a special object: a DoubleDefinition. In other words:

stub(object).foo     #=> RR::DoubleDefinitions::DoubleDefinition

There are several ways you can modify the behavior of these doubles via the DoubleDefinition API, and they are listed in this section.

Quick note: all of these methods accept blocks as a shortcut for setting the return value at the same time. In other words, if you have something like this:

mock(object).foo { 'bar' }

you can modify the mock and keep the return value like so:

mock(object).foo.times(2) { 'bar' }

You can even flip around the block:

mock(object).foo { 'bar' }.times(2)

And as we explain below, this is just a shortcut for:

mock(object).foo.returns { 'bar' }.times(2)

Stubbing method implementation / return value

There are two ways here. We have already covered this usage:

stub(object).foo { 'bar' }

However, you can also use #returns if it's more clear to you:

stub(object).foo.returns { 'bar' }

Regardless, keep in mind that you're actually supplying the implementation of the method in question here, so you can put whatever you want in this block:

stub(object).foo { |age, count|
  raise 'hell' if age < 16
  ret = yield count
  blue? ? ret : 'whatever'

This works for mocks as well as stubs.

Stubbing method implementation based on argument expectation

A double's implementation is always tied to its argument expectation. This means that it is possible to return one value if the method is called one way and return a second value if the method is called a second way. For example:

stub(object).foo { 'bar' }
stub(object).foo(1, 2) { 'baz' }        #=> 'bar', 2)  #=> 'baz'

This works for mocks as well as stubs.

Stubbing method to yield given block

If you need to stub a method such that a block given to it is guaranteed to be called when the method is called, then use #yields.

 This outputs: [1, 2, 3]
stub(object).foo.yields(1, 2, 3) {|*args| pp args }

This works for mocks as well as stubs.

Expecting method to be called with exact argument list

There are two ways to do this. Here is the way we have shown before:

mock(object).foo(1, 2), 2)   # ok      # fails

But if this is not clear enough to you, you can use #with:

mock(object).foo.with(1, 2), 2)   # ok      # fails

As seen above, if you create an the expectation for a set of arguments and the method is called with another set of arguments, even if those arguments are of a completely different size, you will need to create another expectation for them somehow. A simple way to do this is to #stub the method beforehand:

mock(object).foo(1, 2), 2)   # ok      # ok too

Expecting method to be called with any arguments

Use #with_any_args:

mock(object).foo.with_any_args        # ok     # also ok, 2)  # also ok
                  # ... you get the idea

Expecting method to be called with no arguments

Use #with_no_args:

mock(object).foo.with_no_args        # ok     # fails

Expecting method to never be called

Use #never:

mock(object).foo.never        # fails

You can also narrow the negative expectation to a specific set of arguments. Of course, you will still need to set explicit expectations for any other ways that your method could be called. For instance:

mock(object).foo.with(1, 2).never, 4)  # fails

RR will complain here that this is an unexpected invocation, so we need to add an expectation for this beforehand. We can do this easily with #stub:


So, a full example would look like:

mock(object).foo.with(1, 2).never, 4)   # ok, 2)   # fails

Alternatively, you can also use #dont_allow, although the same rules apply as above:

dont_allow(object).foo.with(1, 2), 4)   # ok, 2)   # fails

Expecting method to be called only once

Use #once:

mock(object).foo.once    # fails

Expecting method to called exact number of times

Use #times:

mock(object).foo.times(3)    # fails

Expecting method to be called minimum number of times

Use #at_least.

For instance, this would pass:


But this would fail:


Expecting method to be called maximum number of times

Use #at_most.

For instance, this would pass:


But this would fail:


Expecting method to be called any number of times

Use #any_times. This effectively disables the times-called expectation.


You can also use #times + the argument invocation #any_times matcher:


Argument wildcard matchers

RR also has several methods which you can use with argument expectations which act as placeholders for arguments. When RR goes to verify the argument expectation it will compare the placeholders with the actual arguments the method was called with, and if they match then the test passes (hence "matchers").


Matches any value.

mock(object).foobar(1, anything)
object.foobar(1, :my_symbol)


Matches an object which .is_a?(*Class*).



Matches a value which .is_a?(Numeric).



Matches true or false.



Matches an object which responds to certain methods.

mock(object).foobar(duck_type(:walk, :talk))
arg =
def arg.walk; 'waddle'; end
def; 'quack'; end


Matches a number within a certain range.



Matches a string which matches a certain regex.

object.foobar("ruby on rails")


Matches a hash which contains a subset of keys and values.

mock(object).foobar(hash_including(:red => "#FF0000", :blue => "#0000FF"))
object.foobar({:red => "#FF0000", :blue => "#0000FF", :green => "#00FF00"})


Matches an argument which satisfies a custom requirement.

mock(object).foobar(satisfy {|arg| arg.length == 2 })

Writing your own argument matchers

Writing a custom argument wildcard matcher is not difficult. See RR::WildcardMatchers for details.

Invocation amount wildcard matchers


Only used with #times and matches any number.

mock(object).foo.times(any_times) { return_value }