Files | Admin


Release Name: 0.6.0

= RR

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

== 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:
* Mocks
* Stubs
* Fakes
* Spies
* Proxies

Currently RR implements mocks, stubs, and proxies. In the future, RR will
support spies.

== Using RR
=== test/unit
  class Test::Unit::TestCase
    include RR::Adapters::TestUnit

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

== 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 =

Compare this with doing a mock in mocha:
  my_mocked_object = mock()

== 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 =

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

  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')

  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')

  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:
* 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
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.


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"}

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


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 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.
  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"

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|
    mock(bob).valid? {false}

=== 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")

=== instance_of
Put double scenarios on instances of a Class.

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

=== Block Syntax
  script =
  mock(script) do |m|
    m.system("cd #{RAILS_ENV}") {true}
    m.system("rake foo:bar") {true}
    m.system("rake baz") {true}

=== 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} # :baz
  # or
  stub(object).foo {stub!.bar {:baz}} # :baz
  # or
  bar = stub!.bar {:baz}
  stub(object).foo {bar} # :baz

=== Argument Wildcard matchers
==== anything
  mock(object).foobar(1, anything)
  object.foobar(1, :my_symbol)

==== is_a

==== numeric

==== boolean

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

==== Ranges

==== Regexps
  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})

=== 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.
* Pivotal Labs for sponsoring RR development
* Nick Kallen for documentation suggestions, bug reports, and patches
* Matthew O'Conner for patches
* Nathan Sobo for various ideas and inspiration for cleaner and more expressive code
* Parker Thompson for pairing with me
* Felix Morio for pairing with me
* Jeff Whitmire for documentation suggestions
* David Chelimsky for encouragement to make the RR framework, for developing
  the Rspec mock framework, and syntax ideas
* Gerard Meszaros for his excellent book "xUnit Test Patterns"
* Dan North for syntax ideas
* Jim Weirich for developing Flexmock, the first Terse ruby mock framework in Ruby
* James Mead for developing Mocha
* Aslak Hellesoy for Developing Rspec
* Stephen Baker for Developing Rspec
* Dave Astels for some BDD inspiration

Changes: - Friendlier DoubleNotFound error message - Implemented Double strategy creation methods (#mock, #stub, #proxy, #instance_of, and ! equivalents) on DoubleDefinition - Implemented hash_including matcher (Patch by Matthew O'Conner) - Implemented satisfy matcher (Patch by Matthew O'Conner) - Implemented DoubleDefinitionCreator#mock!, #stub!, and #dont_allow! - Modified api to method chain Doubles - Fix conflict with Mocha overriding Object#verify