rr 0.3.11 → 0.4.0

data/lib/rr/adapters/rspec.rb

@@ -8,7 +8,7 @@ module RR
         end
       end
 
-      include RR::Extensions::InstanceMethods
+      include RRMethods
       def setup_mocks_for_rspec
         rr_reset
       end

data/lib/rr/adapters/test_unit.rb

@@ -1,7 +1,7 @@
 module RR
   module Adapters
     module TestUnit
-      include RR::Extensions::InstanceMethods
+      include RRMethods
       def self.included(mod)
         RR::Space.trim_backtrace = true
         mod.class_eval do

data/lib/rr/double.rb

@@ -1,132 +1,337 @@
 module RR
-  # RR::Double is the binding of an object and a method.
-  # A double has 0 to many Scenario objects. Each Scenario
-  # has Argument Expectations and Times called Expectations.
+  # RR::Double is the use case for a method call.
+  # It has the ArgumentEqualityExpectation, TimesCalledExpectation,
+  # and the implementation.
   class Double
-    MethodArguments = Struct.new(:arguments, :block)
-    attr_reader :space, :object, :method_name, :scenarios
+    class << self
+      def formatted_name(method_name, args)
+        formatted_errors = args.collect {|arg| arg.inspect}.join(', ')
+        "#{method_name}(#{formatted_errors})"
+      end
 
-    def initialize(space, object, method_name)
-      @space = space
-      @object = object
-      @method_name = method_name.to_sym
-      if object_has_method?(method_name)
-        meta.send(:alias_method, original_method_name, method_name)
+      def list_message_part(scenarios)
+        scenarios.collect do |scenario|
+          "- #{formatted_name(scenario.method_name, scenario.expected_arguments)}"
+        end.join("\n")
       end
-      @scenarios = []
     end
 
-    # RR::Double#register_scenario adds the passed in Scenario
-    # into this Double's list of Scenario objects.
-    def register_scenario(scenario)
-      @scenarios << scenario
+    attr_reader :times_called, :double_insertion, :definition
+
+    def initialize(space, double_insertion, definition)
+      @space = space
+      @double_insertion = double_insertion
+      @definition = definition
+      @times_called = 0
+      @times_called_expectation = Expectations::TimesCalledExpectation.new(self)
     end
 
-    # RR::Double#bind injects a method that acts as a dispatcher
-    # that dispatches to the matching Scenario when the method
-    # is called.
-    def bind
-      define_implementation_placeholder
-      returns_method = <<-METHOD
-        def #{@method_name}(*args, &block)
-          arguments = MethodArguments.new(args, block)
-          #{placeholder_name}(arguments)
-        end
-      METHOD
-      meta.class_eval(returns_method, __FILE__, __LINE__ - 5)
+    # Double#with sets the expectation that the Double will receive
+    # the passed in arguments.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.with(1, 2) {:return_value}
+    def with(*args, &returns)
+      definition.with(*args, &returns)
     end
 
-    # RR::Double#verify verifies each Scenario
-    # TimesCalledExpectation are met.
-    def verify
-      @scenarios.each do |scenario|
-        scenario.verify
-      end
+    # Double#with_any_args sets the expectation that the Double can receive
+    # any arguments.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.with_any_args {:return_value}
+    def with_any_args(&returns)
+      definition.with_any_args(&returns)
     end
 
-    # RR::Double#reset removes the injected dispatcher method.
-    # It binds the original method implementation on the object
-    # if one exists.
-    def reset
-      meta.send(:remove_method, placeholder_name)
-      if object_has_original_method?
-        meta.send(:alias_method, @method_name, original_method_name)
-        meta.send(:remove_method, original_method_name)
-      else
-        meta.send(:remove_method, @method_name)
-      end
+    # Double#with_no_args sets the expectation that the Double will receive
+    # no arguments.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.with_no_args {:return_value}
+    def with_no_args(&returns)
+      definition.with_no_args(&returns)
     end
 
-    def call_original_method(*args, &block)
-      @object.__send__(original_method_name, *args, &block)
+    # Double#never sets the expectation that the Double will never be
+    # called.
+    #
+    # This method does not accept a block because it will never be called.
+    #
+    #   mock(subject).method_name.never
+    def never
+      definition.never
     end
 
-    def object_has_original_method?
-      object_has_method?(original_method_name)
+    # Double#once sets the expectation that the Double will be called
+    # 1 time.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.once {:return_value}
+    def once(&returns)
+      definition.once(&returns)
     end
 
-    protected
-    def define_implementation_placeholder
-      me = self
-      meta.send(:define_method, placeholder_name) do |arguments|
-        me.send(:call_method, arguments.arguments, arguments.block)
-      end
+    # Double#twice sets the expectation that the Double will be called
+    # 2 times.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.twice {:return_value}
+    def twice(&returns)
+      definition.twice(&returns)
     end
 
-    def call_method(args, block)
-      if scenario = find_scenario_to_attempt(args)
-        return scenario.call(self, *args, &block)
-      end
-      scenario_not_found_error(*args)
+    # Double#at_least sets the expectation that the Double
+    # will be called at least n times.
+    # It works by creating a TimesCalledExpectation.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.at_least(4) {:return_value}
+    def at_least(number, &returns)
+      definition.at_least(number, &returns)
     end
 
-    def find_scenario_to_attempt(args)
-      matches = ScenarioMatches.new(@scenarios).find_all_matches!(args)
+    # Double#at_most allows sets the expectation that the Double
+    # will be called at most n times.
+    # It works by creating a TimesCalledExpectation.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.at_most(4) {:return_value}
+    def at_most(number, &returns)
+      definition.at_most(number, &returns)
+    end
 
-      unless matches.exact_terminal_scenarios_to_attempt.empty?
-        return matches.exact_terminal_scenarios_to_attempt.first
-      end
+    # Double#any_number_of_times sets an that the Double will be called
+    # any number of times. This effectively removes the times called expectation
+    # from the Doublen
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.any_number_of_times
+    def any_number_of_times(&returns)
+      definition.any_number_of_times(&returns)
+    end
 
-      unless matches.exact_non_terminal_scenarios_to_attempt.empty?
-        return matches.exact_non_terminal_scenarios_to_attempt.last
-      end
+    # Double#times creates an TimesCalledExpectation of the passed
+    # in number.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.times(4) {:return_value}
+    def times(number, &returns)
+      definition.times(number, &returns)
+    end
+
+    # Double#ordered sets the Double to have an ordered
+    # expectation.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.ordered {return_value}
+    def ordered(&returns)
+      definition.ordered(&returns)
+    end
 
-      unless matches.wildcard_terminal_scenarios_to_attempt.empty?
-        return matches.wildcard_terminal_scenarios_to_attempt.first
+    # Double#ordered? returns true when the Double is ordered.
+    #
+    #   mock(subject).method_name.ordered?
+    def ordered?
+      definition.ordered?
+    end
+
+    # Double#yields sets the Double to invoke a passed in block when
+    # the Double is called.
+    # An Expection will be raised if no block is passed in when the
+    # Double is called.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.yields(yield_arg1, yield_arg2) {return_value}
+    #   subject.method_name {|yield_arg1, yield_arg2|}
+    def yields(*args, &returns)
+      definition.yields(*args, &returns)
+    end
+
+    # Double#after_call creates a callback that occurs after call
+    # is called. The passed in block receives the return value of
+    # the Double being called.
+    # An Expection will be raised if no block is passed in.
+    #
+    #   mock(subject).method_name {return_value}.after_call {|return_value|}
+    #   subject.method_name # return_value
+    #
+    # This feature is built into proxies.
+    #   mock.proxy(User).find('1') {|user| mock(user).valid? {false}}
+    def after_call(&block)
+      definition.after_call &block
+    end
+
+    # Double#returns accepts an argument value or a block.
+    # It will raise an ArgumentError if both are passed in.
+    #
+    # Passing in a block causes Double to return the return value of
+    # the passed in block.
+    #
+    # Passing in an argument causes Double to return the argument.
+    def returns(value=nil, &implementation)
+      definition.returns(value, &implementation)
+    end
+
+    # Double#implemented_by sets the implementation of the Double.
+    # This method takes a Proc or a Method. Passing in a Method allows
+    # the Double to accept blocks.
+    #
+    #   obj = Object.new
+    #   def obj.foobar
+    #     yield(1)
+    #   end
+    #   mock(obj).method_name.implemented_by(obj.method(:foobar))
+    def implemented_by(implementation)
+      definition.implemented_by implementation
+    end
+
+    # Double#implemented_by_original_method sets the implementation
+    # of the Double to be the original method.
+    # This is primarily used with proxy.
+    #
+    #   obj = Object.new
+    #   def obj.foobar
+    #     yield(1)
+    #   end
+    #   mock(obj).method_name.implemented_by_original_method
+    #   obj.foobar {|arg| puts arg} # puts 1
+    def implemented_by_original_method
+      definition.implemented_by_original_method
+    end
+
+    # Double#call calls the Double's implementation. The return
+    # value of the implementation is returned.
+    #
+    # A TimesCalledError is raised when the times called
+    # exceeds the expected TimesCalledExpectation.
+    def call(double_insertion, *args, &block)
+      self.times_called_expectation.attempt! if definition.times_matcher
+      @space.verify_ordered_scenario(self) if ordered?
+      yields!(block)
+      return_value = call_implementation(double_insertion, *args, &block)
+      return return_value unless definition.after_call_value
+      definition.after_call_value.call(return_value)
+    end
+
+    def yields!(block)
+      if definition.yields_value
+        unless block
+          raise ArgumentError, "A Block must be passed into the method call when using yields"
+        end
+        block.call(*definition.yields_value)
       end
+    end
+    protected :yields!
 
-      unless matches.wildcard_non_terminal_scenarios_to_attempt.empty?
-        return matches.wildcard_non_terminal_scenarios_to_attempt.last
+    def call_implementation(double_insertion, *args, &block)
+      return nil unless implementation
+
+      if implementation === DoubleDefinition::ORIGINAL_METHOD
+        if double_insertion.object_has_original_method?
+          return double_insertion.call_original_method(*args, &block)
+        else
+          return double_insertion.object.__send__(
+            :method_missing,
+            method_name,
+            *args,
+            &block
+          )
+        end
       end
 
-      unless matches.matching_scenarios.empty?
-        # This will raise a TimesCalledError
-        return matches.matching_scenarios.first
+      if implementation.is_a?(Method)
+        return implementation.call(*args, &block)
+      else
+        args << block if block
+        return implementation.call(*args)
       end
+    end
+    protected :call_implementation
+
+    # Double#exact_match? returns true when the passed in arguments
+    # exactly match the ArgumentEqualityExpectation arguments.
+    def exact_match?(*arguments)
+      definition.exact_match?(*arguments)
+    end
 
-      return nil
+    # Double#wildcard_match? returns true when the passed in arguments
+    # wildcard match the ArgumentEqualityExpectation arguments.
+    def wildcard_match?(*arguments)
+      definition.wildcard_match?(*arguments)
     end
 
-    def scenario_not_found_error(*args)
-      message = "No scenario for #{Scenario.formatted_name(@method_name, args)} in\n"
-      message << Scenario.list_message_part(@scenarios)
-      raise Errors::ScenarioNotFoundError, message
+    # Double#attempt? returns true when the
+    # TimesCalledExpectation is satisfied.
+    def attempt?
+      return true unless definition.times_matcher
+      times_called_expectation.attempt?
     end
 
-    def placeholder_name
-      "__rr__#{@method_name}"
+    # Double#verify verifies the the TimesCalledExpectation
+    # is satisfied for this scenario. A TimesCalledError
+    # is raised if the TimesCalledExpectation is not met.
+    def verify
+      return true unless definition.times_matcher
+      times_called_expectation.verify!
+      true
+    end
+
+    def terminal?
+      return false unless definition.times_matcher
+      times_called_expectation.terminal?
+    end
+
+    # The method name that this Double is attatched to
+    def method_name
+      double_insertion.method_name
+    end
+
+    # The Arguments that this Double expects
+    def expected_arguments
+      return [] unless argument_expectation
+      argument_expectation.expected_arguments
     end
 
-    def original_method_name
-      "__rr__original_#{@method_name}"
+    # The TimesCalledMatcher for the TimesCalledExpectation
+    def times_matcher
+      times_called_expectation.matcher
     end
 
-    def object_has_method?(method_name)
-      @object.methods.include?(method_name.to_s) || @object.respond_to?(method_name)
+    def times_called_expectation
+      @times_called_expectation.matcher = definition.times_matcher
+      @times_called_expectation
+    end
+
+    def implementation
+      definition.implementation
+    end
+    def implementation=(value)
+      definition.implementation = value
+    end
+    protected :implementation=
+
+    def argument_expectation
+      definition.argument_expectation
+    end
+    def argument_expectation=(value)
+      definition.argument_expectation = value
     end
+    protected :argument_expectation=
 
-    def meta
-      (class << @object; self; end)
+    def formatted_name
+      self.class.formatted_name(method_name, expected_arguments)
     end
   end
-end
+end

data/lib/rr/{scenario_creator.rb → double_creator.rb}

@@ -1,12 +1,11 @@
 module RR
-  # RR::ScenarioCreator provides a strategies to create a Scenario.
+  # RR::DoubleCreator provides a strategies to create a Double.
   # The strategies are:
   # * mock
   # * stub
-  # * do_not_call
-  #
-  # Probing can also be added.
-  class ScenarioCreator
+  # * proxy
+  # * dont_allow
+  class DoubleCreator
     NO_SUBJECT_ARG = Object.new
 
     attr_reader :space
@@ -15,29 +14,29 @@ module RR
     def initialize(space)
       @space = space
       @strategy = nil
-      @probe = false
+      @proxy = false
       @instance_of = nil
       @instance_of_method_name = nil
     end
     
-    # This method sets the Scenario to have a mock strategy. A mock strategy
-    # sets the default state of the Scenario to expect the method call
-    # with arguments exactly one time. The Scenario's expectations can be
+    # 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 probe.
-    #   mock.probe(subject).method_name_1
+    # This method can be chained with proxy.
+    #   mock.proxy(subject).method_name_1
     #   or
-    #   probe.mock(subject).method_name_1
+    #   proxy.mock(subject).method_name_1
     #
-    # When passed the subject, a ScenarioMethodProxy is returned. Passing
+    # 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.
     #   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 Scenario with the method already set.
+    # 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}
@@ -54,17 +53,17 @@ module RR
       RR::Space.scenario_method_proxy(self, subject, method_name, &definition)
     end
 
-    # This method sets the Scenario to have a stub strategy. A stub strategy
-    # sets the default state of the Scenario to expect the method call
-    # with any arguments any number of times. The Scenario's
+    # 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 probe.
-    #   stub.probe(subject).method_name_1
+    # This method can be chained with proxy.
+    #   stub.proxy(subject).method_name_1
     #   or
-    #   probe.stub(subject).method_name_1
+    #   proxy.stub(subject).method_name_1
     #
-    # When passed the subject, a ScenarioMethodProxy is returned. Passing
+    # 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.
@@ -72,7 +71,7 @@ module RR
     #   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 Scenario with the method already set.
+    # 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}
@@ -89,50 +88,50 @@ module RR
       RR::Space.scenario_method_proxy(self, subject, method_name, &definition)
     end
 
-    # This method sets the Scenario to have a do_not_call strategy.
-    # A do_not_call strategy sets the default state of the Scenario
-    # to expect never to be called. The Scenario's expectations can be
+    # 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(subject).method_name(arg1, arg2)
     #
-    # do_not_call also supports a block sytnax.
-    #    do_not_call(subject) do |m|
+    # 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 do_not_call(subject=NO_SUBJECT_ARG, method_name=nil, &definition)
+    def dont_allow(subject=NO_SUBJECT_ARG, method_name=nil, &definition)
       strategy_error! if @strategy
-      probe_when_do_not_call_error! if @probe
-      @strategy = :do_not_call
+      proxy_when_dont_allow_error! if @proxy
+      @strategy = :dont_allow
       return self if subject.__id__ === NO_SUBJECT_ARG.__id__
       RR::Space.scenario_method_proxy(self, subject, method_name, &definition)
     end
-    alias_method :dont_call, :do_not_call
-    alias_method :do_not_allow, :do_not_call
-    alias_method :dont_allow, :do_not_call
+    alias_method :do_not_allow, :dont_allow
+    alias_method :dont_call, :dont_allow
+    alias_method :do_not_call, :dont_allow
 
-    # This method add probe capabilities to the Scenario. probe can be called
+    # This method add proxy capabilities to the Double. proxy can be called
     # with mock or stub.
     #
-    #   mock.probe(controller.template).render(:partial => "my/socks")
+    #   mock.proxy(controller.template).render(:partial => "my/socks")
     #
-    #   stub.probe(controller.template).render(:partial => "my/socks") do |html|
+    #   stub.proxy(controller.template).render(:partial => "my/socks") do |html|
     #     html.should include("My socks are wet")
     #     html
     #   end
     #
-    #   mock.probe(controller.template).render(:partial => "my/socks") do |html|
+    #   mock.proxy(controller.template).render(:partial => "my/socks") do |html|
     #     html.should include("My socks are wet")
     #     "My new return value"
     #   end
     #
-    # mock.probe also takes a block for definitions.
-    #   mock.probe(subject) do
+    # mock.proxy also takes a block for definitions.
+    #   mock.proxy(subject) do
     #     render(:partial => "my/socks")
     #
     #     render(:partial => "my/socks") do |html|
@@ -151,31 +150,31 @@ module RR
     #     end
     #   end
     #
-    # Passing a block to the Scenario (after the method name and arguments)
+    # 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.probe(controller.template).render(:partial => "my/socks") do |html|
+    #   mock.proxy(controller.template).render(:partial => "my/socks") do |html|
     #     html.should include("My socks are wet")
     #     "My new return value"
     #   end
-    def probe(subject=NO_SUBJECT_ARG, method_name=nil, &definition)
-      probe_when_do_not_call_error! if @strategy == :do_not_call
-      @probe = true
+    def proxy(subject=NO_SUBJECT_ARG, method_name=nil, &definition)
+      proxy_when_dont_allow_error! if @strategy == :dont_allow
+      @proxy = true
       return self if subject.__id__ === NO_SUBJECT_ARG.__id__
       RR::Space.scenario_method_proxy(self, subject, method_name, &definition)
     end
-    alias_method :proxy, :probe
+    alias_method :probe, :proxy
 
     # Calling instance_of will cause all instances of the passed in Class
-    # to have the Scenario defined.
+    # 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 probes User#projects and returns the
+    # The following example mocks and proxies User#projects and returns the
     # first 3 projects.
     #   mock.instance_of(User).projects do |projects|
     #     projects[0..2]
@@ -201,45 +200,45 @@ module RR
     
     protected
     def setup_scenario(subject, method_name)
-      @double = @space.double(subject, method_name)
-      @scenario = @space.scenario(@double)
+      @double_insertion = @space.double_insertion(subject, method_name)
+      @scenario = @space.scenario(@double_insertion)
       @definition = @scenario.definition
     end
 
     def setup_class_probing_instances(subject, method_name)
-      class_double = @space.double(subject, :new)
+      class_double = @space.double_insertion(subject, :new)
       class_scenario = @space.scenario(class_double)
 
       instance_method_name = method_name
 
       @definition = @space.scenario_definition
       class_handler = proc do |return_value|
-        double = @space.double(return_value, instance_method_name)
-        @space.scenario(double, @definition)
+        double_insertion = @space.double_insertion(return_value, instance_method_name)
+        @space.scenario(double_insertion, @definition)
         return_value
       end
 
-      builder = ScenarioDefinitionBuilder.new(
+      builder = DoubleDefinitionBuilder.new(
         class_scenario.definition,
         [],
         class_handler
       )
       builder.stub!
-      builder.probe!
+      builder.proxy!
     end
 
     def transform!
-      builder = ScenarioDefinitionBuilder.new(@definition, @args, @handler)
+      builder = DoubleDefinitionBuilder.new(@definition, @args, @handler)
 
       case @strategy
       when :mock; builder.mock!
       when :stub; builder.stub!
-      when :do_not_call; builder.do_not_call!
+      when :dont_allow; builder.dont_allow!
       else no_strategy_error!
       end
       
-      if @probe
-        builder.probe!
+      if @proxy
+        builder.proxy!
       else
         builder.reimplementation!
       end
@@ -247,22 +246,22 @@ module RR
 
     def strategy_error!
       raise(
-        ScenarioDefinitionError,
-        "This Scenario already has a #{@strategy} strategy"
+        DoubleDefinitionError,
+        "This Double already has a #{@strategy} strategy"
       )
     end
 
     def no_strategy_error!
       raise(
-        ScenarioDefinitionError,
-        "This Scenario has no strategy"
+        DoubleDefinitionError,
+        "This Double has no strategy"
       )
     end
 
-    def probe_when_do_not_call_error!
+    def proxy_when_dont_allow_error!
       raise(
-        ScenarioDefinitionError,
-        "Scenarios cannot be probed when using do_not_call strategy"
+        DoubleDefinitionError,
+        "Doubles cannot be proxied when using dont_allow strategy"
       )
     end
   end