rr 1.0.4 → 1.0.5.rc1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MzZiOTU0OTRjZjQ4NTUxODZhMTNkOTAxMjg3NmZiY2E1YWZmYTE1MQ==
+  data.tar.gz: !binary |-
+    OGFkYmIyMWRiNTg0ZTU5OTIyYmM4NDM3YzZkODAzOTJkMDg1MDIyMA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    YzI1MDhlMDhkMDZmMWU0ODBjZjdjZDdjZjQ5ZDkwNTEyZTA4NDM2ZmI0N2Nk
+    MDM4MDVlOTg5NTJjYWRiYTVjMTA5NDQ2MDFiNzhmMzMyZjliZjI0NTE0MjJl
+    YzM0Y2RlY2I5ZjkyNmZkN2M5MzNjNjJmZTUzMTg5YjkyOWQwN2U=
+  data.tar.gz: !binary |-
+    OWI5YTViOGFiMzg0YmIzYzZlNjZmZmFkMDkwMjczYWRjNmUxMDRhYjAzZjgw
+    MjNhNmU4YjQ1Njg3OTlkYTY3NzNmNTc1MWM0OTUzMGEyZTg0MTMzZjRmNjIy
+    YmUyYzU1ZjVlMmI4ZDc5ZmEzODc3OTlkYjQ1Nzg3Y2I5MWQzNGE=

data/CHANGES.md

@@ -0,0 +1,376 @@
+# Changelog
+
+## 1.0.4 (2011-06-11)
+
+* Fixed bug using workaround with leftover MethodMissingInjections
+
+## 1.0.3 (2011-06-11)
+
+* Eliminate usage of ObjectSpace._id2ref (Patch Evan Phoenix)
+* Added minitest adapter (Patch Caleb Spare)
+* Added instructions on installing the gem (Patch Gavin Miller)
+* delete missing scratch.rb file from gemspec (Patch bonkydog)
+
+## 1.0.2 (2010-11-01)
+
+* Fixed Two calls recorded to a mock expecting only one call when called via
+  another mock's yield block
+  (http://github.com/btakita/rr/issues/closed#issue/42). Patch by Eugene Pimenov
+  (http://github.com/libc).
+
+## 1.0.1 (2010-10-30)
+
+* Removed new_instance_of for Ruby 1.9.2 compatibility. instance_of is now an
+  alias for any_instance_of.
+* Compatible with Ruby 1.9.2
+
+## 1.0.0 (2010-08-23)
+
+* Added any_instance_of (aliased by all_instances_of), which binds methods
+  directly to the class (instead of the eigenclass).
+* Subclasses of a injected class do not have their methods overridden.
+* any_instance_of and new_instance_of now have a block syntax
+
+## 0.10.11 (2010-03-22)
+
+* Added RR.blank_slate_whitelist
+* Fixed class_eval method redefinition warning in jruby
+
+## 0.10.10 (2010-02-25)
+
+* Suite passes for Ruby 1.9.1
+
+## 0.10.9 (2010-02-17)
+
+* Fixed 1.8.6 bug for real
+
+## 0.10.8 (2010-02-16)
+
+* Fixed 1.8.6 bug
+
+## 0.10.7 (2010-02-15)
+
+* Fixed issue with DoubleInjections binding to objects overriding the method
+  method.
+
+## 0.10.6 (2010-02-15)
+
+* Added MIT license
+* Fixed Bug - dont_allow doesn't work when it follows stub
+  (http://github.com/btakita/rr/issues#issue/20)
+* Fixed exception with DoubleInjections on proxy objects
+  (http://github.com/btakita/rr/issues#issue/24)
+* Fixed Bug - Can't stub attribute methods on a BelongsToAssociation
+  (http://github.com/btakita/rr/issues#issue/24)
+
+## 0.10.5 (2009-12-20)
+
+* Fixed stack overflow caused by double include in Test::Unit adapter
+  [http://github.com/btakita/rr/issues#issue/16]. Identified by Dave Myron
+  (http://github.com/contentfree)
+* Fixed warnings (Patch by Bryan Helmkamp)
+
+## 0.10.4 (2009-09-26)
+
+* Handle lazily defined methods (where respond_to? returns true yet the method
+  is not yet defined and the first call to method_missing defines the method).
+  This pattern is used in ActiveRecord and ActionMailer.
+* Fixed warning about aliasing #instance_exec in jruby.
+  http://github.com/btakita/rr/issues#issue/9 (Patch by Nathan Sobo)
+
+## 0.10.2 (2009-08-30)
+
+* RR properly proxies subjects with private methods
+  [http://github.com/btakita/rr/issues/#issue/7]. Identified by Matthew
+  O'Connor.
+
+## 0.10.1 (???)
+
+* Fixed issue with DoubleInjection not invoking methods that are lazily created
+  [http://github.com/btakita/rr/issues/#issue/4]. Identified by davidlee
+  (http://github.com/davidlee)
+* Fixed issue with mock.proxy and returns
+  [http://github.com/btakita/rr/issues/#issue/2]. Identified by trogdoro
+  (http://github.com/trogdoro)
+
+## 0.10.0 (2009-06-01)
+
+* Method is no longer invoked if respond_to? returns false. This was in place to
+  support ActiveRecord association proxies, and is no longer needed.
+
+## 0.9.0 (2009-04-25)
+
+* instance_of Doubles now apply to methods invoked in the subject's #initialize
+  method.
+
+## 0.8.1 (2009-03-29)
+
+* Fixed exception where the Subject uses method delegation via method_missing
+  (e.g. certain ActiveRecord AssociationProxy methods)
+
+##  0.8.0 (2009-03-29)
+
+* Fixed compatability issues with Ruby 1.9
+* Aliased any_number_of_times with any_times
+* Better error messages for have_received and assert_received matchers (Patch by
+  Joe Ferris)
+* Better documentation on RR wilcard matchers (Patch by Phil Arnowsky)
+
+## 0.7.1 (2009-01-16)
+
+* Performance improvements
+
+## 0.7.0 (2008-12-14)
+
+* Added spies (Patchs by Joe Ferris, Michael Niessner & Mike Mangino)
+* Added strongly typed reimplementation doubles (Patch by Michael Niessner)
+
+## 0.6.2 (???)
+
+* Fixed DoubleDefinition chaining edge cases
+
+## 0.6.1 (???)
+
+* DoubleDefinitionCreatorProxy definition eval block is instance_evaled when the
+  arity is not 1. When the arity is 1, the block is yielded with the
+  DoubleDefinitionCreatorProxy passed in.
+
+## 0.6.0 (2008-10-13)
+
+* 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
+
+## 0.5.0 (???)
+
+* Method chaining Doubles (Patch by Nick Kallen)
+* Chained ordered expectations (Patch by Nick Kallen)
+* Space#verify_doubles can take one or more objects with DoubleInjections to be
+  verified
+
+## 0.4.10 (2008-07-06)
+
+* DoubleDefinitionCreatorProxy does not undef #object_id
+* Fixed rdoc pointer to README
+
+## 0.4.9 (2008-06-18)
+
+* Proxying from RR module to RR::Space.instance
+
+## 0.4.8 (2008-01-23)
+
+* Fixed issue with Hash arguments
+
+## 0.4.7 (2008-01-23)
+
+* Improved error message
+
+## 0.4.6 (2008-01-23)
+
+* Added Double#verbose and Double#verbose?
+
+## 0.4.5 (2008-01-15)
+
+* Fixed doubles for == and #eql? methods
+
+## 0.4.4 (2008-01-15)
+
+* Doc improvements
+* Methods that are not alphabetic, such as ==, can be doubles
+
+## 0.4.3 (2008-01-07)
+
+* Doc improvements
+* Cleanup
+* Finished renaming scenario to double
+
+## 0.4.2 (2007-12-31)
+
+* Renamed DoubleInsertion to DoubleInjection to be consistent with Mocha
+  terminology
+
+## 0.4.1 (2007-12-31)
+
+* Fixed backward compatability issues with rspec
+* Renamed Space#verify_double_insertions to #verify_doubles
+
+## 0.4.0 (2007-12-30)
+
+* Documentation improvements
+* Renamed Double to DoubleInsertion
+* Renamed Scenario to Double
+
+## 0.3.11 (2007-09-06)
+
+* Fixed [#13724] Mock Proxy on Active Record Association proxies causes error
+
+## 0.3.10 (2007-08-18)
+
+* Fixed [#13139] Blocks added to proxy sets the return_value and not the
+  after_call callback
+
+## 0.3.9 (2007-08-14)
+
+* Alias probe to proxy
+
+## 0.3.8 (2007-08-12)
+
+* Implemented [#13009] Better error mesage from TimesCalledMatcher
+
+## 0.3.7 (2007-08-09)
+
+* Fixed [#12928] Reset doubles fails on Rails association proxies
+
+## 0.3.6 (2007-08-01)
+
+* Fixed [#12765] Issues with ObjectSpace._id2ref
+
+## 0.3.5 (2007-07-29)
+
+* trim_backtrace is only set for Test::Unit
+
+## 0.3.4 (2007-07-22)
+
+* Implemented instance_of
+
+## 0.3.3 (2007-07-22)
+
+* Fixed [#12495] Error Probing method_missing interaction
+
+## 0.3.2 (2007-07-22)
+
+* Fixed [#12486] ScenarioMethodProxy when Kernel passed into instance methods
+
+## 0.3.1 (2007-07-22)
+
+* Automatically require Test::Unit and Rspec adapters
+
+## 0.3.0 (2007-07-22)
+
+* ScenarioCreator strategy method chaining
+* Removed mock_probe
+* Removed stub_probe
+
+## 0.2.5 (2007-07-21)
+
+* mock takes method_name argument
+* stub takes method_name argument
+* mock_probe takes method_name argument
+* stub_probe takes method_name argument
+* probe takes method_name argument
+* dont_allow takes method_name argument
+* do_not_allow takes method_name argument
+
+## 0.2.4 (2007-07-19)
+
+* Space#doubles key is now the object id
+* Fixed [#12402] Stubbing return value of probes fails after calling the stubbed
+  method two times
+
+## 0.2.3 (2007-07-18)
+
+* Added RRMethods#rr_verify and RRMethods#rr_reset
+
+## 0.2.2 (2007-07-17)
+
+* Fixed "singleton method bound for a different object"
+* Doing Method aliasing again to store original method
+
+## 0.2.1 (2007-07-17)
+
+* Added mock_probe
+* Added stub_probe
+* Probe returns the return value of the passed in block, instead of ignoring its
+  return value
+* Scenario#after_call returns the return value of the passed in block
+* Not using method aliasing to store original method
+* Renamed DoubleMethods to RRMethods
+* Added RRMethods#mock_probe
+
+## 0.1.15 (2007-07-17)
+
+* Fixed [#12333] Rebinding original_methods causes blocks not to work
+
+## 0.1.14 (2007-07-16)
+
+* Introduced concept of Terminal and NonTerminal TimesCalledMatchers
+* Doubles that can be called many times can be replaced
+* Terminal Scenarios are called before NonTerminal Scenarios
+* Error message tweaking
+* Raise error when making a Scenarios with NonTerminal TimesMatcher Ordered
+
+## 0.1.13 (2007-07-14)
+
+* Fixed [#12290] Scenario#returns with false causes a return value of nil
+
+## 0.1.12 (2007-07-14)
+
+* Fixed bug where Creators methods are not removed when methods are defined on
+  Object
+* Fixed [#12289] Creators methods are not removed in Rails environment
+
+## 0.1.11 (2007-07-14)
+
+* Fixed [#12287] AtLeastMatcher does not cause Scenario to be called
+
+## 0.1.10 (2007-07-14)
+
+* Fixed [#12286] AnyArgumentExpectation#expected_arguments not implemented
+
+## 0.1.9 (2007-07-14)
+
+* Added DoubleMethods#any_times
+* Added Scenario#any_number_of_times
+
+## 0.1.8 (2007-07-14)
+
+* TimesCalledError Message Formatted to be on multiple lines
+* ScenarioNotFoundError Message includes all Scenarios for the Double
+* ScenarioOrderError shows list of remaining ordered scenarios
+
+## 0.1.7 (2007-07-14)
+
+* Fixed [#12194] Double#reset_doubles are not clearing Ordered Scenarios bug
+* Added Space#reset
+* Space#reset_doubles and Space#reset_ordered_scenarios is now protected
+* Added Scenario#at_least
+* Added Scenario#at_most
+
+## 0.1.6 (2007-07-10)
+
+* [#12120] probe allows a the return value to be intercepted
+
+## 0.1.5 (2007-07-09)
+
+* TimesCalledExpectation says how many times were called and how many times
+  called were expected on error
+
+## 0.1.4 (2007-07-09)
+
+* TimesCalledError prints the backtrace to where the Scenario was defined when
+  being verified
+* Error message includes method name when Scenario is not found
+
+## 0.1.3 (2007-07-09)
+
+* Fixed issue where Double#placeholder_name issues when Double method name has a
+  ! or ?
+
+## 0.1.2 (2007-07-08)
+
+* Scenario#returns also accepts an argument
+* Implemented Scenario#yields
+
+## 0.1.1 (2007-07-08)
+
+* Trim the backtrace for Rspec and Test::Unit
+* Rspec and Test::Unit integration fixes
+
+## 0.1.0 (2007-07-07)
+
+* Initial Release

data/Gemfile

@@ -1,12 +1,9 @@
-source :rubygems
+source 'https://rubygems.org'
 
-group :test do
-  gem "rspec", "1.3.0"
-  gem "session", "3.1.0"
-  gem "diff-lcs", "1.1.2"
-  if RUBY_VERSION.include?("1.9")
-    gem "ruby-debug19", "0.11.6"
-  else
-    gem "ruby-debug", "0.10.4"
-  end
+gem 'rake', '~> 10.0'
+
+gem "rspec", "~> 2.13.0"
+if RUBY_VERSION !~ /^1.8/
+  gem "minitest", "~> 4.7.0"
 end
+gem "session", "~> 2.4.0"

data/README.md

@@ -0,0 +1,822 @@
+# RR [![Build Status](https://secure.travis-ci.org/rr/rr.png)](http://travis-ci.org/rr/rr)
+
+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
+~~~
+
+
+## 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. It's like a stunt double for tests. The
+following are test doubles:
+
+* Mocks
+* Stubs
+* Fakes
+* Spies
+* Proxies
+
+*Learn more: <http://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 with your test framework
+
+### Test::Unit
+
+~~~ ruby
+class Test::Unit::TestCase
+  include RR::Adapters::TestUnit
+end
+~~~
+
+### RSpec
+
+RR actually has two adapters, one for the newest version of RSpec (2) and
+another for the older version (1). Currently RSpec targets RR's RSpec-1 adapter
+and so until this is fixed you will need to specify the RSpec-2 adapter:
+
+~~~ ruby
+RSpec.configure do |config|
+  config.include(RR::Adapters::RSpec2)
+end
+~~~
+
+### MiniTest / MiniSpec
+
+~~~ ruby
+class MiniTest::Unit::TestCase
+  include RR::Adapters::MiniTest
+end
+~~~
+
+
+## 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:
+
+~~~ ruby
+# Flexmock
+flexmock(User).should_receive(:find).with('42').and_return(jane)
+# RSpec
+User.should_receive(:find).with('42').and_return(jane)
+# Mocha
+User.expects(:find).with('42').returns { jane }
+# rspec-mocks (using return value blocks)
+User.should_receive(:find).with('42') { jane }
+# RR
+mock(User).find('42') { jane }
+~~~
+
+### Double injections (aka partial mocking)
+
+RR utilizes a technique known as "double injection".
+
+~~~ ruby
+my_object = MyClass.new
+mock(my_object).hello
+~~~
+
+Compare this with doing a mock in Mocha:
+
+~~~ ruby
+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:
+
+~~~ ruby
+mock(my_mock_object = Object.new).hello
+~~~
+
+However as a shortcut you can also use #mock!:
+
+~~~ ruby
+# Create a new mock object with an empty #hello method, then retrieve that mock
+# object via the #subject method
+my_mock_object = mock!.hello.subject
+~~~
+
+### 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.
+
+~~~ ruby
+# In Mocha, #expects sets the #hello method expectation:
+my_object.expects(:hello)
+# Using rspec-mocks, #should_receive sets the #hello method expectation:
+my_object.should_receive(:hello)
+# And here's how you say it using RR:
+mock(my_object).hello
+~~~
+
+### #with method call is not necessary
+
+The fact that RR uses #method_missing also makes using the #with method
+unnecessary in most circumstances to set the argument expectation itself
+(although you can still use it if you want):
+
+~~~ ruby
+# Mocha
+my_object.expects(:hello).with('bob', 'jane')
+# rspec-mocks
+my_object.should_receive(:hello).with('bob', 'jane')
+# RR
+mock(my_object).hello('bob', 'jane')
+mock(my_object).hello.with('bob', 'jane')  # same thing, just more verbose
+~~~
+
+### Using a block to set the return value
+
+RR supports using a block to set the return value as opposed to a specific
+method call (although again, you can use #returns if you like):
+
+~~~ ruby
+# Mocha
+my_object.expects(:hello).with('bob', 'jane').returns('Hello Bob and Jane')
+# rspec-mocks
+my_object.should_receive(:hello).with('bob', 'jane') { 'Hello Bob and Jane' }
+my_object.should_receive(:hello).with('bob', 'jane').and_return('Hello Bob and Jane')  # same thing, just more verbose
+# RR
+mock(my_object).hello('bob', 'jane') { 'Hello Bob and Jane' }
+mock(my_object).hello('bob', 'jane').returns('Hello Bob and Jane')  # same thing, just more verbose
+~~~
+
+
+## Using RR
+
+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
+
+\#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: <http://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.
+
+~~~ ruby
+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:
+
+~~~ ruby
+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.
+
+*Learn more: <http://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.
+
+~~~ ruby
+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 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.
+
+~~~ ruby
+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 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.
+
+~~~ ruby
+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 so that #valid? returns false.
+
+~~~ ruby
+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.
+
+~~~ ruby
+view = controller.template
+stub.proxy(view).render(:partial => "user_info") do |html|
+  html.should include("Joe Smith")
+  html
+end
+~~~
+
+### #any_instance_of
+
+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.
+
+~~~ ruby
+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 })
+~~~
+
+### 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
+
+~~~ ruby
+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
+
+~~~ ruby
+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:
+
+* A normal block mode with a DoubleDefinitionCreatorProxy argument:
+
+  ~~~ ruby
+  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_eval'ed:
+
+  ~~~ ruby
+  script = MyScript.new
+  mock(script) do
+    system("cd #{RAILS_ENV}") {true}
+    system("rake foo:bar") {true}
+    system("rake baz") {true}
+  end
+  ~~~
+
+### 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:
+
+~~~ ruby
+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
+~~~
+
+### 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:
+
+~~~ ruby
+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:
+
+~~~ ruby
+mock(object).foo { 'bar' }
+~~~
+
+you can modify the mock and keep the return value like so:
+
+~~~ ruby
+mock(object).foo.times(2) { 'bar' }
+~~~
+
+You can even flip around the block:
+
+~~~ ruby
+mock(object).foo { 'bar' }.times(2)
+~~~
+
+And as we explain below, this is just a shortcut for:
+
+~~~ ruby
+mock(object).foo.returns { 'bar' }.times(2)
+~~~
+
+#### Stubbing method implementation / return value
+
+There are two ways here. We have already covered this usage:
+
+~~~ ruby
+stub(object).foo { 'bar' }
+~~~
+
+However, you can also use #returns if it's more clear to you:
+
+~~~ ruby
+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:
+
+~~~ ruby
+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:
+
+~~~ ruby
+stub(object).foo { 'bar' }
+stub(object).foo(1, 2) { 'baz' }
+object.foo        #=> 'bar'
+object.foo(1, 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.
+
+~~~ ruby
+# This outputs: [1, 2, 3]
+stub(object).foo.yields(1, 2, 3)
+object.foo {|*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:
+
+~~~ ruby
+mock(object).foo(1, 2)
+object.foo(1, 2)   # ok
+object.foo(3)      # fails
+~~~
+
+But if this is not clear enough to you, you can use #with:
+
+~~~ ruby
+mock(object).foo.with(1, 2)
+object.foo(1, 2)   # ok
+object.foo(3)      # 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:
+
+~~~ ruby
+stub(object).foo
+mock(object).foo(1, 2)
+object.foo(1, 2)   # ok
+object.foo(3)      # ok too
+~~~
+
+#### Expecting method to be called with any arguments
+
+Use #with_any_args:
+
+~~~ ruby
+mock(object).foo.with_any_args
+object.foo        # ok
+object.foo(1)     # also ok
+object.foo(1, 2)  # also ok
+                  # ... you get the idea
+~~~
+
+#### Expecting method to be called with no arguments
+
+Use #with_no_args:
+
+~~~ ruby
+mock(object).foo.with_no_args
+object.foo        # ok
+object.foo(1)     # fails
+~~~
+
+#### Expecting method to never be called
+
+Use #never:
+
+~~~ ruby
+mock(object).foo.never
+object.foo        # 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:
+
+~~~ ruby
+mock(object).foo.with(1, 2).never
+object.foo(3, 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:
+
+~~~ ruby
+stub(object).foo
+~~~
+
+So, a full example would look like:
+
+~~~ ruby
+stub(object).foo
+mock(object).foo.with(1, 2).never
+object.foo(3, 4)   # ok
+object.foo(1, 2)   # fails
+~~~
+
+Alternatively, you can also use #dont_allow, although the same rules apply as
+above:
+
+~~~ ruby
+stub(object).foo
+dont_allow(object).foo.with(1, 2)
+object.foo(3, 4)   # ok
+object.foo(1, 2)   # fails
+~~~
+
+#### Expecting method to be called only once
+
+Use #once:
+
+~~~ ruby
+mock(object).foo.once
+object.foo
+object.foo    # fails
+~~~
+
+#### Expecting method to called exact number of times
+
+Use #times:
+
+~~~ ruby
+mock(object).foo.times(3)
+object.foo
+object.foo
+object.foo
+object.foo    # fails
+~~~
+
+#### Expecting method to be called minimum number of times
+
+Use #at_least.
+
+For instance, this would pass:
+
+~~~ ruby
+mock(object).foo.at_least(3)
+object.foo
+object.foo
+object.foo
+object.foo
+~~~
+
+But this would fail:
+
+~~~ ruby
+mock(object).foo.at_least(3)
+object.foo
+object.foo
+~~~
+
+#### Expecting method to be called maximum number of times
+
+Use #at_most.
+
+For instance, this would pass:
+
+~~~ ruby
+mock(object).foo.at_most(3)
+object.foo
+object.foo
+~~~
+
+But this would fail:
+
+~~~ ruby
+mock(object).foo.at_most(3)
+object.foo
+object.foo
+object.foo
+object.foo
+~~~
+
+#### Expecting method to be called any number of times
+
+Use #any_times. This effectively disables the times-called expectation.
+
+~~~ ruby
+mock(object).foo.any_times
+object.foo
+object.foo
+object.foo
+...
+~~~
+
+You can also use #times + the argument invocation #any_times matcher:
+
+~~~ ruby
+mock(object).foo.times(any_times)
+object.foo
+object.foo
+object.foo
+...
+~~~
+
+
+
+### 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").
+
+#### #anything
+
+Matches any value.
+
+~~~ ruby
+mock(object).foobar(1, anything)
+object.foobar(1, :my_symbol)
+~~~
+
+#### #is_a
+
+Matches an object which `.is_a?(*Class*)`.
+
+~~~ ruby
+mock(object).foobar(is_a(Time))
+object.foobar(Time.now)
+~~~
+
+#### #numeric
+
+Matches a value which `.is_a?(Numeric)`.
+
+~~~ ruby
+mock(object).foobar(numeric)
+object.foobar(99)
+~~~~
+
+#### #boolean
+
+Matches true or false.
+
+~~~ ruby
+mock(object).foobar(boolean)
+object.foobar(false)
+~~~
+
+#### #duck_type
+
+Matches an object which responds to certain methods.
+
+~~~ ruby
+mock(object).foobar(duck_type(:walk, :talk))
+arg = Object.new
+def arg.walk; 'waddle'; end
+def arg.talk; 'quack'; end
+object.foobar(arg)
+~~~
+
+#### Ranges
+
+Matches a number within a certain range.
+
+~~~ ruby
+mock(object).foobar(1..10)
+object.foobar(5)
+~~~
+
+#### Regexps
+
+Matches a string which matches a certain regex.
+
+~~~ ruby
+mock(object).foobar(/on/)
+object.foobar("ruby on rails")
+~~~
+
+#### #hash_including
+
+Matches a hash which contains a subset of keys and values.
+
+~~~ ruby
+mock(object).foobar(hash_including(:red => "#FF0000", :blue => "#0000FF"))
+object.foobar({:red => "#FF0000", :blue => "#0000FF", :green => "#00FF00"})
+~~~
+
+#### #satisfy
+
+Matches an argument which satisfies a custom requirement.
+
+~~~ ruby
+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
+
+Only used with #times and matches any number.
+
+~~~ ruby
+mock(object).foo.times(any_times) { return_value }
+object.foo
+object.foo
+object.foo
+...
+~~~
+
+
+## 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!
+
+* 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
+* Steven Baker for Developing RSpec
+* Tatsuya Ono for patches
+* Tuomas Kareinen for a bug report
+