rr 0.4.10 → 0.6.0

data/CHANGES

@@ -1,3 +1,17 @@
+* 0.6.0
+- 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
 - DoubleDefinitionCreatorProxy does not undef #object_id
 - Fixed rdoc pointer to README

data/README.rdoc

@@ -3,6 +3,15 @@
 RR (Double Ruby) is a test double framework that features a rich
 selection of double techniques and a terse syntax.
 
+== More Information
+=== Mailing Lists
+* double-ruby-users@rubyforge.org
+* double-ruby-devel@rubyforge.org
+
+=== Websites
+* http://rubyforge.org/projects/double-ruby
+* http://github.com/btakita/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. Its like a stunt
@@ -33,7 +42,7 @@ 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.
+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
@@ -42,10 +51,8 @@ Here is RR compared to other mock frameworks:
   User.should_receive(:find).with('42') {jane} # Rspec using return value blocks
   mock(User).find('42') {jane} # RR
 
-=== No "pure" mock object
-RR is an opinionated framework. RR does not create a mock object for you,
-like other frameworks. Instead, RR utilizes a technique known as
-"double injection".
+=== Double Injections (a.k.a Partial Mocking)
+RR utilizes a technique known as "double injection".
 
   my_object = MyClass.new
   mock(my_object).hello
@@ -54,10 +61,14 @@ 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.
@@ -70,7 +81,7 @@ 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
+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')
@@ -95,16 +106,19 @@ Rspec mocks:
 
 == Using RR
 To create a double on an object, you can use the following methods:
-* mock
-* stub
-* proxy
-* instance_of
+* mock or mock!
+* stub or stub!
+* dont_allow or dont_allow!
+* proxy or proxy!
+* instance_of or instance_of!
 
-These methods are composable. mock and stub can be used by themselves and
+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 chain
+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
@@ -136,6 +150,12 @@ an exception is raised.
     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
@@ -190,6 +210,22 @@ Put double scenarios on instances of a Class.
     m.system("rake baz") {true}
   end
 
+=== 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)
@@ -214,6 +250,22 @@ Put double scenarios on instances of a Class.
   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")
+
 === Invocation Amount Wildcard Matchers
 ==== any_times
   mock(object).method_name(anything).times(any_times) {return_value}
@@ -222,10 +274,12 @@ Put double scenarios on instances of a Class.
 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
-* Nick Kallen for documentation suggestion & bug reports
 * 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"

data/Rakefile

@@ -26,7 +26,7 @@ def run_suite
 end
 
 PKG_NAME = "rr"
-PKG_VERSION = "0.4.10"
+PKG_VERSION = "0.6.0"
 PKG_FILES = FileList[
   '[A-Z]*',
   '*.rb',

data/lib/rr.rb

@@ -10,13 +10,24 @@ require "#{dir}/rr/space"
 require "#{dir}/rr/double_injection"
 require "#{dir}/rr/hash_with_object_id_key"
 
-require "#{dir}/rr/double_definition_creator_proxy"
-
-require "#{dir}/rr/double_definition_creator"
+require "#{dir}/rr/double_definitions/double_definition_creator_proxy"
+require "#{dir}/rr/double_definitions/double_definition_creator"
+require "#{dir}/rr/double_definitions/child_double_definition_creator"
+require "#{dir}/rr/adapters/rr_methods"
 
 require "#{dir}/rr/double"
-require "#{dir}/rr/double_definition"
-require "#{dir}/rr/double_definition_builder"
+require "#{dir}/rr/double_definitions/double_definition"
+require "#{dir}/rr/double_definitions/strategies/strategy"
+require "#{dir}/rr/double_definitions/strategies/verification/verification_strategy"
+require "#{dir}/rr/double_definitions/strategies/verification/mock"
+require "#{dir}/rr/double_definitions/strategies/verification/stub"
+require "#{dir}/rr/double_definitions/strategies/verification/dont_allow"
+require "#{dir}/rr/double_definitions/strategies/implementation/implementation_strategy"
+require "#{dir}/rr/double_definitions/strategies/implementation/reimplementation"
+require "#{dir}/rr/double_definitions/strategies/implementation/proxy"
+require "#{dir}/rr/double_definitions/strategies/scope/scope_strategy"
+require "#{dir}/rr/double_definitions/strategies/scope/instance"
+require "#{dir}/rr/double_definitions/strategies/scope/instance_of_class"
 require "#{dir}/rr/double_matches"
 
 require "#{dir}/rr/expectations/argument_equality_expectation"
@@ -30,6 +41,8 @@ require "#{dir}/rr/wildcard_matchers/boolean"
 require "#{dir}/rr/wildcard_matchers/duck_type"
 require "#{dir}/rr/wildcard_matchers/regexp"
 require "#{dir}/rr/wildcard_matchers/range"
+require "#{dir}/rr/wildcard_matchers/satisfy"
+require "#{dir}/rr/wildcard_matchers/hash_including"
 
 require "#{dir}/rr/times_called_matchers/terminal"
 require "#{dir}/rr/times_called_matchers/non_terminal"
@@ -41,15 +54,22 @@ 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/adapters/rr_methods"
-
 require "#{dir}/rr/adapters/rspec"
 require "#{dir}/rr/adapters/test_unit"
 
 module RR
   class << self
+    (RR::Space.instance_methods - Object.instance_methods).each do |method_name|
+      returns_method = <<-METHOD
+        def #{method_name}(*args, &block)
+          RR::Space.instance.__send__(:#{method_name}, *args, &block)
+        end
+      METHOD
+      class_eval(returns_method, __FILE__, __LINE__ - 4)
+    end
+
     def method_missing(method_name, *args, &block)
       RR::Space.instance.__send__(method_name, *args, &block)
     end
-  end  
-end
+  end
+end

data/lib/rr/adapters/rr_methods.rb

@@ -1,6 +1,24 @@
 module RR
   module Adapters
     module RRMethods
+      class << self
+        def register_strategy_class(strategy_class, method_name)
+          class_eval((<<-CLASS), __FILE__, __LINE__ + 1)
+          def #{method_name}(subject=DoubleDefinitions::DoubleDefinitionCreator::NO_SUBJECT, method_name=nil, &definition_eval_block)
+            creator = DoubleDefinitions::DoubleDefinitionCreator.new
+            creator.#{method_name}(subject, method_name, &definition_eval_block)
+          end
+          CLASS
+
+          class_eval((<<-CLASS), __FILE__, __LINE__ + 1)
+          def #{method_name}!(method_name=nil, &definition_eval_block)
+            creator = DoubleDefinitions::DoubleDefinitionCreator.new
+            creator.#{method_name}!(method_name, &definition_eval_block)
+          end
+          CLASS
+        end
+      end
+
       # Verifies all the DoubleInjection objects have met their
       # TimesCalledExpectations.
       def verify
@@ -12,163 +30,6 @@ module RR
         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 DoubleDefinitionCreatorProxy 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=DoubleDefinitionCreator::NO_SUBJECT_ARG, method_name=nil, &definition)
-        creator = DoubleDefinitionCreator.new
-        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 DoubleDefinitionCreatorProxy 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=DoubleDefinitionCreator::NO_SUBJECT_ARG, method_name=nil, &definition)
-        creator = DoubleDefinitionCreator.new
-        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=DoubleDefinitionCreator::NO_SUBJECT_ARG, method_name=nil, &definition)
-        creator = DoubleDefinitionCreator.new
-        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=DoubleDefinitionCreator::NO_SUBJECT_ARG, method_name=nil, &definition)
-        creator = DoubleDefinitionCreator.new
-        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=DoubleDefinitionCreator::NO_SUBJECT_ARG, method_name=nil, &definition)
-        creator = DoubleDefinitionCreator.new
-        creator.instance_of(subject, method_name, &definition)
-      end
-
       # Returns a AnyTimesMatcher. This is meant to be passed in as an argument
       # to Double#times.
       #
@@ -210,7 +71,7 @@ module RR
       end
 
       # Sets up a DuckType wildcard ArgumentEqualityExpectation
-      # that succeeds when passed the argument implements the methods.
+      # that succeeds when the passed argument implements the methods.
       #   arg = Object.new
       #   def arg.foo; end
       #   def arg.bar; end
@@ -219,6 +80,25 @@ module RR
       def duck_type(*args)
         RR::WildcardMatchers::DuckType.new(*args)
       end
+      
+      # Sets up a HashIncluding wildcard ArgumentEqualityExpectation
+      # that succeeds when the passed argument contains at least those keys
+      # and values of the expectation.
+      #   mock(object).method_name(hash_including(:foo => 1)) {return_value}
+      #   object.method_name({:foo => 1, :bar => 2) # passes
+      def hash_including(expected_hash)
+        RR::WildcardMatchers::HashIncluding.new(expected_hash)
+      end
+
+      # Sets up a Satisfy wildcard ArgumentEqualityExpectation
+      # that succeeds when the passed argument causes the expectation's
+      # proc to return true.
+      #   mock(object).method_name(satisfy {|arg| arg == :foo}) {return_value}
+      #   object.method_name(:foo) # passes
+      def satisfy(expectation_proc=nil, &block)
+        expectation_proc ||= block
+        RR::WildcardMatchers::Satisfy.new(expectation_proc)
+      end
 
       instance_methods.each do |name|
         alias_method "rr_#{name}", name