RR (Double Ruby) is a test double framework that features a rich selection of double techniques and a terse syntax.
To get started, install RR from the command prompt:
gem install rr
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:
-
Mocks
-
Stubs
-
Fakes
-
Spies
-
Proxies
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.
class Test::Unit::TestCase include RR::Adapters::TestUnit end
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
extend RR::Adapters::RRMethods mock(object).method_name {:return_value} object.method_name # Returns :return_value RR.verify # Verifies the Double expectations are satisfied
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
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)
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
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
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')
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
To create a double on an object, you can use the following methods:
-
mock or mock!
-
stub or stub!
-
dont_allow or dont_allow!
-
proxy or proxy!
-
instance_of or 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.
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 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 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 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
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
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} end # or any_instance_of(User, :valid? => false) # or any_instance_of(User, :valid? => lambda {false})
Stubs the new method of the class and allows doubles to be bound to new instances.
Mocks can be used, because new instances are deterministically bound.
new_instance_of(User) do |u| mock(u).valid? {false} end # Deprecated syntax mock.instance_of(User).valid? {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 = Object.new stub(subject).foo subject.foo(1) assert_received(subject) {|subject| subject.foo(1)} assert_received(subject) {|subject| subject.bar} # This fails
subject = Object.new stub(subject).foo subject.foo(1) subject.should have_received.foo(1) subject.should have_received.bar # this fails
The block syntax has two modes
-
A normal block mode with a DoubleDefinitionCreatorProxy argument
script = MyScript.new mock(script) do |expect|
expect.system("cd #{RAILS_ENV}") {true} expect.system("rake foo:bar") {true} expect.system("rake baz") {true}
end
-
An instance_eval mode where the DoubleDefinitionCreatorProxy is instance_evaled
script = MyScript.new mock(script) do system("cd #{RAILS_ENV}") {true} system("rake foo:bar") {true} system("rake baz") {true} end
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
mock(object).foobar(1, anything) object.foobar(1, :my_symbol)
mock(object).foobar(is_a(Time)) object.foobar(Time.now)
mock(object).foobar(numeric) object.foobar(99)
mock(object).foobar(boolean) object.foobar(false)
mock(object).foobar(duck_type(:walk, :talk)) arg = Object.new def arg.walk; 'waddle'; end def arg.talk; 'quack'; end object.foobar(arg)
mock(object).foobar(1..10) object.foobar(5)
mock(object).foobar(/on/) object.foobar("ruby on rails")
mock(object).foobar(hash_including(:red => "#FF0000", :blue => "#0000FF")) object.foobar({:red => "#FF0000", :blue => "#0000FF", :green => "#00FF00"})
mock(object).foobar(satisfy {|arg| arg.length == 2}) object.foobar("xy")
Writing a custom argument wildcard matcher is not difficult. See RR::WildcardMatchers for details.
mock(object).method_name(anything).times(any_times) {return_value}
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!
-
Andreas Haller for patches
-
Aslak Hellesoy for Developing Rspec
-
Bryan Helmkamp for patches
-
Caleb Spare for patches
-
Christopher Redinger for patches
-
Dan North for syntax ideas
-
Dave Astels for some BDD inspiration
-
Dave Myron for a bug report
-
David Chelimsky for encouragement to make the RR framework, for developing the Rspec mock framework, syntax ideas, and patches
-
Daniel Sudol for identifing performance issues with RR
-
Dmitry Ratnikov for patches
-
Eugene Pimenov for patches
-
Evan Phoenix for patches
-
Felix Morio for pairing with me
-
Gabriel Horner for patches
-
Gavin Miller for patches
-
Gerard Meszaros for his excellent book “xUnit Test Patterns”
-
James Mead for developing Mocha
-
Jeff Whitmire for documentation suggestions
-
Jim Weirich for developing Flexmock, the first Terse ruby mock framework in Ruby
-
Joe Ferris for patches
-
Matthew O’Connor for patches and pairing with me
-
Michael Niessner for patches and pairing with me
-
Mike Mangino (from Elevated Rails) for patches and pairing with me
-
Myron Marston for bug reports
-
Nick Kallen for documentation suggestions, bug reports, and patches
-
Nathan Sobo for various ideas and inspiration for cleaner and more expressive code
-
Parker Thompson for pairing with me
-
Phil Darnowsky for patches
-
Pivotal Labs for sponsoring RR development
-
Stephen Baker for Developing Rspec
-
Tatsuya Ono for patches
-
Tuomas Kareinen for a bug report