mocha 1.8.0 → 1.13.0

data/lib/mocha/api.rb

@@ -3,11 +3,33 @@ require 'mocha/hooks'
 require 'mocha/mockery'
 require 'mocha/sequence'
 require 'mocha/object_methods'
-require 'mocha/module_methods'
 require 'mocha/class_methods'
 
 module Mocha
   # Methods added to +Test::Unit::TestCase+, +MiniTest::Unit::TestCase+ or equivalent.
+  # The mock creation methods are {#mock}, {#stub} and {#stub_everything}, all of which return a #{Mock}
+  # which can be further modified by {Mock#responds_like} and {Mock#responds_like_instance_of} methods,
+  # both of which return a {Mock}, too, and can therefore, be chained to the original creation methods.
+  #
+  # {Mock#responds_like} and {Mock#responds_like_instance_of} 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.
+  #
+  # @example Verifying mock using {Mock#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').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
   module API
     include ParameterMatchers
     include Hooks
@@ -15,22 +37,26 @@ module Mocha
     # @private
     def self.included(_mod)
       Object.send(:include, Mocha::ObjectMethods)
-      Module.send(:include, Mocha::ModuleMethods)
       Class.send(:include, Mocha::ClassMethods)
     end
 
+    # @private
+    def self.extended(mod)
+      included(mod)
+    end
+
     # Builds a new mock object
     #
-    # @param [String] name identifies mock object in error messages.
-    # @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 {Mock#expects} were called multiple times.
-    # @yield optional block to be evaluated in the context of the mock object instance, giving an alternative way to setup stubbed methods.
-    # @yield note that the block is evaulated by calling Mock#instance_eval and so things like instance variables declared in the test will not be available within the block.
-    # @yield deprecated: use Object#tap or define stubs/expectations with an explicit receiver instead.
     # @return [Mock] a new mock object
     #
-    # @overload def mock(name, &block)
-    # @overload def mock(expected_methods_vs_return_values = {}, &block)
-    # @overload def mock(name, expected_methods_vs_return_values = {}, &block)
+    # @overload def mock(name)
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #   @note Prior to v1.10.0 when +name+ was a +Symbol+, this method returned an unnamed +Mock+ that expected the method identified by +name+. This was undocumented behaviour and it will be removed in the future, but for the moment it can be reinstated using {Configuration#reinstate_undocumented_behaviour_from_v1_9=}.
+    # @overload def mock(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 {Mock#expects} were called multiple times.
+    # @overload def mock(name, expected_methods_vs_return_values = {})
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #   @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 {Mock#expects} were called multiple times.
     #
     # @example Using expected_methods_vs_return_values Hash to setup expectations.
     #   def test_motor_starts_and_stops
@@ -39,36 +65,44 @@ module Mocha
     #     assert motor.stop
     #     # an error will be raised unless both Motor#start and Motor#stop have been called
     #   end
-    # @example Using the optional block to setup expectations & stubbed methods [deprecated].
-    #   def test_motor_starts_and_stops
-    #     motor = mock('motor') do
-    #       expects(:start).with(100.rpm).returns(true)
-    #       stubs(:stop).returns(true)
-    #     end
-    #     assert motor.start(100.rpm)
-    #     assert motor.stop
-    #     # an error will only be raised if Motor#start(100.rpm) has not been called
-    #   end
-    def mock(*arguments, &block)
-      name = arguments.shift if arguments.first.is_a?(String)
+    #
+    def mock(*arguments) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      if Mocha.configuration.reinstate_undocumented_behaviour_from_v1_9?
+        if arguments.first.is_a?(Symbol)
+          method_name = arguments[0]
+          Deprecation.warning(
+            "Explicitly include `#{method_name}` in Hash of expected methods vs return values,",
+            " e.g. `mock(:#{method_name} => nil)`."
+          )
+          if arguments[1]
+            Deprecation.warning(
+              "In this case the 2nd argument for `mock(:##{method_name}, ...)` is ignored,",
+              ' but in the future a Hash of expected methods vs return values will be respected.'
+            )
+          end
+        elsif arguments.first.is_a?(String)
+          name = arguments.shift
+        end
+      elsif arguments.first.is_a?(String) || arguments.first.is_a?(Symbol)
+        name = arguments.shift
+      end
       expectations = arguments.shift || {}
-      mock = name ? Mockery.instance.named_mock(name, &block) : Mockery.instance.unnamed_mock(&block)
+      mock = name ? Mockery.instance.named_mock(name) : Mockery.instance.unnamed_mock
       mock.expects(expectations)
       mock
     end
 
     # Builds a new mock object
     #
-    # @param [String] name identifies mock object in error messages.
-    # @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 {Mock#stubs} were called multiple times.
-    # @yield optional block to be evaluated in the context of the mock object instance, giving an alternative way to setup stubbed methods.
-    # @yield note that the block is evaulated by calling Mock#instance_eval and so things like instance variables declared in the test will not be available within the block.
-    # @yield deprecated: use Object#tap or define stubs/expectations with an explicit receiver instead.
     # @return [Mock] a new mock object
     #
-    # @overload def stub(name, &block)
-    # @overload def stub(stubbed_methods_vs_return_values = {}, &block)
-    # @overload def stub(name, stubbed_methods_vs_return_values = {}, &block)
+    # @overload def stub(name)
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #   @note Prior to v1.10.0 when +name+ was a +Symbol+, this method returned an unnamed +Mock+ that stubbed the method identified by +name+. This was undocumented behaviour and it will be removed in the future, but for the moment it can be reinstated using {Configuration#reinstate_undocumented_behaviour_from_v1_9=}.
+    # @overload def stub(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 {Mock#stubs} were called multiple times.
+    # @overload def stub(name, stubbed_methods_vs_return_values = {})
+    #   @param [String, Symbol] name identifies mock object in error messages.
     #
     # @example Using stubbed_methods_vs_return_values Hash to setup stubbed methods.
     #   def test_motor_starts_and_stops
@@ -77,37 +111,46 @@ module Mocha
     #     assert motor.stop
     #     # an error will not be raised even if either Motor#start or Motor#stop has not been called
     #   end
-    #
-    # @example Using the optional block to setup expectations & stubbed methods [deprecated].
-    #   def test_motor_starts_and_stops
-    #     motor = stub('motor') do
-    #       expects(:start).with(100.rpm).returns(true)
-    #       stubs(:stop).returns(true)
-    #     end
-    #     assert motor.start(100.rpm)
-    #     assert motor.stop
-    #     # an error will only be raised if Motor#start(100.rpm) has not been called
-    #   end
-    def stub(*arguments, &block)
-      name = arguments.shift if arguments.first.is_a?(String)
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    def stub(*arguments)
+      if Mocha.configuration.reinstate_undocumented_behaviour_from_v1_9?
+        if arguments.first.is_a?(Symbol)
+          method_name = arguments[0]
+          Deprecation.warning(
+            "Explicitly include `#{method_name}` in Hash of stubbed methods vs return values,",
+            " e.g. `stub(:#{method_name} => nil)`."
+          )
+          if arguments[1]
+            Deprecation.warning(
+              "In this case the 2nd argument for `stub(:##{method_name}, ...)` is ignored,",
+              ' but in the future a Hash of stubbed methods vs return values will be respected.'
+            )
+          end
+        elsif arguments.first.is_a?(String)
+          name = arguments.shift
+        end
+      elsif arguments.first.is_a?(String) || arguments.first.is_a?(Symbol)
+        name = arguments.shift
+      end
       expectations = arguments.shift || {}
-      stub = name ? Mockery.instance.named_mock(name, &block) : Mockery.instance.unnamed_mock(&block)
+      stub = name ? Mockery.instance.named_mock(name) : Mockery.instance.unnamed_mock
       stub.stubs(expectations)
       stub
     end
+    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
 
     # Builds a mock object that accepts calls to any method. By default it will return +nil+ for any method call.
     #
-    # @param [String] name identifies mock object in error messages.
-    # @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 {Mock#stubs} were called multiple times.
-    # @yield optional block to be evaluated in the context of the mock object instance, giving an alternative way to setup stubbed methods.
-    # @yield note that the block is evaulated by calling Mock#instance_eval and so things like instance variables declared in the test will not be available within the block.
-    # @yield deprecated: use Object#tap or define stubs/expectations with an explicit receiver instead.
     # @return [Mock] a new mock object
     #
-    # @overload def stub_everything(name, &block)
-    # @overload def stub_everything(stubbed_methods_vs_return_values = {}, &block)
-    # @overload def stub_everything(name, stubbed_methods_vs_return_values = {}, &block)
+    # @overload def stub_everything(name)
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #   @note Prior to v1.10.0 when +name+ was a +Symbol+, this method returned an unnamed +Mock+ that stubbed the method identified by +name+. This was undocumented behaviour and it will be removed in the future, but for the moment it can be reinstated using {Configuration#reinstate_undocumented_behaviour_from_v1_9=}.
+    # @overload def stub_everything(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 {Mock#stubs} were called multiple times.
+    # @overload def stub_everything(name, stubbed_methods_vs_return_values = {})
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #   @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 {Mock#stubs} were called multiple times.
     #
     # @example Ignore invocations of irrelevant methods.
     #   def test_motor_stops
@@ -116,14 +159,34 @@ module Mocha
     #     assert_nil motor.irrelevant_method_2 # => no error raised
     #     assert motor.stop
     #   end
-    def stub_everything(*arguments, &block)
-      name = arguments.shift if arguments.first.is_a?(String)
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    def stub_everything(*arguments)
+      if Mocha.configuration.reinstate_undocumented_behaviour_from_v1_9?
+        if arguments.first.is_a?(Symbol)
+          method_name = arguments[0]
+          Deprecation.warning(
+            "Explicitly include `#{method_name}` in Hash of stubbed methods vs return values,",
+            " e.g. `stub_everything(:#{method_name} => nil)`."
+          )
+          if arguments[1]
+            Deprecation.warning(
+              "In this case the 2nd argument for `stub_everything(:##{method_name}, ...)` is ignored,",
+              ' but in the future a Hash of stubbed methods vs return values will be respected.'
+            )
+          end
+        elsif arguments.first.is_a?(String)
+          name = arguments.shift
+        end
+      elsif arguments.first.is_a?(String) || arguments.first.is_a?(Symbol)
+        name = arguments.shift
+      end
       expectations = arguments.shift || {}
-      stub = name ? Mockery.instance.named_mock(name, &block) : Mockery.instance.unnamed_mock(&block)
+      stub = name ? Mockery.instance.named_mock(name) : Mockery.instance.unnamed_mock
       stub.stub_everything
       stub.stubs(expectations)
       stub
     end
+    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
 
     # Builds a new sequence which can be used to constrain the order in which expectations can occur.
     #

data/lib/mocha/block_matcher.rb

@@ -0,0 +1,31 @@
+module Mocha
+  module BlockMatchers
+    class OptionalBlock
+      def match?(_actual_block)
+        true
+      end
+
+      def mocha_inspect; end
+    end
+
+    class BlockGiven
+      def match?(actual_block)
+        !actual_block.nil?
+      end
+
+      def mocha_inspect
+        'with block given'
+      end
+    end
+
+    class NoBlockGiven
+      def match?(actual_block)
+        actual_block.nil?
+      end
+
+      def mocha_inspect
+        'with no block given'
+      end
+    end
+  end
+end

data/lib/mocha/cardinality.rb

@@ -2,85 +2,103 @@ module Mocha
   class Cardinality
     INFINITY = 1 / 0.0
 
-    class << self
-      def exactly(count)
-        new(count, count)
-      end
+    def initialize(required = 0, maximum = INFINITY)
+      update(required, maximum)
+      @invocations = []
+    end
 
-      def at_least(count)
-        new(count, INFINITY)
-      end
+    def exactly(count)
+      update(count, count)
+    end
 
-      def at_most(count)
-        new(0, count)
-      end
+    def at_least(count)
+      update(count, INFINITY)
+    end
+
+    def at_most(count)
+      update(0, count)
+    end
 
-      def times(range_or_count)
-        case range_or_count
-        when Range then new(range_or_count.first, range_or_count.last)
-        else new(range_or_count, range_or_count)
-        end
+    def times(range_or_count)
+      case range_or_count
+      when Range then update(range_or_count.first, range_or_count.last)
+      else update(range_or_count, range_or_count)
       end
     end
 
-    def initialize(required, maximum)
-      @required = required
-      @maximum = maximum
+    def <<(invocation)
+      @invocations << invocation
     end
 
-    def invocations_allowed?(invocation_count)
-      invocation_count < maximum
+    def invocations_allowed?
+      @invocations.size < maximum
     end
 
-    def satisfied?(invocations_so_far)
-      invocations_so_far >= required
+    def satisfied?
+      @invocations.size >= required
     end
 
     def needs_verifying?
       !allowed_any_number_of_times?
     end
 
-    def verified?(invocation_count)
-      (invocation_count >= required) && (invocation_count <= maximum)
+    def verified?
+      (@invocations.size >= required) && (@invocations.size <= maximum)
     end
 
     def allowed_any_number_of_times?
       required.zero? && infinite?(maximum)
     end
 
-    def used?(invocation_count)
-      (invocation_count > 0) || maximum.zero?
+    def used?
+      @invocations.any? || maximum.zero?
     end
 
-    def mocha_inspect
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    def anticipated_times
       if allowed_any_number_of_times?
         'allowed any number of times'
       elsif required.zero? && maximum.zero?
-        'expected never'
+        "expected #{count(maximum)}"
       elsif required == maximum
-        "expected exactly #{times(required)}"
+        "expected exactly #{count(required)}"
       elsif infinite?(maximum)
-        "expected at least #{times(required)}"
+        "expected at least #{count(required)}"
       elsif required.zero?
-        "expected at most #{times(maximum)}"
+        "expected at most #{count(maximum)}"
       else
-        "expected between #{required} and #{times(maximum)}"
+        "expected between #{required} and #{count(maximum)}"
       end
     end
+    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+
+    def invoked_times
+      "invoked #{count(@invocations.size)}"
+    end
+
+    def actual_invocations
+      @invocations.map(&:full_description).join
+    end
 
     protected
 
     attr_reader :required, :maximum
 
-    def times(number)
+    def count(number)
       case number
-      when 0 then 'no times'
+      when 0 then 'never'
       when 1 then 'once'
       when 2 then 'twice'
       else "#{number} times"
       end
     end
 
+    def update(required, maximum)
+      @required = required
+      @maximum = maximum
+      self
+    end
+
     def infinite?(number)
       number.respond_to?(:infinite?) && number.infinite?
     end

data/lib/mocha/class_methods.rb

@@ -1,15 +1,9 @@
 require 'mocha/mockery'
-require 'mocha/class_method'
 require 'mocha/any_instance_method'
 
 module Mocha
   # Methods added to all classes to allow mocking and stubbing on real (i.e. non-mock) objects.
   module ClassMethods
-    # @private
-    def stubba_method
-      Mocha::ClassMethod
-    end
-
     # @private
     class AnyInstance
       def initialize(klass)
@@ -28,17 +22,15 @@ module Mocha
         Mocha::AnyInstanceMethod
       end
 
-      attr_reader :stubba_object
+      def stubba_class
+        @stubba_object
+      end
 
-      def method_exists?(method, include_public_methods = true)
-        if include_public_methods
-          return true if @stubba_object.public_instance_methods(true).include?(method)
-          return true if @stubba_object.allocate.respond_to?(method.to_sym)
-        end
-        return true if @stubba_object.protected_instance_methods(true).include?(method)
-        return true if @stubba_object.private_instance_methods(true).include?(method)
-        false
+      def respond_to?(method)
+        @stubba_object.allocate.respond_to?(method.to_sym)
       end
+
+      attr_reader :stubba_object
     end
 
     # @return [Mock] a mock object which will detect calls to any instance of this class.
@@ -56,5 +48,15 @@ module Mocha
       end
       @any_instance ||= AnyInstance.new(self)
     end
+
+    # @private
+    # rubocop:disable Metrics/CyclomaticComplexity
+    def __method_visibility__(method, include_public_methods = true)
+      (include_public_methods && public_method_defined?(method) && :public) ||
+        (protected_method_defined?(method) && :protected) ||
+        (private_method_defined?(method) && :private)
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+    alias_method :__method_exists__?, :__method_visibility__
   end
 end