mocha 1.2.1 → 1.16.1

data/lib/mocha/api.rb

@@ -1,36 +1,63 @@
+require 'mocha/ruby_version'
 require 'mocha/parameter_matchers'
 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
 
     # @private
-    def self.included(mod)
+    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 against the mock object instance, giving an alternative way to setup expectations.
     # @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,34 +66,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.
-    #   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 against the mock object instance, giving an alternative way to setup stubbed methods.
     # @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
@@ -75,35 +112,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.
-    #   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 against the mock object instance, giving an alternative way to setup stubbed methods.
     # @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
@@ -112,14 +160,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.
     #
@@ -132,11 +200,22 @@ module Mocha
     # @example Ensure methods on egg are invoked in correct order.
     #   breakfast = sequence('breakfast')
     #
-    #   egg = mock('egg') do
-    #     expects(:crack).in_sequence(breakfast)
-    #     expects(:fry).in_sequence(breakfast)
-    #     expects(:eat).in_sequence(breakfast)
-    #   end
+    #   egg = mock('egg')
+    #   egg.expects(:crack).in_sequence(breakfast)
+    #   egg.expects(:fry).in_sequence(breakfast)
+    #   egg.expects(:eat).in_sequence(breakfast)
+    #
+    # @example Ensure methods across multiple objects are invoked in correct order.
+    #   sequence = sequence(:task_order)
+    #
+    #   task_one = mock("task_one")
+    #   task_two = mock("task_two")
+    #
+    #   task_one.expects(:execute).in_sequence(sequence)
+    #   task_two.expects(:execute).in_sequence(sequence)
+    #
+    #   task_one.execute
+    #   task_two.execute
     def sequence(name)
       Sequence.new(name)
     end
@@ -159,18 +238,15 @@ module Mocha
     # @example Constrain expected invocations to occur in particular states.
     #   power = states('power').starts_as('off')
     #
-    #   radio = mock('radio') do
-    #     expects(:switch_on).then(power.is('on'))
-    #     expects(:select_channel).with('BBC Radio 4').when(power.is('on'))
-    #     expects(:adjust_volume).with(+5).when(power.is('on'))
-    #     expects(:select_channel).with('BBC World Service').when(power.is('on'))
-    #     expects(:adjust_volume).with(-5).when(power.is('on'))
-    #     expects(:switch_off).then(power.is('off'))
-    #   end
+    #   radio = mock('radio')
+    #   radio.expects(:switch_on).then(power.is('on'))
+    #   radio.expects(:select_channel).with('BBC Radio 4').when(power.is('on'))
+    #   radio.expects(:adjust_volume).with(+5).when(power.is('on'))
+    #   radio.expects(:select_channel).with('BBC World Service').when(power.is('on'))
+    #   radio.expects(:adjust_volume).with(-5).when(power.is('on'))
+    #   radio.expects(:switch_off).then(power.is('off'))
     def states(name)
       Mockery.instance.new_state_machine(name)
     end
-
   end
-
 end

data/lib/mocha/argument_iterator.rb

@@ -1,21 +1,17 @@
 module Mocha
-
   class ArgumentIterator
-
     def initialize(argument)
       @argument = argument
     end
 
-    def each(&block)
-      if @argument.is_a?(Hash) then
+    def each
+      if @argument.is_a?(Hash)
         @argument.each do |method_name, return_value|
-          block.call(method_name, return_value)
+          yield method_name, return_value
         end
       else
-        block.call(@argument)
+        yield @argument
       end
     end
-
   end
-
 end

data/lib/mocha/backtrace_filter.rb

@@ -1,8 +1,6 @@
 module Mocha
-
   class BacktraceFilter
-
-    LIB_DIRECTORY = File.expand_path(File.join(File.dirname(__FILE__), "..")) + File::SEPARATOR
+    LIB_DIRECTORY = File.expand_path(File.join(File.dirname(__FILE__), '..')) + File::SEPARATOR
 
     def initialize(lib_directory = LIB_DIRECTORY)
       @path_pattern = Regexp.new(lib_directory)
@@ -11,7 +9,5 @@ module Mocha
     def filtered(backtrace)
       backtrace.reject { |location| @path_pattern.match(File.expand_path(location)) }
     end
-
   end
-
 end

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

@@ -1,95 +1,106 @@
 module Mocha
-
   class Cardinality
-
     INFINITY = 1 / 0.0
 
-    class << self
+    def initialize(required = 0, maximum = INFINITY)
+      update(required, maximum)
+      @invocations = []
+    end
 
-      def exactly(count)
-        new(count, count)
-      end
+    def exactly(count)
+      update(count, count)
+    end
 
-      def at_least(count)
-        new(count, INFINITY)
-      end
+    def at_least(count)
+      update(count, INFINITY)
+    end
 
-      def at_most(count)
-        new(0, count)
-      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, @maximum = required, 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 == 0 && infinite?(maximum)
+      required.zero? && infinite?(maximum)
     end
 
-    def used?(invocation_count)
-      (invocation_count > 0) || (maximum == 0)
+    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"
+        'allowed any number of times'
+      elsif required.zero? && maximum.zero?
+        "expected #{count(maximum)}"
+      elsif required == maximum
+        "expected exactly #{count(required)}"
+      elsif infinite?(maximum)
+        "expected at least #{count(required)}"
+      elsif required.zero?
+        "expected at most #{count(maximum)}"
       else
-        if required == 0 && maximum == 0
-          "expected never"
-        elsif required == maximum
-          "expected exactly #{times(required)}"
-        elsif infinite?(maximum)
-          "expected at least #{times(required)}"
-        elsif required == 0
-          "expected at most #{times(maximum)}"
-        else
-          "expected between #{required} and #{times(maximum)}"
-        end
+        "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 1 then "once"
-        when 2 then "twice"
-        else "#{number} 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
-
   end
-
 end

data/lib/mocha/central.rb

@@ -1,6 +1,19 @@
 module Mocha
-
   class Central
+    class Null < self
+      def initialize(&block)
+        super
+        @raise_not_initialized_error = block
+      end
+
+      def stub(*)
+        @raise_not_initialized_error.call
+      end
+
+      def unstub(*)
+        @raise_not_initialized_error.call
+      end
+    end
 
     attr_accessor :stubba_methods
 
@@ -9,25 +22,21 @@ module Mocha
     end
 
     def stub(method)
-      unless stubba_methods.detect { |m| m.matches?(method) }
-        method.stub
-        stubba_methods.push(method)
-      end
+      return if stubba_methods.detect { |m| m.matches?(method) }
+      method.stub
+      stubba_methods.push(method)
     end
 
     def unstub(method)
-      if existing = stubba_methods.detect { |m| m.matches?(method) }
-        existing.unstub
-        stubba_methods.delete(existing)
-      end
+      return unless (existing = stubba_methods.detect { |m| m.matches?(method) })
+      existing.unstub
+      stubba_methods.delete(existing)
     end
 
     def unstub_all
-      while stubba_methods.any? do
+      while stubba_methods.any?
         unstub(stubba_methods.first)
       end
     end
-
   end
-
 end

data/lib/mocha/change_state_side_effect.rb

@@ -1,7 +1,5 @@
 module Mocha
-
   class ChangeStateSideEffect
-
     def initialize(state)
       @state = state
     end
@@ -13,7 +11,5 @@ module Mocha
     def mocha_inspect
       "then #{@state.mocha_inspect}"
     end
-
   end
-
 end

data/lib/mocha/class_methods.rb

@@ -1,46 +1,36 @@
 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)
         @stubba_object = klass
       end
 
-      def mocha
-        @mocha ||= Mocha::Mockery.instance.mock_impersonating_any_instance_of(@stubba_object)
+      def mocha(instantiate = true)
+        if instantiate
+          @mocha ||= Mocha::Mockery.instance.mock_impersonating_any_instance_of(@stubba_object)
+        else
+          defined?(@mocha) ? @mocha : nil
+        end
       end
 
       def stubba_method
         Mocha::AnyInstanceMethod
       end
 
-      def 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(include_superclass_methods = true).include?(method)
-          return true if @stubba_object.allocate.respond_to?(method.to_sym)
-        end
-        return true if @stubba_object.protected_instance_methods(include_superclass_methods = true).include?(method)
-        return true if @stubba_object.private_instance_methods(include_superclass_methods = true).include?(method)
-        return false
+      def respond_to?(symbol, include_all = false)
+        @stubba_object.allocate.respond_to?(symbol.to_sym, include_all)
       end
 
+      attr_reader :stubba_object
     end
 
     # @return [Mock] a mock object which will detect calls to any instance of this class.
@@ -59,6 +49,14 @@ module Mocha
       @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