mocha 1.10.1 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37552b852159a54683d4acb532daa97dd5b4db6ba031399e07056d438b034717
-  data.tar.gz: 86be70d9b97b96f30bda6122a056f79a6a93e9a5e7e657fda8df3ce60f5e55ac
+  metadata.gz: 3182f55b0e553eb0559fee7df5f5fd71f824e219480715de2f35e7bfacb5d9b2
+  data.tar.gz: 485677b5a3628ccee3730274697f27defb4fc087cc838d7c4ec8dac4e3cd589d
 SHA512:
-  metadata.gz: 7d0dded9eac7033c2fdefeeca1045bc6616c2c3a6f4376b83adc43fdae7af5b2771b8a395570e6417cc3ae431de01fca6253a477be29aac86d2607cc37395744
-  data.tar.gz: 44dd01735f61991c56031d85dd06c2f561ae518050daa17865714c25cdab70cfcc45a95b14220c8cb53656d2cc67c5b04660cbb7d47091bbd8b53a00e05c5093
+  metadata.gz: 1f782e0791e221f18081e35a298a039b96afd7a06caf4177a3d117e3803ee2165d9cd5dd6c19edde9334fda7dea973c105a5c3fe7070810dd0e7229901df056f
+  data.tar.gz: 8adf5cf18b21d7039c7c8f10b4c7a49ba4a215d9351cdd89a04d7a4371eda9863727b08e5bdbb240d92dd6cc93555306b13501370ecdadd4b6a74368213851c5

data/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: floehopper

data/.yardopts

@@ -1,3 +1,4 @@
+--output-dir docs
 --template-path yard-templates
 --no-private
 lib/mocha/api.rb

data/CONTRIBUTING.md

@@ -3,5 +3,5 @@
 * Make your changes in a branch.
 * Add/modify/remove tests as appropriate.
 * Open a pull request based on a branch on your fork.
-* Wait for your pull request build to pass on [Travis CI](https://travis-ci.org/freerange/mocha/pull_requests).
+* Wait for your pull request build to pass on [Travis CI](https://travis-ci.com/github/freerange/mocha/pull_requests).
 * Pull requests with failing tests will not be accepted.

data/README.md

@@ -1,5 +1,4 @@
-## Mocha [![Build Status](https://travis-ci.org/freerange/mocha.svg?branch=master)](https://travis-ci.org/freerange/mocha) [![Gem Version](https://badge.fury.io/rb/mocha.svg)](http://badge.fury.io/rb/mocha) [![SemVer](https://api.dependabot.com/badges/compatibility_score?dependency-name=mocha&package-manager=bundler&version-scheme=semver)](https://dependabot.com/compatibility-score.html?dependency-name=mocha&package-manager=bundler&version-scheme=semver)
-
+## Mocha [![Build Status](https://travis-ci.com/freerange/mocha.svg?branch=main)](https://travis-ci.com/github/freerange/mocha) [![Gem Version](https://badge.fury.io/rb/mocha.svg)](http://badge.fury.io/rb/mocha) [![SemVer](https://api.dependabot.com/badges/compatibility_score?dependency-name=mocha&package-manager=bundler&version-scheme=semver)](https://dependabot.com/compatibility-score.html?dependency-name=mocha&package-manager=bundler&version-scheme=semver)
 
 ### Description
 
@@ -47,35 +46,21 @@ If you're using Bundler, include Mocha in the `Gemfile` and then setup Mocha lat
 
 ```ruby
 # Gemfile
-gem "mocha"
+gem 'mocha'
 
 # Elsewhere after Bundler has loaded gems e.g. after `require 'bundler/setup'`
-require "test/unit"
-require "mocha/test_unit"
+require 'test/unit'
+require 'mocha/test_unit'
 ```
 
 ##### MiniTest
 
 ```ruby
 # Gemfile
-gem "mocha"
-
-# Elsewhere after Bundler has loaded gems e.g. after `require 'bundler/setup'`
-require "minitest/unit"
-require "mocha/minitest"
-```
-
-#### Rails
-
-If you're loading Mocha using Bundler within a Rails application, you should setup Mocha manually e.g. at the bottom of your `test_helper.rb`.
-
-##### MiniTest
-
-```ruby
-# Gemfile in Rails app
 gem 'mocha'
 
-# At bottom of test_helper.rb (or at least after `require 'rails/test_help'`)
+# Elsewhere after Bundler has loaded gems e.g. after `require 'bundler/setup'`
+require 'minitest/unit'
 require 'mocha/minitest'
 ```
 
@@ -95,13 +80,6 @@ end
 
 Note: There is no need to use a require statement to setup Mocha; RSpec does this itself.
 
-##### MiniTest
-
-```ruby
-# At bottom of test_helper.rb (or at least after `require 'rails/test_help'`)
-require 'mocha/minitest'
-```
-
 ##### Cucumber
 
 ```ruby
@@ -121,9 +99,29 @@ Around do |scenario, block|
 end
 ```
 
+#### Rails
+
+If you're loading Mocha using Bundler within a Rails application, you should setup Mocha manually e.g. at the bottom of your `test_helper.rb`.
+
+##### MiniTest
+
+Note that since Rails v4 (at least), `ActiveSupport::TestCase` has inherited from `Minitest::Test` or its earlier equivalents. Thus unless you are *explicitly* using Test::Unit, you are likely to be using MiniTest.
+
+```ruby
+# Gemfile in Rails app
+gem 'mocha'
+
+# At bottom of test_helper.rb (or at least after `require 'rails/test_help'`)
+require 'mocha/minitest'
+```
+
+##### Other Test Framework
+
+Follow the instructions for the relevant test framework in the [Bundler](#bundler) section, but ensure that the relevant Mocha file (`mocha/minitest`, `mocha/test_unit`, or `mocha/api`) is required **after** the test framework has been loaded, e.g. at the bottom of `test_helper.rb` or `spec_helper.rb`, or at least after `rails/test_help` has been required.
+
 #### Known Issues
 
-* In Mocha v1.10.0 an undocumented feature of `API#mock`, `API#stub` & `API#stub_everything` was changed. Previously when these methods were passed a single symbol, they returned a mock object that responded to the method identified by the symbol. Now Passing a single symbol is equivalent to passing a single string, i.e. it now defines the "name" of the mock object.
+* In Mocha v1.10.0 an undocumented feature of `API#mock`, `API#stub` & `API#stub_everything` was changed. Previously when these methods were passed a single symbol, they returned a mock object that responded to the method identified by the symbol. Now Passing a single symbol is equivalent to passing a single string, i.e. it now defines the 'name' of the mock object.
 * In Mocha v1.2.0 there is a scenario where stubbing a class method originally defined in a module hangs the Ruby interpreter due to [a bug in Ruby v2.3.1](https://bugs.ruby-lang.org/issues/12832). See #272. This was fixed in Mocha v1.2.1.
 * Since v1.1.0 Mocha has used prepended modules internally for stubbing methods. There is [an obscure Ruby bug](https://bugs.ruby-lang.org/issues/12876) in many (but not all) versions of Ruby between v2.0 & v2.3 which under certain circumstances may cause your Ruby interpreter to hang. See the Ruby bug report for more details. The bug has been fixed in Ruby v2.3.3 & v2.4.0.
 * Stubbing an aliased class method, where the original method is defined in a module that's used to `extend` the class doesn't work in Ruby 1.8.x. See stub_method_defined_on_module_and_aliased_test.rb for an example of this behaviour.
@@ -325,7 +323,7 @@ See this [list of contributors](https://github.com/freerange/mocha/graphs/contri
 * Update the RELEASE.md file with a summary of changes
 * Bump the version in `lib/mocha/version.rb`
 * Commit & push to GitHub
-* Check Travis CI build is passing - https://travis-ci.org/freerange/mocha
+* Check Travis CI build is passing - https://travis-ci.com/github/freerange/mocha
 
 * Sign in to Google Analytics - https://analytics.google.com/analytics/web/
 * Find the web property ID for floehopper (625523) > Mocha Documentation (UA-625523-7)

data/RELEASE.md

@@ -1,5 +1,74 @@
 # Release Notes
 
+## 1.12.0
+
+### External changes
+
+* Various improvements to README inspired by #207 and #390 - thanks to @nitishr for his work on #390 (fed0eee6)
+* Improve documentation related to `StateMachine` classes - thanks to @nitishr (#425 & #427)
+* Fix regression in cardinality introduced in v1.10.0 (59454a8) and reported in #473 - thanks to @srvance for reporting and @nitishr for fixing (#474)
+* Fix documentation for `Mocha::Expectation#when` - thanks to @olleolleolle (b4f59daa & #477)
+* Remove `Mocha::Mock#respond_to?` from documentation - thanks to @nitishr (#480)
+* Improvements to documentation for `Expectation#yields` & `#multiple_yields` - thanks to @andyw8 for reporting in #495 (1b6571c)
+* Remove documentation & tests from gem to reduce its size by over 50% - thanks to @gabetax (#500)
+* Update documentation to point to travis-ci.com instead of travis-ci.org
+
+### Internal changes
+
+* Refactor `StateMachine`-related classes - thanks to @nitishr (#425 & #427)
+* Remove redundant test - thanks to @nitishr (8e4f1a7c)
+* Add Ruby 2.7 to Travis CI matrix - thanks to @bastelfreak (fc5ea2f2)
+* Simplify `Mockery` - thanks to @nitishr (#449)
+* Update Travis CI badge to point to main vs master branch (bd8028f8)
+* Generate docs using newer version of yard (v0.9.25) (c619afac)
+* Manually upgrade jquery in docs from v1.7.1 -> v1.9.0 to fix CVE-2017-16011 (211098a5, dd5eeedb & 1b76e4d5; also see #492)
+* Remove reference to non-existent jquery source map to fix error in Chrome developer tools (20156555)
+* Temporarily ignore Ruby v1.8.7 build failures (e5b9feef)
+
+## 1.11.2
+
+### External changes
+
+* Fix regression introduced in v1.10.0 that meant `Object#inspect` was called unnecessarily (368abd98)
+* Warn when mock object receives invocations in another test - thanks to @nitishr (#442)
+* Avoid rubocop comments appearing in YARD-generated docs (d8019eed)
+
+### Internal changes
+
+* Replace `StubbedMethod#original_method` & `#original_visibility` attribute reader methods with instance variables - thanks to @nitishr (d917f332)
+* Set up `MochaExampleTest` & `StubbaExampleTest` as acceptance tests - thanks to @nitishr (4881cc58)
+* Delete unused `PrettyParameters` class - thanks to @nitishr (314ea922)
+
+## 1.11.1
+
+### External changes
+
+* The `reinstate_undocumented_behaviour_from_v1_9` configuration option is now enabled by default to give people a chance to see and fix the relevant deprecation warnings before the behaviour is removed in a future release (b91b1c9e)
+
+## 1.11.0
+
+### External changes
+
+* Add `Expectation#with_block_given` & `Expectation#with_no_block_given` (#441).
+  * Allows non-deprecated solution for #382. Thanks to @yemartin for reporting and to @techbelly & @nitishr for feedback.
+* Fix issue with non-Array arguments passed to `Expectation#multiple_yields` (#444).
+  * The undocumented behaviour is now properly supported and documented.
+
+### Internal changes
+
+* Move static YARD options from Rake task to `.yardopts` file - thanks to @nitishr (#429)
+* Simplify implementation of yielding functionality - thanks to @nitishr (#439)
+* Add missing require statement to `acceptance_test_helper.rb` (1070fc02)
+* Add some baseline acceptance tests for yielding behaviour (c2cac911)
+* Display a sponsor button on GitHub repo page (9fc5911b)
+* Use new Deprecation.warning behaviour in `Invocation#call` (932d1166)
+
+## 1.10.2
+
+* Optionally reinstate undocumented behaviour from v1.9. This introduces a new configuration option (`reinstate_undocumented_behaviour_from_v1_9`) to reinstate a couple of bits of undocumented behaviour from v1.9 which were changed in v1.10 without any prior deprecation warning (#438):
+  * The behaviour of `API#mock`, `API#stub` and `API#stub_everything` when called with a symbol as the first argument.
+  * The behaviour of `Expectation#yields` and `Expectation#multiple_yields` when the stubbed method is called without a block.
+
 ## 1.10.1
 
 * Ensure ObjectMethods & ClassMethods included when API extended (43778756)

data/Rakefile

@@ -138,18 +138,20 @@ if ENV['MOCHA_GENERATE_DOCS']
 
   desc 'Generate documentation'
   YARD::Rake::YardocTask.new('yardoc' => 'docs_environment') do |task|
-    task.options = [
-      '--title', "Mocha #{Mocha::VERSION}",
-      '--output-dir', 'docs'
-    ]
+    task.options = ['--title', "Mocha #{Mocha::VERSION}"]
   end
 
   task 'checkout_docs_cname' do
     `git checkout docs/CNAME`
   end
 
+  task 'checkout_docs_js' do
+    `git checkout docs/js/app.js`
+    `git checkout docs/js/jquery.js`
+  end
+
   desc 'Generate documentation'
-  task 'generate_docs' => %w[clobber_yardoc yardoc checkout_docs_cname]
+  task 'generate_docs' => %w[clobber_yardoc yardoc checkout_docs_cname checkout_docs_js]
 end
 
 task 'release' => 'default'

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,8 +65,31 @@ module Mocha
     #     assert motor.stop
     #     # an error will be raised unless both Motor#start and Motor#stop have been called
     #   end
-    def mock(*arguments)
-      create_mock(arguments) { |mock, expectations| mock.expects(expectations) }
+    #
+    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) : Mockery.instance.unnamed_mock
+      mock.expects(expectations)
+      mock
     end
 
     # Builds a new mock object
@@ -75,7 +98,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 +111,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 +145,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 +159,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 +237,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/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,31 +2,28 @@ 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 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
-      end
+    def at_most(count)
+      update(0, count)
     end
 
-    def initialize(required, maximum)
-      @required = required
-      @maximum = maximum
-      @invocations = []
+    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 <<(invocation)
@@ -62,21 +59,21 @@ module Mocha
       if allowed_any_number_of_times?
         'allowed any number of times'
       elsif required.zero? && maximum.zero?
-        "expected #{times(maximum)}"
+        "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 #{times(@invocations.size)}"
+      "invoked #{count(@invocations.size)}"
     end
 
     def actual_invocations
@@ -87,7 +84,7 @@ module Mocha
 
     attr_reader :required, :maximum
 
-    def times(number)
+    def count(number)
       case number
       when 0 then 'never'
       when 1 then 'once'
@@ -96,6 +93,12 @@ module Mocha
       end
     end
 
+    def update(required, maximum)
+      @required = required
+      @maximum = maximum
+      self
+    end
+
     def infinite?(number)
       number.respond_to?(:infinite?) && number.infinite?
     end