rr-0.10.11 Documentation

RR (Double Ruby) is a test double framework that features a rich selection of double techniques and a terse syntax.

More Information

Mailing Lists

Websites

What is a Test Double?

A Test Double is a generalization of something that replaces a real object to make it easier to test another object. Its like a stunt double for tests. The following are test doubles:

xunitpatterns.com/Test%20Double.html

Currently RR implements mocks, stubs, proxies, and spies. Fakes usually require custom code, so it is beyond the scope of RR.

Using RR

test/unit

class Test::Unit::TestCase
  include RR::Adapters::TestUnit
end

rspec

Spec::Runner.configure do |config|
  config.mock_with :rr
  # or if that doesn't work due to a version incompatibility
  # config.mock_with RR::Adapters::Rspec
end

standalone

extend RR::Adapters::RRMethods
mock(object).method_name {:return_value}

object.method_name # Returns :return_value

RR.verify # Verifies the Double expectations are satisfied

Syntax between RR and other double/mock frameworks

Terse Syntax

One of the goals of RR is to make doubles more scannable. This is accomplished by making the double declaration look as much as the actual method invocation as possible. Here is RR compared to other mock frameworks:

flexmock(User).should_receive(:find).with('42').and_return(jane) # Flexmock
User.should_receive(:find).with('42').and_return(jane) # Rspec
User.expects(:find).with('42').returns {jane} # Mocha
User.should_receive(:find).with('42') {jane} # Rspec using return value blocks
mock(User).find('42') {jane} # RR

Double Injections (a.k.a Partial Mocking)

RR utilizes a technique known as "double injection".

my_object = MyClass.new
mock(my_object).hello

Compare this with doing a mock in mocha:

my_mocked_object = mock()
my_mocked_object.expects(:hello)

Pure Mock objects

If you wish to use objects for the sole purpose of being a mock, you can do so by creating an empty object.

mock(my_mock_object = Object.new).hello

or by using mock!

my_mock_object = mock!.hello.subject # Mocks the #hello method and retrieves that object via the #subject method

No should_receive or expects method

RR uses method_missing to set your method expectation. This means you do not need to use a method such as should_receive or expects.

mock(my_object).hello # The hello method on my_object is mocked

Mocha:

my_object.expects(:hello) # expects sets the hello method expectation

Rspec mocks:

my_object.should_receive(:hello) # should_receive sets the hello method expectation

with method call is not necessary

Since RR uses method_missing, it also makes using the with method unnecessary in most circumstances to set the argument expectations.

mock(my_object).hello('bob', 'jane')

Mocha:

my_object.expects(:hello).with('bob', 'jane')

Rspec mocks:

my_object.should_receive(:hello).with('bob', 'jane')

using a block to set the return value

RR supports using a block to set the return value. RR also has the returns method. Both of the examples are equivalent.

mock(my_object).hello('bob', 'jane') {'Hello Bob and Jane'}
mock(my_object).hello('bob', 'jane').returns('Hello Bob and Jane')

Mocha:

my_object.expects(:hello).with('bob', 'jane').returns('Hello Bob and Jane')

Rspec mocks:

my_object.should_receive(:hello).with('bob', 'jane').and_return('Hello Bob and Jane')
my_object.should_receive(:hello).with('bob', 'jane') {'Hello Bob and Jane'} #rspec also supports blocks for the return value

Using RR

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

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

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.

See xunitpatterns.com/Mock%20Object.html

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 by using:

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

stub

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

See xunitpatterns.com/Test%20Stub.html

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 = User.new
bob = User.new
stub(User).find('42') {jane}
stub(User).find('99') {bob}
stub(User).find do |id|
  raise "Unexpected id #{id.inspect} passed to me"
end

dont_allow - aliased with do_not_allow, dont_call, and do_not_call

dont_allow sets an expectation on the Double that it will never be called. If the Double is called, then a TimesCalledError is raised.

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

mock.proxy

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 return 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 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"
end

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 with valid? to return false.

mock.proxy(User).find('5') do |bob|
  mock.proxy(bob).projects do |projects|
    projects[0..3]
  end
  mock(bob).valid? {false}
  bob
end

stub.proxy

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")
  html
end

instance_of

Put double scenarios on instances of a Class.

mock.instance_of(User).valid? {false}

Spies

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.

test/unit

subject = Object.new
stub(subject).foo
subject.foo(1)
assert_received(subject) {|subject| subject.foo(1)}
assert_received(subject) {|subject| subject.bar} # This fails

rspec

subject = Object.new
stub(subject).foo
subject.foo(1)
subject.should have_received.foo(1)
subject.should have_received.bar # this fails

Block Syntax

The block syntax has two modes

Block Syntax with explicit DoubleDefinitionCreatorProxy argument

Double Graphs

RR has a method-chaining api support for Double graphs. For example, lets 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}
object.foo.bar # :baz
# or
stub(object).foo {stub!.bar {:baz}}
object.foo.bar # :baz
# or
bar = stub!.bar {:baz}
stub(object).foo {bar}
object.foo.bar # :baz

Argument Wildcard matchers

anything

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

is_a

mock(object).foobar(is_a(Time))
object.foobar(Time.now)

numeric

mock(object).foobar(numeric)
object.foobar(99)

boolean

mock(object).foobar(boolean)
object.foobar(false)

duck_type

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

Ranges

mock(object).foobar(1..10)
object.foobar(5)

Regexps

mock(object).foobar(/on/)
object.foobar("ruby on rails")

hash_including

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

satisfy

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

Writing your own Argument Matchers

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

Invocation Amount Wildcard Matchers

any_times

mock(object).method_name(anything).times(any_times) {return_value}

Special Thanks To

With any development effort, there are countless people who have contributed to making it possible. We all are standing on the shoulders of giants. If you have directly contributed to RR and I missed you in this list, please let me know and I will add you. Thanks!

Files

Classes/Modules

Methods

[Validate]

Generated with the Darkfish Rdoc Generator 2.