mocha 1.10.1 → 1.10.2

data/docs/top-level-namespace.html

@@ -6,7 +6,7 @@
 <title>
   Top Level Namespace
   
-    &mdash; Mocha 1.10.1
+    &mdash; Mocha 1.10.2
   
 </title>
 
@@ -108,7 +108,7 @@
 </div>
 
       <div id="footer">
-  Generated on Wed Dec  4 09:20:46 2019 by
+  Generated on Thu Dec 12 10:57:46 2019 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.20 (ruby-2.6.5).
 </div>

data/lib/mocha/api.rb

@@ -51,7 +51,7 @@ module Mocha
     #
     # @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 stubbed the method identified by +name+. This was undocumented behaviour and it no longer exists.
+    #   @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 = {})
@@ -65,9 +65,33 @@ module Mocha
     #     assert motor.stop
     #     # an error will be raised unless both Motor#start and Motor#stop have been called
     #   end
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
     def mock(*arguments)
-      create_mock(arguments) { |mock, expectations| mock.expects(expectations) }
+      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) : Mockery.instance.unnamed_mock
+      mock.expects(expectations)
+      mock
     end
+    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
 
     # Builds a new mock object
     #
@@ -75,7 +99,7 @@ module Mocha
     #
     # @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 no longer exists.
+    #   @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 = {})
@@ -88,9 +112,33 @@ module Mocha
     #     assert motor.stop
     #     # an error will not be raised even if either Motor#start or Motor#stop has not been called
     #   end
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
     def stub(*arguments)
-      create_mock(arguments) { |stub, expectations| stub.stubs(expectations) }
+      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) : 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.
     #
@@ -98,7 +146,7 @@ module Mocha
     #
     # @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 everything. This was undocumented behaviour and it no longer exists.
+    #   @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 = {})
@@ -112,12 +160,34 @@ module Mocha
     #     assert_nil motor.irrelevant_method_2 # => no error raised
     #     assert motor.stop
     #   end
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
     def stub_everything(*arguments)
-      create_mock(arguments) do |stub, expectations|
-        stub.stub_everything
-        stub.stubs(expectations)
+      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) : 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.
     #
@@ -168,15 +238,5 @@ module Mocha
     def states(name)
       Mockery.instance.new_state_machine(name)
     end
-
-    private
-
-    def create_mock(arguments)
-      name = arguments.shift.to_s if arguments.first.is_a?(String) || arguments.first.is_a?(Symbol)
-      expectations = arguments.shift || {}
-      mock = name ? Mockery.instance.named_mock(name) : Mockery.instance.unnamed_mock
-      yield mock, expectations
-      mock
-    end
   end
 end

data/lib/mocha/configuration.rb

@@ -42,7 +42,8 @@ module Mocha
       :stubbing_non_existent_method => :allow,
       :stubbing_non_public_method => :allow,
       :stubbing_method_on_nil => :prevent,
-      :display_matching_invocations_on_failure => false
+      :display_matching_invocations_on_failure => false,
+      :reinstate_undocumented_behaviour_from_v1_9 => false
     }.freeze
 
     attr_reader :options
@@ -247,6 +248,61 @@ module Mocha
       @options[:display_matching_invocations_on_failure]
     end
 
+    # Reinstate undocumented behaviour from v1.9
+    #
+    # Previously when {API#mock}, {API#stub}, or {API#stub_everything} were called with the first argument being a symbol, they built an *unnamed* mock object *and* expected or stubbed the method identified by the symbol argument; subsequent arguments were ignored.
+    # Now these methods build a *named* mock with the name specified by the symbol argument; *no* methods are expected or stubbed and subsequent arguments *are* taken into account.
+    #
+    # Previously if {Expectation#yields} or {Expectation#multiple_yields} was called on an expectation, but no block was given when the method was invoked, the instruction to yield was ignored.
+    # Now a +LocalJumpError+ is raised.
+    #
+    # Enabling this configuration option reinstates the previous behaviour, but displays a deprecation warning.
+    #
+    # @param [Boolean] value +true+ to reinstate undocumented behaviour; disabled by default.
+    #
+    # @example Reinstate undocumented behaviour for {API#mock}
+    #   Mocha.configure do |c|
+    #     c.reinstate_undocumented_behaviour_from_v1_9 = true
+    #   end
+    #
+    #   foo = mock(:bar)
+    #   foo.inspect # => #<Mock>
+    #
+    #   not all expectations were satisfied
+    #   unsatisfied expectations:
+    #   - expected exactly once, invoked never: #<Mock>.foo
+    #
+    # @example Reinstate undocumented behaviour for {API#stub}
+    #   Mocha.configure do |c|
+    #     c.reinstate_undocumented_behaviour_from_v1_9 = true
+    #   end
+    #
+    #   foo = stub(:bar)
+    #   foo.inspect # => #<Mock>
+    #   foo.bar # => nil
+    #
+    # @example Reinstate undocumented behaviour for {Expectation#yields}
+    #   foo = mock('foo')
+    #   foo.stubs(:my_method).yields(1, 2)
+    #   foo.my_method # => raises LocalJumpError when no block is supplied
+    #
+    #   Mocha.configure do |c|
+    #     c.reinstate_undocumented_behaviour_from_v1_9 = true
+    #   end
+    #
+    #   foo = mock('foo')
+    #   foo.stubs(:my_method).yields(1, 2)
+    #   foo.my_method # => does *not* raise LocalJumpError when no block is supplied
+    #
+    def reinstate_undocumented_behaviour_from_v1_9=(value)
+      @options[:reinstate_undocumented_behaviour_from_v1_9] = value
+    end
+
+    # @private
+    def reinstate_undocumented_behaviour_from_v1_9?
+      @options[:reinstate_undocumented_behaviour_from_v1_9]
+    end
+
     class << self
       # Allow the specified +action+.
       #

data/lib/mocha/deprecation.rb

@@ -5,7 +5,8 @@ module Mocha
     class << self
       attr_accessor :mode, :messages
 
-      def warning(message)
+      def warning(*messages)
+        message = messages.join
         @messages << message
         return if mode == :disabled
         filter = BacktraceFilter.new

data/lib/mocha/expectation.rb

@@ -568,7 +568,7 @@ module Mocha
     def invoke(invocation)
       perform_side_effects
       @cardinality << invocation
-      invocation.call(@yield_parameters, @return_values) { |*yield_args| yield(*yield_args) }
+      invocation.call(@yield_parameters, @return_values)
     end
 
     # @private

data/lib/mocha/invocation.rb

@@ -3,15 +3,18 @@ require 'mocha/raised_exception'
 require 'mocha/return_values'
 require 'mocha/thrown_object'
 require 'mocha/yield_parameters'
+require 'mocha/configuration'
+require 'mocha/deprecation'
 
 module Mocha
   class Invocation
     attr_reader :method_name
 
-    def initialize(mock, method_name, *arguments)
+    def initialize(mock, method_name, *arguments, &block)
       @mock = mock
       @method_name = method_name
       @arguments = arguments
+      @block = block
       @yields = []
       @result = nil
     end
@@ -19,7 +22,16 @@ module Mocha
     def call(yield_parameters = YieldParameters.new, return_values = ReturnValues.new)
       yield_parameters.next_invocation.each do |yield_args|
         @yields << ParametersMatcher.new(yield_args)
-        yield(*yield_args)
+        if @block
+          @block.call(*yield_args)
+        else
+          raise LocalJumpError unless Mocha.configuration.reinstate_undocumented_behaviour_from_v1_9?
+          yield_args_description = ParametersMatcher.new(yield_args).mocha_inspect
+          Deprecation.warning([
+            "Stubbed method was instructed to yield #{yield_args_description}, but no block was given by invocation: #{call_description}.",
+            'This will raise a LocalJumpError in the future.'
+          ].join(' '))
+        end
       end
       return_values.next(self)
     end

data/lib/mocha/mock.rb

@@ -310,13 +310,13 @@ module Mocha
       if @responder && !@responder.respond_to?(symbol)
         raise NoMethodError, "undefined method `#{symbol}' for #{mocha_inspect} which responds like #{@responder.mocha_inspect}"
       end
-      invocation = Invocation.new(self, symbol, *arguments)
+      invocation = Invocation.new(self, symbol, *arguments, &block)
       if (matching_expectation_allowing_invocation = all_expectations.match_allowing_invocation(invocation))
-        matching_expectation_allowing_invocation.invoke(invocation, &block)
+        matching_expectation_allowing_invocation.invoke(invocation)
       elsif (matching_expectation = all_expectations.match(invocation)) || (!matching_expectation && !@everything_stubbed)
         if @unexpected_invocation.nil?
           @unexpected_invocation = invocation
-          matching_expectation.invoke(invocation, &block) if matching_expectation
+          matching_expectation.invoke(invocation) if matching_expectation
           message = "#{@unexpected_invocation.call_description}\n#{@mockery.mocha_inspect}"
         else
           message = @unexpected_invocation.short_call_description

data/lib/mocha/version.rb

@@ -1,3 +1,3 @@
 module Mocha
-  VERSION = '1.10.1'.freeze
+  VERSION = '1.10.2'.freeze
 end

data/test/acceptance/mock_built_with_first_argument_type_being_string_test.rb

@@ -0,0 +1,99 @@
+require File.expand_path('../acceptance_test_helper', __FILE__)
+require 'deprecation_disabler'
+
+class MockBuiltWithFirstArgumentTypeBeingStringTest < Mocha::TestCase
+  include AcceptanceTest
+
+  def setup
+    setup_acceptance_test
+    Mocha.configure { |c| c.reinstate_undocumented_behaviour_from_v1_9 = true }
+  end
+
+  def teardown
+    teardown_acceptance_test
+  end
+
+  def test_mock_built_with_single_symbol_argument_with_satisfied_expectation
+    test_result = run_as_test do
+      DeprecationDisabler.disable_deprecations do
+        m = mock(:my_method)
+        assert_nil m.my_method
+      end
+      expected_warning = 'Explicitly include `my_method` in Hash of expected methods vs return values, e.g. `mock(:my_method => nil)`.'
+      assert_equal expected_warning, Mocha::Deprecation.messages.last
+    end
+    assert_passed(test_result)
+  end
+
+  def test_mock_built_with_single_symbol_argument_with_unsatisfied_expectation
+    test_result = run_as_test do
+      DeprecationDisabler.disable_deprecations do
+        mock(:my_method)
+      end
+    end
+    assert_failed(test_result)
+    assert(test_result.failure_message_lines.any? do |line|
+      line[/expected exactly once, invoked never\: #<Mock\:0x[0-9a-f]+>\.my_method\(any_parameters\)/]
+    end)
+  end
+
+  def test_stub_built_with_single_symbol_argument
+    test_result = run_as_test do
+      DeprecationDisabler.disable_deprecations do
+        s = stub(:my_method)
+        assert_nil s.my_method
+      end
+      expected_warning = 'Explicitly include `my_method` in Hash of stubbed methods vs return values, e.g. `stub(:my_method => nil)`.'
+      assert_equal expected_warning, Mocha::Deprecation.messages.last
+    end
+    assert_passed(test_result)
+  end
+
+  def test_mock_built_with_first_argument_a_symbol_and_second_argument_a_hash
+    test_result = run_as_test do
+      DeprecationDisabler.disable_deprecations do
+        s = mock(:my_method, :another_method => 123)
+        assert_nil s.my_method
+      end
+      expected_warning = 'In this case the 2nd argument for `mock(:#my_method, ...)` is ignored, but in the future a Hash of expected methods vs return values will be respected.'
+      assert Mocha::Deprecation.messages.last(2).include?(expected_warning)
+    end
+    assert_passed(test_result)
+  end
+
+  def test_stub_built_with_first_argument_a_symbol_and_second_argument_a_hash
+    test_result = run_as_test do
+      DeprecationDisabler.disable_deprecations do
+        s = stub(:my_method, :another_method => 123)
+        assert_nil s.my_method
+      end
+      expected_warning = 'In this case the 2nd argument for `stub(:#my_method, ...)` is ignored, but in the future a Hash of stubbed methods vs return values will be respected.'
+      assert Mocha::Deprecation.messages.last(2).include?(expected_warning)
+    end
+    assert_passed(test_result)
+  end
+
+  def test_stub_everything_built_with_single_symbol_argument
+    test_result = run_as_test do
+      DeprecationDisabler.disable_deprecations do
+        s = stub_everything(:my_method)
+        assert_nil s.my_method
+      end
+      expected_warning = 'Explicitly include `my_method` in Hash of stubbed methods vs return values, e.g. `stub_everything(:my_method => nil)`.'
+      assert_equal expected_warning, Mocha::Deprecation.messages.last
+    end
+    assert_passed(test_result)
+  end
+
+  def test_stub_everything_built_with_first_argument_a_symbol_and_second_argument_a_hash
+    test_result = run_as_test do
+      DeprecationDisabler.disable_deprecations do
+        s = stub_everything(:my_method, :another_method => 123)
+        assert_nil s.my_method
+      end
+      expected_warning = 'In this case the 2nd argument for `stub_everything(:#my_method, ...)` is ignored, but in the future a Hash of stubbed methods vs return values will be respected.' # rubocop:disable Metrics/LineLength
+      assert Mocha::Deprecation.messages.last(2).include?(expected_warning)
+    end
+    assert_passed(test_result)
+  end
+end

data/test/unit/expectation_test.rb

@@ -2,8 +2,11 @@ require File.expand_path('../../test_helper', __FILE__)
 require 'mocha/expectation'
 require 'mocha/invocation'
 require 'mocha/sequence'
+require 'mocha/configuration'
+require 'mocha/deprecation'
 require 'execution_point'
 require 'simple_counter'
+require 'deprecation_disabler'
 
 class ExpectationTest < Mocha::TestCase
   include Mocha
@@ -13,7 +16,7 @@ class ExpectationTest < Mocha::TestCase
   end
 
   def invoke(expectation, &block)
-    expectation.invoke(Invocation.new(:irrelevant, :expected_method), &block)
+    expectation.invoke(Invocation.new(:irrelevant, :expected_method, &block))
   end
 
   def test_should_match_calls_to_same_method_with_any_parameters
@@ -116,6 +119,18 @@ class ExpectationTest < Mocha::TestCase
     assert_raises(LocalJumpError) { invoke(new_expectation.yields(:foo)) }
   end
 
+  def test_yield_should_display_warning_when_caller_does_not_provide_block_and_behaviour_from_v1_9_retained
+    Mocha::Configuration.override(:reinstate_undocumented_behaviour_from_v1_9 => true) do
+      DeprecationDisabler.disable_deprecations do
+        invoke(new_expectation.yields(:foo, 1, [2, 3]))
+      end
+    end
+    assert message = Deprecation.messages.last
+    assert message.include?('Stubbed method was instructed to yield (:foo, 1, [2, 3])')
+    assert message.include?('but no block was given by invocation: :irrelevant.expected_method()')
+    assert message.include?('This will raise a LocalJumpError in the future.')
+  end
+
   def test_should_yield_with_specified_parameters
     yielded_parameters = nil
     invoke(new_expectation.yields(1, 2, 3)) { |*parameters| yielded_parameters = parameters }