rspec-mocks 2.8.0.rc1 → 2.8.0.rc2

data/lib/rspec/mocks/any_instance.rb

@@ -1,18 +1,33 @@
 require 'rspec/mocks/any_instance/chain'
-require 'rspec/mocks/any_instance/stub_chain'
-require 'rspec/mocks/any_instance/stub_chain_chain'
-require 'rspec/mocks/any_instance/expectation_chain'
 require 'rspec/mocks/any_instance/message_chains'
 require 'rspec/mocks/any_instance/recorder'
 
 module RSpec
   module Mocks
     module AnyInstance
+      # Used to set stubs and message expectations on any instance of a given
+      # class. Returns a [Recorder](Recorder), which records messages like
+      # `stub` and `should_receive` for later playback on instances of the
+      # class.
+      #
+      # @example
+      #
+      #     Car.any_instance.should_receive(:go)
+      #     race = Race.new
+      #     race.cars << Car.new
+      #     race.go # assuming this delegates to all of its cars
+      #             # this example would pass
+      #
+      #     Account.any_instance.stub(:balance) { Money.new(:USD, 25) }
+      #     Account.new.balance # => Money.new(:USD, 25))
+      #
+      # @return [Recorder]
       def any_instance
         RSpec::Mocks::space.add(self)
         __recorder
       end
       
+      # @private
       def rspec_verify
         __recorder.verify
         super
@@ -21,6 +36,7 @@ module RSpec
         @__recorder = nil
       end
 
+      # @private
       def __recorder
         @__recorder ||= AnyInstance::Recorder.new(self)
       end

data/lib/rspec/mocks/any_instance/chain.rb

@@ -2,25 +2,47 @@ module RSpec
   module Mocks
     module AnyInstance
       class Chain
-        [
-          :with, :and_return, :and_raise, :and_yield,
-          :once, :twice, :any_number_of_times,
-          :exactly, :times, :never,
-          :at_least, :at_most
-          ].each do |method_name|
+        class << self
+          private
+
+          # @macro [attach] record
+          #   @method $1(*args, &block)
+          #   Records the `$1` message for playback against an instance that
+          #   invokes a method stubbed or mocked using `any_instance`.
+          #
+          #   @see RSpec::Mocks::MessageExpectation#$1
+          #
+          def record(method_name)
             class_eval(<<-EOM, __FILE__, __LINE__)
               def #{method_name}(*args, &block)
                 record(:#{method_name}, *args, &block)
               end
             EOM
+          end
         end
 
+        record :and_return
+        record :and_raise
+        record :and_throw
+        record :and_yield
+        record :with
+        record :once
+        record :twice
+        record :any_number_of_times
+        record :exactly
+        record :times
+        record :never
+        record :at_least
+        record :at_most
+
+        # @private
         def playback!(instance)
           messages.inject(instance) do |_instance, message|
             _instance.__send__(*message.first, &message.last)
           end
         end
 
+        # @private
         def constrained_to_any_of?(*constraints)
           constraints.any? do |constraint|
             messages.any? do |message|
@@ -29,7 +51,13 @@ module RSpec
           end
         end
 
+        # @private
+        def expectation_fulfilled!
+          @expectation_fulfilled = true
+        end
+
         private
+
         def messages
           @messages ||= []
         end
@@ -44,6 +72,87 @@ module RSpec
           self
         end
       end
+
+      # @private
+      class ExpectationChain < Chain
+
+        # @private
+        def initialize(*args, &block)
+          record(:should_receive, *args, &block)
+          @expectation_fulfilled = false
+        end
+
+        # @private
+        def expectation_fulfilled?
+          @expectation_fulfilled || constrained_to_any_of?(:never, :any_number_of_times)
+        end
+
+        private
+
+        def verify_invocation_order(rspec_method_name, *args, &block)
+        end
+
+        def invocation_order
+          @invocation_order ||= {
+            :should_receive => [nil],
+            :with => [:should_receive],
+            :and_return => [:with, :should_receive],
+            :and_raise => [:with, :should_receive]
+          }
+        end
+      end
+
+      # @private
+      class StubChain < Chain
+
+        # @private
+        def initialize(*args, &block)
+          record(:stub, *args, &block)
+        end
+
+        # @private
+        def expectation_fulfilled?
+          true
+        end
+
+        private
+
+        def invocation_order
+          @invocation_order ||= {
+            :stub => [nil],
+            :with => [:stub],
+            :and_return => [:with, :stub],
+            :and_raise => [:with, :stub],
+            :and_yield => [:with, :stub]
+          }
+        end
+
+        def verify_invocation_order(rspec_method_name, *args, &block)
+          unless invocation_order[rspec_method_name].include?(last_message)
+            raise(NoMethodError, "Undefined method #{rspec_method_name}")
+          end
+        end
+      end
+
+      # @private
+      class StubChainChain < StubChain
+
+        # @private
+        def initialize(*args, &block)
+          record(:stub_chain, *args, &block)
+        end
+
+        private
+
+        def invocation_order
+          @invocation_order ||= {
+            :stub_chain => [nil],
+            :and_return => [:stub_chain],
+            :and_raise => [:stub_chain],
+            :and_yield => [:stub_chain]
+          }
+        end
+      end
     end
   end
 end

data/lib/rspec/mocks/any_instance/message_chains.rb

@@ -1,48 +1,60 @@
 module RSpec
   module Mocks
     module AnyInstance
+      # @private
       class MessageChains < Hash
+        def initialize
+          super {|h,k| h[k] = []}
+        end
+
+        # @private
         def add(method_name, chain)
-          (self[method_name] ||= []) << chain
+          self[method_name] << chain
+          chain
         end
-        
+
+        # @private
         def remove_stub_chains_for!(method_name)
-          chains = self[method_name]
-          chains.reject! { |chain| chain.is_a?(StubChain) || chain.is_a?(StubChainChain) }
+          self[method_name].reject! {|chain| chain.is_a?(StubChain)}
         end
-        
+
+        # @private
         def has_expectation?(method_name)
-          !!self[method_name].find{|chain| chain.is_a?(ExpectationChain)}
+          self[method_name].find {|chain| chain.is_a?(ExpectationChain)}
         end
-        
-        def each_expectation_fulfilled?
-          self.all? do |method_name, chains|
-            chains.all? { |chain| chain.expectation_fulfilled? }
-          end
+
+        # @private
+        def all_expectations_fulfilled?
+          all? {|method_name, chains| chains.all? {|chain| chain.expectation_fulfilled?}}
         end
 
+        # @private
         def unfulfilled_expectations
-          self.map do |method_name, chains|
+          map do |method_name, chains|
             method_name.to_s if chains.last.is_a?(ExpectationChain) unless chains.last.expectation_fulfilled?
           end.compact
         end
 
+        # @private
         def received_expected_message!(method_name)
-          self[method_name].each do |chain|
-            chain.expectation_fulfilled!
-          end
+          self[method_name].each {|chain| chain.expectation_fulfilled!}
         end
-        
+
+        # @private
         def playback!(instance, method_name)
-          self[method_name].each do |chain|
-            @instance_with_expectation = instance if instance.is_a?(ExpectationChain) && !@instance_with_expectation
-            if instance.is_a?(ExpectationChain) && !@instance_with_expectation.equal?(instance)
-              raise RSpec::Mocks::MockExpectationError, "Exactly one instance should have received the following message(s) but didn't: #{unfulfilled_expectations.sort.join(', ')}"
-            end
-            chain.playback!(instance)
+          raise_if_second_instance_to_receive_message(instance)
+          self[method_name].each {|chain| chain.playback!(instance)}
+        end
+
+        private
+
+        def raise_if_second_instance_to_receive_message(instance)
+          @instance_with_expectation ||= instance if instance.is_a?(ExpectationChain)
+          if instance.is_a?(ExpectationChain) && !@instance_with_expectation.equal?(instance)
+            raise RSpec::Mocks::MockExpectationError, "Exactly one instance should have received the following message(s) but didn't: #{unfulfilled_expectations.sort.join(', ')}"
           end
         end
       end
     end
   end
-end
+end

data/lib/rspec/mocks/any_instance/recorder.rb

@@ -1,8 +1,18 @@
 module RSpec
   module Mocks
     module AnyInstance
+      # Given a class `TheClass`, `TheClass.any_instance` returns a `Recorder`,
+      # which records stubs and message expectations for later playback on
+      # instances of `TheClass`.
+      #
+      # Further constraints are stored in instances of [Chain](Chain).
+      #
+      # @see AnyInstance
+      # @see Chain
       class Recorder
+        # @private
         attr_reader :message_chains
+
         def initialize(klass)
           @message_chains = MessageChains.new
           @observed_methods = []
@@ -10,7 +20,49 @@ module RSpec
           @klass = klass
           @expectation_set = false
         end
-        
+
+        # Initializes the recording a stub to be played back against any
+        # instance of this object that invokes the submitted method.
+        #
+        # @see Methods#stub
+        def stub(method_name_or_method_map, &block)
+          if method_name_or_method_map.is_a?(Hash)
+            method_name_or_method_map.each do |method_name, return_value|
+              stub(method_name).and_return(return_value)
+            end
+          else
+            observe!(method_name_or_method_map)
+            message_chains.add(method_name_or_method_map, StubChain.new(method_name_or_method_map, &block))
+          end
+        end
+
+        # Initializes the recording a stub chain to be played back against any
+        # instance of this object that invokes the method matching the first
+        # argument.
+        #
+        # @see Methods#stub_chain
+        def stub_chain(*method_names_and_optional_return_values, &block)
+          normalize_chain(*method_names_and_optional_return_values) do |method_name, args|
+            observe!(method_name)
+            message_chains.add(method_name, StubChainChain.new(*args, &block))
+          end
+        end
+
+        # Initializes the recording a message expectation to be played back
+        # against any instance of this object that invokes the submitted
+        # method.
+        #
+        # @see Methods#should_receive
+        def should_receive(method_name, &block)
+          @expectation_set = true
+          observe!(method_name)
+          message_chains.add(method_name, ExpectationChain.new(method_name, &block))
+        end
+
+        # Removes any previously recorded stubs, stub_chains or message
+        # expectations that use `method_name`.
+        #
+        # @see Methods#unstub
         def unstub(method_name)
           unless @observed_methods.include?(method_name.to_sym)
             raise RSpec::Mocks::MockExpectationError, "The method `#{method_name}` was not stubbed or was already unstubbed"
@@ -18,52 +70,28 @@ module RSpec
           message_chains.remove_stub_chains_for!(method_name)
           stop_observing!(method_name) unless message_chains.has_expectation?(method_name)
         end
-        
-        def stub(method_name_or_method_map, *args, &block)
-          if method_name_or_method_map.is_a?(Hash)
-            method_map = method_name_or_method_map
-            method_map.each do |method_name, return_value| 
-              observe!(method_name)
-              message_chains.add(method_name, chain = StubChain.new(method_name))
-              chain.and_return(return_value)
-            end
-            method_map
-          else
-            method_name = method_name_or_method_map
-            observe!(method_name)
-            message_chains.add(method_name, chain = StubChain.new(method_name, *args, &block))
-            chain
+
+        # @api private
+        #
+        # Used internally to verify that message expectations have been
+        # fulfilled.
+        def verify
+          if @expectation_set && !message_chains.all_expectations_fulfilled?
+            raise RSpec::Mocks::MockExpectationError, "Exactly one instance should have received the following message(s) but didn't: #{message_chains.unfulfilled_expectations.sort.join(', ')}"
           end
         end
 
+        # @private
         def stub!(*)
           raise "stub! is not supported on any_instance. Use stub instead."
         end
 
-        def stub_chain(method_name_or_string_chain, *args, &block)
-          if period_separated_method_chain?(method_name_or_string_chain)
-            first_method_name = method_name_or_string_chain.split('.').first.to_sym
-          else
-            first_method_name = method_name_or_string_chain
-          end
-          observe!(first_method_name)
-          message_chains.add(first_method_name, chain = StubChainChain.new(method_name_or_string_chain, *args, &block))
-          chain
-        end
-        
-        def should_receive(method_name, *args, &block)
-          observe!(method_name)
-          @expectation_set = true
-          message_chains.add(method_name, chain = ExpectationChain.new(method_name, *args, &block))
-          chain
-        end
-
+        # @private
         def stop_all_observation!
-          @observed_methods.each do |method_name|
-            restore_method!(method_name)
-          end
+          @observed_methods.each {|method_name| restore_method!(method_name)}
         end
 
+        # @private
         def playback!(instance, method_name)
           RSpec::Mocks::space.add(instance)
           message_chains.playback!(instance, method_name)
@@ -71,27 +99,24 @@ module RSpec
           received_expected_message!(method_name) if message_chains.has_expectation?(method_name)
         end
 
+        # @private
         def instance_that_received(method_name)
           @played_methods[method_name]
         end
 
-        def verify
-          if @expectation_set && !message_chains.each_expectation_fulfilled?
-            raise RSpec::Mocks::MockExpectationError, "Exactly one instance should have received the following message(s) but didn't: #{message_chains.unfulfilled_expectations.sort.join(', ')}"
-          end
-        end
-
         private
-        def period_separated_method_chain?(method_name)
-          method_name.is_a?(String) && method_name.include?('.')
+
+        def normalize_chain(*args)
+          args.shift.to_s.split('.').map {|s| s.to_sym}.reverse.each {|a| args.unshift a}
+          yield args.first, args
         end
-        
+
         def received_expected_message!(method_name)
           message_chains.received_expected_message!(method_name)
           restore_method!(method_name)
           mark_invoked!(method_name)
         end
-        
+
         def restore_method!(method_name)
           if public_protected_or_private_method_defined?(build_alias_method_name(method_name))
             restore_original_method!(method_name)
@@ -125,11 +150,11 @@ module RSpec
             alias_method alias_method_name, method_name
           end if public_protected_or_private_method_defined?(method_name)
         end
-        
+
         def public_protected_or_private_method_defined?(method_name)
           @klass.method_defined?(method_name) || @klass.private_method_defined?(method_name)
         end
-        
+
         def stop_observing!(method_name)
           restore_method!(method_name)
           @observed_methods.delete(method_name)