mocha 0.5.6 → 3.1.0

data/lib/mocha/mock.rb

@@ -1,97 +1,207 @@
+# frozen_string_literal: true
+
+require 'ruby2_keywords'
 require 'mocha/expectation'
 require 'mocha/expectation_list'
-require 'mocha/stub'
-require 'mocha/missing_expectation'
-require 'mocha/metaclass'
+require 'mocha/invocation'
+require 'mocha/default_name'
+require 'mocha/default_receiver'
+require 'mocha/method_matcher'
+require 'mocha/parameters_matcher'
+require 'mocha/argument_iterator'
+require 'mocha/expectation_error_factory'
+require 'mocha/deprecation'
 
-module Mocha # :nodoc:
-  
+module Mocha
   # Traditional mock object.
   #
-  # Methods return an Expectation which can be further modified by methods on Expectation.
+  # {expects} and {stubs} return an {Expectation} which can be further modified
+  # by methods on {Expectation}.
+  #
+  # {responds_like} and {responds_like_instance_of} both return a {Mock}, and
+  # can therefore, be chained to the original creation methods in {API}.
+  # They force the mock to indicate what it is supposed to be mocking, thus
+  # making it a safer verifying mock. They check that the underlying +responder+
+  # will actually respond to the methods being stubbed, throwing a
+  # +NoMethodError+ upon invocation otherwise.
+  #
+  # Stubs and expectations are basically the same thing. A stub is just an
+  # expectation of zero or more invocations. The {#stubs} method is syntactic
+  # sugar to make the intent of the test more explicit.
+  #
+  # When a method is invoked on a mock object, the mock object searches through
+  # its expectations from newest to oldest to find one that matches the
+  # invocation. After the invocation, the matching expectation might stop
+  # matching further invocations. For example, an +expects(:foo).once+
+  # expectation only matches once and will be ignored on future invocations
+  # while an +expects(:foo).at_least_once+ expectation will always be matched
+  # against invocations.
+  #
+  # However, note that if the expectation that matches the invocation has a
+  # cardinality of "never", then an unexpected invocation error is reported.
+  #
+  # This scheme allows you to:
+  #
+  # - Set up default stubs in your the +setup+ method of your test class and
+  #   override some of those stubs in individual tests.
+  # - Set up different +once+ expectations for the same method with different
+  #   action per invocation. However, it's better to use the
+  #   {Expectation#returns} method with multiple arguments to do this, as
+  #   described below.
+  #
+  # However, there are some possible "gotchas" caused by this scheme:
+  #
+  # - if you create an expectation and then a stub for the same method, the
+  #   stub will always override the expectation and the expectation will never
+  #   be met.
+  # - if you create a stub and then an expectation for the same method, the
+  #   expectation will match, and when it stops matching the stub will be used
+  #   instead, possibly masking test failures.
+  # - if you create different expectations for the same method, they will be
+  #   invoked in the opposite order than that in which they were specified,
+  #   rather than the same order.
+  #
+  # The best thing to do is not set up multiple expectations and stubs for the
+  # same method with exactly the same matchers. Instead, use the
+  # {Expectation#returns} method with multiple arguments to create multiple
+  # actions for a method. You can also chain multiple calls to
+  # {Expectation#returns} and {Expectation#raises} (along with syntactic sugar
+  # {Expectation#then} if desired).
+  #
+  # @example
+  #   object = mock()
+  #   object.stubs(:expected_method).returns(1, 2).then.raises(Exception)
+  #   object.expected_method # => 1
+  #   object.expected_method # => 2
+  #   object.expected_method # => raises exception of class Exception1
+  #
+  # If you want to specify more complex ordering or order invocations across
+  # different mock objects, use the {Expectation#in_sequence} method to
+  # explicitly define a total or partial ordering of invocations.
   class Mock
-    
-    # :call-seq: expects(method_name) -> expectation
-    #            expects(method_names) -> last expectation
+    # Adds an expectation that the specified method must be called exactly once with any parameters.
     #
-    # Adds an expectation that a method identified by +method_name+ symbol must be called exactly once with any parameters.
-    # Returns the new expectation which can be further modified by methods on Expectation.
-    #   object = mock()
-    #   object.expects(:method1)
-    #   object.method1
-    #   # no error raised
+    # @return [Expectation] last-built expectation which can be further modified by methods on {Expectation}.
     #
+    # @overload def expects(method_name)
+    #   @param [Symbol,String] method_name name of expected method
+    # @overload def expects(expected_methods_vs_return_values)
+    #   @param [Hash] expected_methods_vs_return_values expected method name symbols as keys and corresponding return values as values - these expectations are setup as if {#expects} were called multiple times.
+    #
+    # @example Expected method invoked once so no error raised
     #   object = mock()
-    #   object.expects(:method1)
-    #   # error raised, because method1 not called exactly once
-    # If +method_names+ is a +Hash+, an expectation will be set up for each entry using the key as +method_name+ and value as +return_value+.
+    #   object.expects(:expected_method)
+    #   object.expected_method
+    #
+    # @example Expected method not invoked so error raised
     #   object = mock()
-    #   object.expects(:method1 => :result1, :method2 => :result2)
+    #   object.expects(:expected_method)
+    #   # error raised when test completes, because expected_method not called exactly once
     #
-    #   # exactly equivalent to
+    # @example Expected method invoked twice so error raised
+    #   object = mock()
+    #   object.expects(:expected_method)
+    #   object.expected_method
+    #   object.expected_method # => error raised when expected method invoked second time
     #
+    # @example Setup multiple expectations using +expected_methods_vs_return_values+.
     #   object = mock()
-    #   object.expects(:method1).returns(:result1)
-    #   object.expects(:method2).returns(:result2)
+    #   object.expects(expected_method_one: :result_one, expected_method_two: :result_two)
     #
-    # Aliased by <tt>\_\_expects\_\_</tt>
+    #   # is exactly equivalent to
+    #
+    #   object = mock()
+    #   object.expects(:expected_method_one).returns(:result_one)
+    #   object.expects(:expected_method_two).returns(:result_two)
     def expects(method_name_or_hash, backtrace = nil)
-      if method_name_or_hash.is_a?(Hash) then
-        method_name_or_hash.each do |method_name, return_value|
-          ensure_method_not_already_defined(method_name)
-          @expectations.add(Expectation.new(self, method_name, backtrace).returns(return_value))
-        end
-      else
-        ensure_method_not_already_defined(method_name_or_hash)
-        @expectations.add(Expectation.new(self, method_name_or_hash, backtrace))
+      expectation = nil
+      iterator = ArgumentIterator.new(method_name_or_hash)
+      iterator.each do |method_name, *args|
+        ensure_method_not_already_defined(method_name)
+        expectation = Expectation.new(self, method_name, backtrace)
+        expectation.in_sequence(@mockery.sequences.last) if @mockery.sequences.any?
+        expectation.returns(args.shift) unless args.empty?
+        @expectations.add(expectation)
       end
+      expectation
     end
-    
-    # :call-seq: stubs(method_name) -> expectation
-    #            stubs(method_names) -> last expectation
+
+    # Adds an expectation that the specified method may be called any number of times with any parameters.
+    #
+    # @return [Expectation] last-built expectation which can be further modified by methods on {Expectation}.
     #
-    # Adds an expectation that a method identified by +method_name+ symbol may be called any number of times with any parameters.
-    # Returns the new expectation which can be further modified by methods on Expectation.
+    # @overload def stubs(method_name)
+    #   @param [Symbol,String] method_name name of stubbed method
+    # @overload def stubs(stubbed_methods_vs_return_values)
+    #   @param [Hash] stubbed_methods_vs_return_values stubbed method name symbols as keys and corresponding return values as values - these stubbed methods are setup as if {#stubs} were called multiple times.
+    #
+    # @example No error raised however many times stubbed method is invoked
     #   object = mock()
-    #   object.stubs(:method1)
-    #   object.method1
-    #   object.method1
+    #   object.stubs(:stubbed_method)
+    #   object.stubbed_method
+    #   object.stubbed_method
     #   # no error raised
-    # If +method_names+ is a +Hash+, an expectation will be set up for each entry using the key as +method_name+ and value as +return_value+.
+    #
+    # @example Setup multiple expectations using +stubbed_methods_vs_return_values+.
     #   object = mock()
-    #   object.stubs(:method1 => :result1, :method2 => :result2)
+    #   object.stubs(stubbed_method_one: :result_one, stubbed_method_two: :result_two)
     #
-    #   # exactly equivalent to
+    #   # is exactly equivalent to
     #
     #   object = mock()
-    #   object.stubs(:method1).returns(:result1)
-    #   object.stubs(:method2).returns(:result2)
-    #
-    # Aliased by <tt>\_\_stubs\_\_</tt>
+    #   object.stubs(:stubbed_method_one).returns(:result_one)
+    #   object.stubs(:stubbed_method_two).returns(:result_two)
     def stubs(method_name_or_hash, backtrace = nil)
-      if method_name_or_hash.is_a?(Hash) then
-        method_name_or_hash.each do |method_name, return_value|
-          ensure_method_not_already_defined(method_name)
-          @expectations.add(Stub.new(self, method_name, backtrace).returns(return_value))
-        end
-      else
-        ensure_method_not_already_defined(method_name_or_hash)
-        @expectations.add(Stub.new(self, method_name_or_hash, backtrace))
+      expectation = nil
+      iterator = ArgumentIterator.new(method_name_or_hash)
+      iterator.each do |method_name, *args|
+        ensure_method_not_already_defined(method_name)
+        expectation = Expectation.new(self, method_name, backtrace)
+        expectation.at_least(0)
+        expectation.in_sequence(@mockery.sequences.last) if @mockery.sequences.any?
+        expectation.returns(args.shift) unless args.empty?
+        @expectations.add(expectation)
       end
+      expectation
     end
-    
-    # :call-seq: responds_like(responder) -> mock
+
+    # Removes the specified stubbed methods (added by calls to {#expects} or {#stubs}) and all expectations associated with them.
     #
-    # Constrains the +mock+ so that it can only expect or stub methods to which +responder+ responds. The constraint is only applied at method invocation time.
+    # @param [Array<Symbol>] method_names names of methods to unstub.
     #
-    # A +NoMethodError+ will be raised if the +responder+ does not <tt>respond_to?</tt> a method invocation (even if the method has been expected or stubbed).
+    # @example Invoking an unstubbed method causes error to be raised
+    #   object = mock('mock')
+    #   object.stubs(:stubbed_method).returns(:result_one)
+    #   object.stubbed_method # => :result_one
+    #   object.unstub(:stubbed_method)
+    #   object.stubbed_method # => unexpected invocation: #<Mock:mock>.stubbed_method()
     #
-    # The +mock+ will delegate its <tt>respond_to?</tt> method to the +responder+.
-    #   class Sheep
-    #     def chew(grass); end
-    #     def self.number_of_legs; end
-    #   end
+    # @example Unstubbing multiple methods.
+    #   multiplier.unstub(:double, :triple)
+    #
+    #   # exactly equivalent to
+    #
+    #   multiplier.unstub(:double)
+    #   multiplier.unstub(:triple)
+    def unstub(*method_names)
+      method_names.each do |method_name|
+        @expectations.remove_all_matching_method(method_name)
+      end
+    end
+
+    # Constrains the {Mock} instance so that it can only expect or stub methods to which +responder+ responds publicly. The constraint is only applied at method invocation time.
     #
+    # A +NoMethodError+ will be raised if the +responder+ does not publicly +#respond_to?+ the invoked method (even if the method has been expected or stubbed).
+    #
+    # The {Mock} instance will delegate its +#respond_to?+ method to the +responder+. However, the +include_all+ parameter is not passed through, so only public methods on the +responder+ will be considered.
+    #
+    # Note that the methods on +responder+ are never actually invoked.
+    #
+    # @param [Object, #respond_to?] responder an object used to determine whether {Mock} instance should +#respond_to?+ to an invocation.
+    # @return [Mock] the same {Mock} instance, thereby allowing invocations of other {Mock} methods to be chained.
+    # @see #responds_like_instance_of
+    #
+    # @example Normal mocking
     #   sheep = mock('sheep')
     #   sheep.expects(:chew)
     #   sheep.expects(:foo)
@@ -101,6 +211,11 @@ module Mocha # :nodoc:
     #   sheep.foo
     #   # no error raised
     #
+    # @example Using {#responds_like} with an instance method
+    #   class Sheep
+    #     def chew(grass); end
+    #   end
+    #
     #   sheep = mock('sheep')
     #   sheep.responds_like(Sheep.new)
     #   sheep.expects(:chew)
@@ -110,93 +225,203 @@ module Mocha # :nodoc:
     #   sheep.chew
     #   sheep.foo # => raises NoMethodError exception
     #
+    # @example Using {#responds_like} with a class method
+    #   class Sheep
+    #     def self.number_of_legs; end
+    #   end
+    #
     #   sheep_class = mock('sheep_class')
     #   sheep_class.responds_like(Sheep)
     #   sheep_class.stubs(:number_of_legs).returns(4)
     #   sheep_class.expects(:foo)
     #   sheep_class.respond_to?(:number_of_legs) # => true
     #   sheep_class.respond_to?(:foo) # => false
-    #   assert_equal 4, sheep_class.number_of_legs
+    #   sheep_class.number_of_legs # => 4
     #   sheep_class.foo # => raises NoMethodError exception
-    #
-    # Aliased by +quacks_like+
-    def responds_like(object)
-      @responder = object
+    def responds_like(responder)
+      @responder = responder
       self
     end
-    
-    # :stopdoc:
-    
-    def initialize(name = nil, &block)
-      @mock_name = name
+
+    # Constrains the {Mock} instance so that it can only expect or stub methods to which an instance of the +responder_class+ responds publicly. The constraint is only applied at method invocation time. Note that the responder instance is instantiated using +Class#allocate+.
+    #
+    # A +NoMethodError+ will be raised if the responder instance does not publicly +#respond_to?+ the invoked method (even if the method has been expected or stubbed).
+    #
+    # The {Mock} instance will delegate its +#respond_to?+ method to the responder instance. However, the +include_all+ parameter is not passed through, so only public methods on the +responder+  will be considered.
+    #
+    # Note that the methods on the responder instance are never actually invoked.
+    #
+    # @param [Class] responder_class a class used to determine whether {Mock} instance should +#respond_to?+ to an invocation.
+    # @return [Mock] the same {Mock} instance, thereby allowing invocations of other {Mock} methods to be chained.
+    # @see #responds_like
+    #
+    # @example Using {#responds_like_instance_of}
+    #   class Sheep
+    #     def initialize
+    #       raise "some awkward code we don't want to call"
+    #     end
+    #     def chew(grass); end
+    #   end
+    #
+    #   sheep = mock('sheep')
+    #   sheep.responds_like_instance_of(Sheep)
+    #   sheep.expects(:chew)
+    #   sheep.expects(:foo)
+    #   sheep.respond_to?(:chew) # => true
+    #   sheep.respond_to?(:foo) # => false
+    #   sheep.chew
+    #   sheep.foo # => raises NoMethodError exception
+    def responds_like_instance_of(responder_class)
+      responds_like(responder_class.allocate)
+    end
+
+    # @private
+    def initialize(mockery, assertion_counter, name = nil, receiver = nil)
+      @mockery = mockery
+      @assertion_counter = assertion_counter
+      @name = name || DefaultName.new(self)
+      @receiver = receiver || DefaultReceiver.new(self)
       @expectations = ExpectationList.new
       @everything_stubbed = false
       @responder = nil
-      instance_eval(&block) if block
+      @unexpected_invocation = nil
+      @expired = false
     end
 
-    attr_reader :everything_stubbed, :expectations
+    # @private
+    attr_reader :everything_stubbed
 
     alias_method :__expects__, :expects
 
     alias_method :__stubs__, :stubs
-    
+
+    alias_method :__singleton_class__, :singleton_class
+
     alias_method :quacks_like, :responds_like
+    alias_method :quacks_like_instance_of, :responds_like_instance_of
 
-    def add_expectation(expectation)
-      @expectations.add(expectation)
+    # @private
+    def __expectations__
+      @expectations
     end
-    
+
+    # @private
     def stub_everything
       @everything_stubbed = true
     end
-    
+
+    # @private
+    def all_expectations
+      @receiver.mocks.inject(ExpectationList.new) { |e, m| e + m.__expectations__ }
+    end
+
+    # @private
     def method_missing(symbol, *arguments, &block)
-      if @responder and not @responder.respond_to?(symbol)
-        raise NoMethodError, "undefined method `#{symbol}' for #{self.mocha_inspect} which responds like #{@responder.mocha_inspect}"
+      handle_method_call(symbol, arguments, block)
+    end
+    ruby2_keywords(:method_missing)
+
+    # @private
+    def handle_method_call(symbol, arguments, block)
+      check_expiry
+      check_responder_responds_to(symbol)
+      invocation = Invocation.new(self, symbol, arguments, block)
+
+      matching_expectations = all_expectations.matching_expectations(invocation)
+
+      index = 0
+      while index < matching_expectations.length
+        matching_expectation = matching_expectations[index]
+        if matching_expectation.invocations_never_allowed?
+          raise_unexpected_invocation_error(invocation, matching_expectation)
+        elsif matching_expectation.invocations_allowed?
+          return matching_expectation.invoke(invocation)
+        end
+        index += 1
       end
-      matching_expectation = @expectations.detect(symbol, *arguments)
-      if matching_expectation then
-        matching_expectation.invoke(&block)
-      elsif @everything_stubbed then
-        return
-      else
-        unexpected_method_called(symbol, *arguments)
+
+      matching_expectation_ignoring_order = all_expectations.match(invocation, ignoring_order: true)
+      if matching_expectation_ignoring_order || (!matching_expectation_ignoring_order && !@everything_stubbed) # rubocop:disable Style/GuardClause
+        raise_unexpected_invocation_error(invocation, matching_expectation_ignoring_order)
       end
     end
-    
-    def respond_to?(symbol)
-      if @responder then
+
+    # @private
+    def respond_to_missing?(symbol, _include_all)
+      if @responder
         @responder.respond_to?(symbol)
       else
-        @expectations.matches_method?(symbol)
+        @everything_stubbed || all_expectations.matches_method?(symbol)
       end
     end
-  
-    def unexpected_method_called(symbol, *arguments)
-      MissingExpectation.new(self, symbol).with(*arguments).verify
+
+    # @private
+    def __verified__?
+      @expectations.verified?(@assertion_counter)
     end
-  
-    def verify(&block)
-      @expectations.verify(&block)
+
+    # @private
+    def __expire__(origin)
+      @expired = origin || true
     end
-  
+
+    # @private
     def mocha_inspect
-      address = self.__id__ * 2
-      address += 0x100000000 if address < 0
-      @mock_name ? "#<Mock:#{@mock_name}>" : "#<Mock:0x#{'%x' % address}>"
+      @name.mocha_inspect
     end
-    
+
+    # @private
     def inspect
       mocha_inspect
     end
-    
+
+    # @private
     def ensure_method_not_already_defined(method_name)
-      self.__metaclass__.send(:undef_method, method_name) if self.__metaclass__.method_defined?(method_name)
+      __singleton_class__.send(:undef_method, method_name) if __singleton_class__.method_defined?(method_name) || __singleton_class__.private_method_defined?(method_name)
     end
 
-    # :startdoc:
+    # @private
+    def any_expectations?
+      @expectations.any?
+    end
 
-  end
+    private
 
+    def raise_unexpected_invocation_error(invocation, matching_expectation)
+      if @unexpected_invocation.nil?
+        @unexpected_invocation = invocation
+        if matching_expectation
+          matching_expectation.invoke(invocation)
+          @assertion_counter.increment
+        end
+        call_description = @unexpected_invocation.call_description
+        if matching_expectation && !matching_expectation.in_correct_order?
+          call_description += ' invoked out of order'
+        end
+        message = "#{call_description}\n#{@mockery.mocha_inspect}"
+      else
+        message = @unexpected_invocation.short_call_description
+      end
+      raise ExpectationErrorFactory.build("unexpected invocation: #{message}", caller)
+    end
+
+    def check_responder_responds_to(symbol)
+      if @responder && !@responder.respond_to?(symbol) # rubocop:disable Style/GuardClause
+        raise NoMethodError, "undefined method `#{symbol}' for #{mocha_inspect} which responds like #{@responder.mocha_inspect}"
+      end
+    end
+
+    def check_expiry
+      return unless @expired
+
+      origin = @expired == true ? 'one test' : @expired
+
+      sentences = [
+        "#{mocha_inspect} was instantiated in #{origin} but it is receiving invocations within another test.",
+        'This can lead to unintended interactions between tests and hence unexpected test failures.',
+        'Ensure that every test correctly cleans up any state that it introduces.'
+      ]
+      raise StubbingError.new(sentences.join(' '), caller)
+    end
+  end
 end