rr 0.3.3 → 0.3.4

data/lib/rr/scenario_creator.rb

@@ -9,7 +9,7 @@ module RR
   class ScenarioCreator
     NO_SUBJECT_ARG = Object.new
 
-    attr_reader :space, :subject
+    attr_reader :space
     include Errors
 
     def initialize(space)
@@ -17,26 +17,9 @@ module RR
       @strategy = nil
       @probe = false
       @instance_of = nil
+      @instance_of_method_name = nil
     end
     
-    def create!(subject, method_name, *args, &handler)
-      @subject = subject
-      @method_name = method_name
-      @args = args
-      @handler = handler
-      @double = @space.double(@subject, method_name)
-      @scenario = @space.scenario(@double)
-      transform!
-      @scenario
-    end
-
-#    def instance_of(subject=NO_SUBJECT_ARG, method_name=nil, &definition)
-#      return self if subject === NO_SUBJECT_ARG
-#      raise ArgumentError, "instance_of only accepts class objects" unless subject.is_a?(Class)
-#      @instance_of = true
-#      RR::Space.scenario_method_proxy(self, subject, method_name, &definition)
-#    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
@@ -184,53 +167,81 @@ module RR
       return self if subject.__id__ === NO_SUBJECT_ARG.__id__
       RR::Space.scenario_method_proxy(self, subject, method_name, &definition)
     end
-    
-    protected
-    def transform!
-      case @strategy
-      when :mock; mock!
-      when :stub; stub!
-      when :do_not_call; do_not_call!
-      else no_strategy_error!
-      end
-      
-      if @probe
-        probe!
+
+    # Calling instance_of will cause all instances of the passed in Class
+    # to have the Scenario 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
+    # first 3 projects.
+    #   mock.instance_of(User).projects do |projects|
+    #     projects[0..2]
+    #   end
+    def instance_of(subject=NO_SUBJECT_ARG, method_name=nil, &definition)
+      @instance_of = true
+      return self if subject === NO_SUBJECT_ARG
+      raise ArgumentError, "instance_of only accepts class objects" unless subject.is_a?(Class)
+      RR::Space.scenario_method_proxy(self, subject, method_name, &definition)
+    end
+
+    def create!(subject, method_name, *args, &handler)
+      @args = args
+      @handler = handler
+      if @instance_of
+        setup_class_probing_instances(subject, method_name)
       else
-        reimplementation!
+        setup_scenario(subject, method_name)
       end
+      transform!
+      @definition
     end
-
-    def mock!
-      @scenario.with(*@args).once
+    
+    protected
+    def setup_scenario(subject, method_name)
+      @double = @space.double(subject, method_name)
+      @scenario = @space.scenario(@double)
+      @definition = @scenario.definition
     end
 
-    def stub!
-      @scenario.any_number_of_times
-      permissive_argument!
-    end
+    def setup_class_probing_instances(subject, method_name)
+      class_double = @space.double(subject, :new)
+      class_scenario = @space.scenario(class_double)
 
-    def do_not_call!
-      @scenario.never
-      permissive_argument!
-      reimplementation!
-    end
+      instance_method_name = method_name
 
-    def permissive_argument!
-      if @args.empty?
-        @scenario.with_any_args
-      else
-        @scenario.with(*@args)
+      @definition = @space.scenario_definition
+      class_handler = proc do |return_value|
+        double = @space.double(return_value, instance_method_name)
+        @space.scenario(double, @definition)
+        return_value
       end
-    end
 
-    def reimplementation!
-      @scenario.returns(&@handler)
+      builder = ScenarioDefinitionBuilder.new(
+        class_scenario.definition,
+        [],
+        class_handler
+      )
+      builder.stub!
+      builder.probe!
     end
-    
-    def probe!
-      @scenario.implemented_by_original_method
-      @scenario.after_call(&@handler) if @handler
+
+    def transform!
+      builder = ScenarioDefinitionBuilder.new(@definition, @args, @handler)
+
+      case @strategy
+      when :mock; builder.mock!
+      when :stub; builder.stub!
+      when :do_not_call; builder.do_not_call!
+      else no_strategy_error!
+      end
+      
+      if @probe
+        builder.probe!
+      else
+        builder.reimplementation!
+      end
     end
 
     def strategy_error!

data/lib/rr/scenario_definition.rb

@@ -0,0 +1,277 @@
+module RR
+  # RR::Scenario is the use case for a method call.
+  # It has the ArgumentEqualityExpectation, TimesCalledExpectation,
+  # and the implementation.
+  class ScenarioDefinition
+    ORIGINAL_METHOD = Object.new
+    attr_accessor :times_called,
+                  :argument_expectation,
+                  :times_matcher,
+                  :double,
+                  :implementation,
+                  :after_call_value,
+                  :yields_value,
+                  :scenario
+
+    def initialize(space)
+      @space = space
+      @implementation = nil
+      @argument_expectation = nil
+      @times_matcher = nil
+      @after_call_value = nil
+      @yields_value = nil
+    end
+
+    # Scenario#with sets the expectation that the Scenario 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)
+      @argument_expectation = Expectations::ArgumentEqualityExpectation.new(*args)
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#with_any_args sets the expectation that the Scenario 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)
+      @argument_expectation = Expectations::AnyArgumentExpectation.new
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#with_no_args sets the expectation that the Scenario 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)
+      @argument_expectation = Expectations::ArgumentEqualityExpectation.new()
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#never sets the expectation that the Scenario will never be
+    # called.
+    #
+    # This method does not accept a block because it will never be called.
+    #
+    #   mock(subject).method_name.never
+    def never
+      @times_matcher = TimesCalledMatchers::IntegerMatcher.new(0)
+      self
+    end
+
+    # Scenario#once sets the expectation that the Scenario will be called
+    # 1 time.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.once {:return_value}
+    def once(&returns)
+      @times_matcher = TimesCalledMatchers::IntegerMatcher.new(1)
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#twice sets the expectation that the Scenario will be called
+    # 2 times.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.twice {:return_value}
+    def twice(&returns)
+      @times_matcher = TimesCalledMatchers::IntegerMatcher.new(2)
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#at_least sets the expectation that the Scenario
+    # 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)
+      @times_matcher = TimesCalledMatchers::AtLeastMatcher.new(number)
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#at_most allows sets the expectation that the Scenario
+    # 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)
+      @times_matcher = TimesCalledMatchers::AtMostMatcher.new(number)
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#any_number_of_times sets an that the Scenario will be called
+    # any number of times. This effectively removes the times called expectation
+    # from the Scenarion
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.any_number_of_times
+    def any_number_of_times(&returns)
+      @times_matcher = TimesCalledMatchers::AnyTimesMatcher.new
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#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(matcher_value, &returns)
+      @times_matcher = TimesCalledMatchers::TimesCalledMatcher.create(matcher_value)
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#ordered sets the Scenario to have an ordered
+    # expectation.
+    #
+    # Passing in a block sets the return value.
+    #
+    #   mock(subject).method_name.ordered {return_value}
+    def ordered(&returns)
+      raise(
+        Errors::ScenarioDefinitionError,
+        "Scenario Definitions must have a dedicated Scenario to be ordered. " <<
+        "For example, using instance_of does not allow ordered to be used. " <<
+        "probe the class's #new method instead."
+      ) unless @scenario
+      @ordered = true
+      @space.ordered_scenarios << @scenario unless @space.ordered_scenarios.include?(@scenario)
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#ordered? returns true when the Scenario is ordered.
+    #
+    #   mock(subject).method_name.ordered?
+    def ordered?
+      @ordered
+    end
+
+    # Scenario#yields sets the Scenario to invoke a passed in block when
+    # the Scenario is called.
+    # An Expection will be raised if no block is passed in when the
+    # Scenario 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)
+      @yields_value = args
+      returns(&returns) if returns
+      self
+    end
+
+    # Scenario#after_call creates a callback that occurs after call
+    # is called. The passed in block receives the return value of
+    # the Scenario 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 probes.
+    #   probe(User).find('1') {|user| mock(user).valid? {false}}
+    def after_call(&block)
+      raise ArgumentError, "after_call expects a block" unless block
+      @after_call_value = block
+      self
+    end
+
+    # Scenario#returns accepts an argument value or a block.
+    # It will raise an ArgumentError if both are passed in.
+    #
+    # Passing in a block causes Scenario to return the return value of
+    # the passed in block.
+    #
+    # Passing in an argument causes Scenario to return the argument.
+    def returns(value=nil, &implementation)
+      if value && implementation
+        raise ArgumentError, "returns cannot accept both an argument and a block"
+      end
+      if value.nil?
+        implemented_by implementation
+      else
+        implemented_by proc {value}
+      end
+      self
+    end
+
+    # Scenario#implemented_by sets the implementation of the Scenario.
+    # This method takes a Proc or a Method. Passing in a Method allows
+    # the Scenario 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)
+      @implementation = implementation
+      self
+    end
+
+    # Scenario#implemented_by_original_method sets the implementation
+    # of the Scenario to be the original method.
+    # This is primarily used with probes.
+    #
+    #   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
+      implemented_by ORIGINAL_METHOD
+      self
+    end
+
+    # Scenario#exact_match? returns true when the passed in arguments
+    # exactly match the ArgumentEqualityExpectation arguments.
+    def exact_match?(*arguments)
+      return false unless @argument_expectation
+      @argument_expectation.exact_match?(*arguments)
+    end
+
+    # Scenario#wildcard_match? returns true when the passed in arguments
+    # wildcard match the ArgumentEqualityExpectation arguments.
+    def wildcard_match?(*arguments)
+      return false unless @argument_expectation
+      @argument_expectation.wildcard_match?(*arguments)
+    end
+
+    def terminal?
+      return false unless @times_matcher
+      @times_matcher.terminal?
+    end
+
+    # The Arguments that this Scenario expects
+    def expected_arguments
+      return [] unless argument_expectation
+      argument_expectation.expected_arguments
+    end
+  end
+end

data/lib/rr/scenario_definition_builder.rb

@@ -0,0 +1,43 @@
+module RR
+  class ScenarioDefinitionBuilder
+    attr_reader :definition
+
+    def initialize(definition, args, handler)
+      @definition = definition
+      @args = args
+      @handler = handler
+    end
+    
+    def mock!
+      @definition.with(*@args).once
+    end
+
+    def stub!
+      @definition.any_number_of_times
+      permissive_argument!
+    end
+
+    def do_not_call!
+      @definition.never
+      permissive_argument!
+      reimplementation!
+    end
+
+    def permissive_argument!
+      if @args.empty?
+        @definition.with_any_args
+      else
+        @definition.with(*@args)
+      end
+    end
+
+    def reimplementation!
+      @definition.returns(&@handler)
+    end
+    
+    def probe!
+      @definition.implemented_by_original_method
+      @definition.after_call(&@handler) if @handler
+    end
+  end
+end