rr 0.3.11 → 0.4.0

data/CHANGES

@@ -1,3 +1,8 @@
+* 0.4.0
+- Documentation improvements
+- Renamed Double to DoubleInsertion
+- Renamed Scenario to Double
+
 * 0.3.11
 - Fixed [#13724] Mock Proxy on Active Record Association proxies causes error
 
@@ -50,7 +55,7 @@
 - Fixed [#12402] Stubbing return value of probes fails after calling the stubbed method two times
 
 * 0.2.3
-- Added InstanceMethods#rr_verify and InstanceMethods#rr_reset
+- Added RRMethods#rr_verify and RRMethods#rr_reset
 
 * 0.2.2
 - Fixed "singleton method bound for a different object"
@@ -62,8 +67,8 @@
 - 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 InstanceMethods
-- Added InstanceMethods#mock_probe
+- Renamed DoubleMethods to RRMethods
+- Added RRMethods#mock_probe
 
 * 0.1.15
 - Fixed [#12333] Rebinding original_methods causes blocks not to work

data/README

@@ -1,32 +1,134 @@
 = RR
 
-RR (Double Ruby) is a double framework that features a rich
+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
 http://xunitpatterns.com/Test%20Double.html
 
-Currently RR implements mocks, stubs, and probes. It is a goal of
-RR to support a wide range of double techniques and patterns.
+Currently RR implements mocks, stubs, and proxies. In the future, RR will
+support spies.
+
+== 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 removing words from a double declaration.
+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
+
+=== No mock objects
+RR is an opinionated framework. RR does not create a mock object for you,
+like other frameworks. Instead, RR utilizes a technique known as
+"partial mocking".
+
+  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)
+
+=== 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 make using the with method unnecessary
+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')
 
-== Mocks
-http://xunitpatterns.com/Mock%20Object.html
+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:
+* mock
+* stub
+* proxy
+* instance_of
+
+These methods are composable. mock and stub can be used by themselves and
+are mutually exclusive.
+proxy and instance_of must be chained with mock or stub. You can chain
+proxy and instance_of together.
+
+=== 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 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.
   view = controller.template
   mock(view).render(:partial => "user_info") {"Information"}
 
-  # or
-  mock(view) do
-    render(:partial => "user_info") {"Information"}
-  end
+=== stub
+stub replaces the method on the object with only an implementation. You
+can still use arguments to differentiate which stub gets invoked.
 
-== Stubs
-http://xunitpatterns.com/Test%20Stub.html
+See 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.
   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
 
-== Mock Proxies/Probes
-Add verifications that a method was called while actually calling it.
-The following example verifies render partial will be called and
-renders the partial.
+=== 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|
@@ -34,21 +136,20 @@ renders the partial.
     "Different html"
   end
 
-Probes support after_call callbacks. This is useful for Stubbing out
-a class method and getting its return value. You can also change the return value.
-This technique is also useful for verifying that you are mocking exists and
-functions proberly, thereby testing you interface.
-For example, using ActiveRecord:
-
-  mock.proxy(User).find('5') do |user|
-    mock.proxy(user).projects do |projects|
+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(user).valid? {false}
-    user
+    mock(bob).valid? {false}
+    bob
   end
 
-== Stub Proxy/Probes
+=== stub.proxy
 Intercept the return value of a method call.
 The following example verifies render partial will be called and
 renders the partial.
@@ -59,12 +160,12 @@ renders the partial.
     html
   end
 
-== Instance of Doubles
+=== instance_of
 Put double scenarios on instances of a Class.
 
   mock.instance_of(User).valid? {false}
 
-== Block Syntax
+=== Block Syntax
   script = MyScript.new
   mock(script) do |m|
     m.system("cd #{RAILS_ENV}") {true}
@@ -72,23 +173,13 @@ Put double scenarios on instances of a Class.
     m.system("rake baz") {true}
   end
 
-== Terse Syntax
-One of the goals of RR is to make doubles more scannable.
-This is accomplished by removing words from a double declaration.
-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
-
 == 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
 * 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
 * Gerald Meszaros for his excellent book "xUnit Test Patterns"

data/Rakefile

@@ -22,16 +22,16 @@ end
 
 def run_suite
   dir = File.dirname(__FILE__)
-  system("ruby #{dir}/examples/example_suite.rb") || raise("Example Suite failed")
+  system("ruby #{dir}/spec/spec_suite.rb") || raise("Spec Suite failed")
 end
 
 PKG_NAME = "rr"
-PKG_VERSION = "0.3.11"
+PKG_VERSION = "0.4.0"
 PKG_FILES = FileList[
   '[A-Z]*',
   '*.rb',
   'lib/**/*.rb',
-  'examples/**/*.rb'
+  'spec/**/*.rb'
 ]
 
 spec = Gem::Specification.new do |s|
@@ -40,7 +40,7 @@ spec = Gem::Specification.new do |s|
   s.summary = "RR (Double Ruby) is a double framework that features a rich " <<
               "selection of double techniques and a terse syntax. " <<
               "http://xunitpatterns.com/Test%20Double.html"
-  s.test_files = "examples/example_suite.rb"
+  s.test_files = "spec/spec_suite.rb"
   s.description = s.summary
 
   s.files = PKG_FILES.to_a
@@ -66,5 +66,6 @@ end
 
 def tag_release
   dashed_version = PKG_VERSION.gsub('.', '-')
-  `svn cp svn+ssh://rubyforge.org/var/svn/pivotalrb/rr/trunk svn+ssh://rubyforge.org/var/svn/pivotalrb/rr/tags/REL-#{dashed_version} -m 'Version #{PKG_VERSION}'`
+  svn_user = "#{ENV["SVN_USER"]}@" || ""
+  `svn cp svn+ssh://#{svn_user}rubyforge.org/var/svn/pivotalrb/rr/trunk svn+ssh://#{svn_user}rubyforge.org/var/svn/pivotalrb/rr/tags/REL-#{dashed_version} -m 'Version #{PKG_VERSION}'`
 end

data/lib/rr.rb

@@ -7,17 +7,17 @@ require "#{dir}/rr/errors/argument_equality_error"
 require "#{dir}/rr/errors/times_called_error"
 
 require "#{dir}/rr/space"
-require "#{dir}/rr/double"
+require "#{dir}/rr/double_insertion"
 require "#{dir}/rr/hash_with_object_id_key"
 
-require "#{dir}/rr/scenario_method_proxy"
+require "#{dir}/rr/double_method_proxy"
 
-require "#{dir}/rr/scenario_creator"
+require "#{dir}/rr/double_creator"
 
-require "#{dir}/rr/scenario"
-require "#{dir}/rr/scenario_definition"
-require "#{dir}/rr/scenario_definition_builder"
-require "#{dir}/rr/scenario_matches"
+require "#{dir}/rr/double"
+require "#{dir}/rr/double_definition"
+require "#{dir}/rr/double_definition_builder"
+require "#{dir}/rr/double_matches"
 
 require "#{dir}/rr/expectations/argument_equality_expectation"
 require "#{dir}/rr/expectations/any_argument_expectation"
@@ -41,7 +41,7 @@ require "#{dir}/rr/times_called_matchers/proc_matcher"
 require "#{dir}/rr/times_called_matchers/at_least_matcher"
 require "#{dir}/rr/times_called_matchers/at_most_matcher"
 
-require "#{dir}/rr/extensions/instance_methods"
+require "#{dir}/rr/adapters/rr_methods"
 
 require "#{dir}/rr/adapters/rspec"
 require "#{dir}/rr/adapters/test_unit"

data/lib/rr/adapters/rr_methods.rb

@@ -0,0 +1,228 @@
+module RR
+  module Adapters
+    module RRMethods
+      # Verifies all the DoubleInsertion objects have met their
+      # TimesCalledExpectations.
+      def verify
+        RR::Space.instance.verify_double_insertions
+      end
+
+      # Resets the registered Doubles and ordered Doubles
+      def reset
+        RR::Space.instance.reset
+      end
+
+      # This method sets the Double to have a mock strategy. A mock strategy
+      # sets the default state of the Double to expect the method call
+      # with arguments exactly one time. The Double's expectations can be
+      # changed.
+      #
+      # This method can be chained with proxy.
+      #   mock.proxy(subject).method_name_1
+      #   or
+      #   proxy.mock(subject).method_name_1
+      #
+      # When passed the subject, a DoubleMethodProxy is returned. Passing
+      # a method with arguments to the proxy will set up expectations that
+      # the a call to the subject's method with the arguments will happen,
+      # and return the prescribed value.
+      #   mock(subject).method_name_1 {return_value_1}
+      #   mock(subject).method_name_2(arg1, arg2) {return_value_2}
+      #
+      # When passed the subject and the method_name, this method returns
+      # a mock Double with the method already set.
+      #
+      #   mock(subject, :method_name_1) {return_value_1}
+      #   mock(subject, :method_name_2).with(arg1, arg2) {return_value_2}
+      #
+      # mock also takes a block for definitions.
+      #   mock(subject) do
+      #     method_name_1 {return_value_1}
+      #     method_name_2(arg_1, arg_2) {return_value_2}
+      #   end
+      def mock(subject=DoubleCreator::NO_SUBJECT_ARG, method_name=nil, &definition)
+        creator = RR::Space.scenario_creator
+        creator.mock(subject, method_name, &definition)
+      end
+
+
+      # This method sets the Double to have a stub strategy. A stub strategy
+      # sets the default state of the Double to expect the method call
+      # with any arguments any number of times. The Double's
+      # expectations can be changed.
+      #
+      # This method can be chained with proxy.
+      #   stub.proxy(subject).method_name_1
+      #   or
+      #   proxy.stub(subject).method_name_1
+      #
+      # When passed the subject, a DoubleMethodProxy is returned. Passing
+      # a method with arguments to the proxy will set up expectations that
+      # the a call to the subject's method with the arguments will happen,
+      # and return the prescribed value.
+      #   stub(subject).method_name_1 {return_value_1}
+      #   stub(subject).method_name_2(arg_1, arg_2) {return_value_2}
+      #
+      # When passed the subject and the method_name, this method returns
+      # a stub Double with the method already set.
+      #
+      #   mock(subject, :method_name_1) {return_value_1}
+      #   mock(subject, :method_name_2).with(arg1, arg2) {return_value_2}
+      #
+      # stub also takes a block for definitions.
+      #   stub(subject) do
+      #     method_name_1 {return_value_1}
+      #     method_name_2(arg_1, arg_2) {return_value_2}
+      #   end
+      def stub(subject=DoubleCreator::NO_SUBJECT_ARG, method_name=nil, &definition)
+        creator = RR::Space.scenario_creator
+        creator.stub(subject, method_name, &definition)
+      end
+
+      # This method add proxy capabilities to the Double. proxy can be called
+      # with mock or stub.
+      #
+      #   mock.proxy(controller.template).render(:partial => "my/socks")
+      #
+      #   stub.proxy(controller.template).render(:partial => "my/socks") do |html|
+      #     html.should include("My socks are wet")
+      #     html
+      #   end
+      #
+      #   mock.proxy(controller.template).render(:partial => "my/socks") do |html|
+      #     html.should include("My socks are wet")
+      #     "My new return value"
+      #   end
+      #
+      # mock.proxy also takes a block for definitions.
+      #   mock.proxy(subject) do
+      #     render(:partial => "my/socks")
+      #
+      #     render(:partial => "my/socks") do |html|
+      #       html.should include("My socks are wet")
+      #       html
+      #     end
+      #
+      #     render(:partial => "my/socks") do |html|
+      #       html.should include("My socks are wet")
+      #       html
+      #     end
+      #
+      #     render(:partial => "my/socks") do |html|
+      #       html.should include("My socks are wet")
+      #       "My new return value"
+      #     end
+      #   end
+      #
+      # Passing a block to the Double (after the method name and arguments)
+      # allows you to intercept the return value.
+      # The return value can be modified, validated, and/or overridden by
+      # passing in a block. The return value of the block will replace
+      # the actual return value.
+      #
+      #   mock.proxy(controller.template).render(:partial => "my/socks") do |html|
+      #     html.should include("My socks are wet")
+      #     "My new return value"
+      #   end
+      def proxy(subject=DoubleCreator::NO_SUBJECT_ARG, method_name=nil, &definition)
+        creator = RR::Space.scenario_creator
+        creator.proxy(subject, method_name, &definition)
+      end
+
+      # This method sets the Double to have a dont_allow strategy.
+      # A dont_allow strategy sets the default state of the Double
+      # to expect never to be called. The Double's expectations can be
+      # changed.
+      #
+      # The following example sets the expectation that subject.method_name
+      # will never be called with arg1 and arg2.
+      #
+      #   do_not_allow(subject).method_name(arg1, arg2)
+      #
+      # dont_allow also supports a block sytnax.
+      #    dont_allow(subject) do |m|
+      #      m.method1 # Do not allow method1 with any arguments
+      #      m.method2(arg1, arg2) # Do not allow method2 with arguments arg1 and arg2
+      #      m.method3.with_no_args # Do not allow method3 with no arguments
+      #    end
+      def dont_allow(subject=DoubleCreator::NO_SUBJECT_ARG, method_name=nil, &definition)
+        creator = RR::Space.scenario_creator
+        creator.dont_allow(subject, method_name, &definition)
+      end
+      alias_method :do_not_allow, :dont_allow
+      alias_method :dont_call, :dont_allow
+      alias_method :do_not_call, :dont_allow
+
+      # Calling instance_of will cause all instances of the passed in Class
+      # to have the Double defined.
+      #
+      # The following example mocks all User's valid? method and return false.
+      #   mock.instance_of(User).valid? {false}
+      #
+      # The following example mocks and proxies User#projects and returns the
+      # first 3 projects.
+      #   mock.instance_of(User).projects do |projects|
+      #     projects[0..2]
+      #   end
+      def instance_of(subject=DoubleCreator::NO_SUBJECT_ARG, method_name=nil, &definition)
+        creator = RR::Space.scenario_creator
+        creator.instance_of(subject, method_name, &definition)
+      end
+
+      # Returns a AnyTimesMatcher. This is meant to be passed in as an argument
+      # to Double#times.
+      #
+      #   mock(object).method_name(anything).times(any_times) {return_value}
+      def any_times
+        TimesCalledMatchers::AnyTimesMatcher.new
+      end
+
+      # Sets up an Anything wildcard ArgumentEqualityExpectation
+      # that succeeds when passed any argument.
+      #   mock(object).method_name(anything) {return_value}
+      #   object.method_name("an arbitrary value") # passes
+      def anything
+        RR::WildcardMatchers::Anything.new
+      end
+
+      # Sets up an IsA wildcard ArgumentEqualityExpectation
+      # that succeeds when passed an argument of a certain type.
+      #   mock(object).method_name(is_a(String)) {return_value}
+      #   object.method_name("A String") # passes
+      def is_a(klass)
+        RR::WildcardMatchers::IsA.new(klass)
+      end
+
+      # Sets up an Numeric wildcard ArgumentEqualityExpectation
+      # that succeeds when passed an argument that is ::Numeric.
+      #   mock(object).method_name(numeric) {return_value}
+      #   object.method_name(99) # passes
+      def numeric
+        RR::WildcardMatchers::Numeric.new
+      end
+
+      # Sets up an Boolean wildcard ArgumentEqualityExpectation
+      # that succeeds when passed an argument that is a ::Boolean.
+      #   mock(object).method_name(boolean) {return_value}
+      #   object.method_name(false) # passes
+      def boolean
+        RR::WildcardMatchers::Boolean.new
+      end
+
+      # Sets up a DuckType wildcard ArgumentEqualityExpectation
+      # that succeeds when passed the argument implements the methods.
+      #   arg = Object.new
+      #   def arg.foo; end
+      #   def arg.bar; end
+      #   mock(object).method_name(duck_type(:foo, :bar)) {return_value}
+      #   object.method_name(arg) # passes
+      def duck_type(*args)
+        RR::WildcardMatchers::DuckType.new(*args)
+      end
+
+      instance_methods.each do |name|
+        alias_method "rr_#{name}", name
+      end
+    end
+  end
+end