mocha 1.11.2 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 398d43b17f224be63c21bcd24cbe4d1bff6b90267e1a870eb4f2a3432515da88
-  data.tar.gz: bd7c4a5ce95a20b5b403750982d63356e1553af54f45d538cc3e3c514f7fb079
+  metadata.gz: 3182f55b0e553eb0559fee7df5f5fd71f824e219480715de2f35e7bfacb5d9b2
+  data.tar.gz: 485677b5a3628ccee3730274697f27defb4fc087cc838d7c4ec8dac4e3cd589d
 SHA512:
-  metadata.gz: 0b8a00e3b21f5761fede57f919785ac653e714d28151325980d6ae5bd5d0a7ec5ecdcbaf96d6e36c6659347852e414b3a1c10fb57e0c72b981e70348308174f1
-  data.tar.gz: f85f050cbbb7bfa224420e8ad2f67f6b683576a1d8ef1d79f55acecda495febca0f6b0aae79721c0159028f752c2e19268f06c5dc8e27f40dd5449e8ea5b96ae
+  metadata.gz: 1f782e0791e221f18081e35a298a039b96afd7a06caf4177a3d117e3803ee2165d9cd5dd6c19edde9334fda7dea973c105a5c3fe7070810dd0e7229901df056f
+  data.tar.gz: 8adf5cf18b21d7039c7c8f10b4c7a49ba4a215d9351cdd89a04d7a4371eda9863727b08e5bdbb240d92dd6cc93555306b13501370ecdadd4b6a74368213851c5

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,30 @@
 # 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

data/Rakefile

@@ -145,8 +145,13 @@ if ENV['MOCHA_GENERATE_DOCS']
     `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/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

data/lib/mocha/expectation.rb

@@ -42,7 +42,7 @@ module Mocha
     #   object.expected_method
     #   # => verify fails
     def times(range)
-      @cardinality = Cardinality.times(range)
+      @cardinality.times(range)
       self
     end
 
@@ -68,7 +68,7 @@ module Mocha
     #   object.expected_method
     #   # => verify fails
     def twice
-      @cardinality = Cardinality.exactly(2)
+      @cardinality.exactly(2)
       self
     end
 
@@ -93,7 +93,7 @@ module Mocha
     #   object.expects(:expected_method).once
     #   # => verify fails
     def once
-      @cardinality = Cardinality.exactly(1)
+      @cardinality.exactly(1)
       self
     end
 
@@ -110,7 +110,7 @@ module Mocha
     #   object.expects(:expected_method).never
     #   # => verify succeeds
     def never
-      @cardinality = Cardinality.exactly(0)
+      @cardinality.exactly(0)
       self
     end
 
@@ -130,7 +130,7 @@ module Mocha
     #   object.expected_method
     #   # => verify fails
     def at_least(minimum_number_of_times)
-      @cardinality = Cardinality.at_least(minimum_number_of_times)
+      @cardinality.at_least(minimum_number_of_times)
       self
     end
 
@@ -149,7 +149,6 @@ module Mocha
     #   # => verify fails
     def at_least_once
       at_least(1)
-      self
     end
 
     # Modifies expectation so that the expected method must be called at most a +maximum_number_of_times+.
@@ -167,7 +166,7 @@ module Mocha
     #   object.expects(:expected_method).at_most(2)
     #   3.times { object.expected_method } # => unexpected invocation
     def at_most(maximum_number_of_times)
-      @cardinality = Cardinality.at_most(maximum_number_of_times)
+      @cardinality.at_most(maximum_number_of_times)
       self
     end
 
@@ -186,7 +185,6 @@ module Mocha
     #   2.times { object.expected_method } # => unexpected invocation
     def at_most_once
       at_most(1)
-      self
     end
 
     # Modifies expectation so that the expected method must be called with +expected_parameters+.
@@ -263,7 +261,11 @@ module Mocha
       self
     end
 
-    # Modifies expectation so that when the expected method is called, it yields with the specified +parameters+ (even if no block is provided, in which case yielding will result in a +LocalJumpError+).
+    # Modifies expectation so that when the expected method is called, it yields to the block with the specified +parameters+.
+    #
+    # If no +parameters+ are specified, it yields to the block without any parameters.
+    #
+    # If no block is provided, the method will still attempt to yield resulting in a +LocalJumpError+. Note that this is what would happen if a "real" (non-mock) method implementation tried to yield to a non-existent block.
     #
     # May be called multiple times on the same expectation for consecutive invocations.
     #
@@ -273,11 +275,10 @@ module Mocha
     #
     # @example Yield when expected method is invoked.
     #   benchmark = mock()
-    #   benchmark.expects(:measure).yields.then.returns('0.350000   0.400000   0.750000 (  0.835234)')
+    #   benchmark.expects(:measure).yields
     #   yielded = false
-    #   returned_value = benchmark.measure { yielded = true }
+    #   benchmark.measure { yielded = true }
     #   yielded # => true
-    #   returned_value # => '0.350000   0.400000   0.750000 (  0.835234)'
     #
     # @example Yield parameters when expected method is invoked.
     #   fibonacci = mock()
@@ -298,7 +299,9 @@ module Mocha
       multiple_yields(parameters)
     end
 
-    # Modifies expectation so that when the expected method is called, it yields multiple times per invocation with the specified +parameter_groups+ (even if no block is provided, in which case yielding will result in a +LocalJumpError+).
+    # Modifies expectation so that when the expected method is called, it yields multiple times per invocation with the specified +parameter_groups+.
+    #
+    # If no block is provided, the method will still attempt to yield resulting in a +LocalJumpError+. Note that this is what would happen if a "real" (non-mock) method implementation tried to yield to a non-existent block.
     #
     # @param [*Array<Array>] parameter_groups each element of +parameter_groups+ should iself be an +Array+ representing the parameters to be passed to the block for a single yield. Any element of +parameter_groups+ that is not an +Array+ is wrapped in an +Array+.
     # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@@ -453,9 +456,9 @@ module Mocha
 
     # @overload def then
     #   Used as syntactic sugar to improve readability. It has no effect on state of the expectation.
-    # @overload def then(state_machine.is(state_name))
-    #   Used to change the +state_machine+ to the state specified by +state_name+ when the expected invocation occurs.
-    #   @param [StateMachine::State] state_machine.is(state_name) provides a mechanism to change the +state_machine+ into the state specified by +state_name+ when the expected method is invoked.
+    # @overload def then(state)
+    #   Used to change the +state_machine+ to the specified state when the expected invocation occurs.
+    #   @param [StateMachine::State] state state_machine.is(state_name) provides a mechanism to change the +state_machine+ into the state specified by +state_name+ when the expected method is invoked.
     #
     #   @see API#states
     #   @see StateMachine
@@ -481,17 +484,14 @@ module Mocha
     #   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 then(*parameters)
-      if parameters.length == 1
-        state = parameters.first
-        add_side_effect(ChangeStateSideEffect.new(state))
-      end
+    def then(state = nil)
+      add_side_effect(ChangeStateSideEffect.new(state)) if state
       self
     end
 
-    # Constrains the expectation to occur only when the +state_machine+ is in the state specified by +state_name+.
+    # Constrains the expectation to occur only when the +state_machine+ is in the state specified by +state_predicate+.
     #
-    # @param [StateMachine::StatePredicate] state_machine.is(state_name) provides a mechanism to determine whether the +state_machine+ is in the state specified by +state_name+ when the expected method is invoked.
+    # @param [StateMachine::StatePredicate] state_predicate +state_machine.is(state_name)+ provides a mechanism to determine whether the +state_machine+ is in the state specified by +state_predicate+ when the expected method is invoked.
     # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
     #
     # @see API#states
@@ -552,7 +552,7 @@ module Mocha
       @block_matcher = BlockMatchers::OptionalBlock.new
       @ordering_constraints = []
       @side_effects = []
-      @cardinality = Cardinality.exactly(1)
+      @cardinality = Cardinality.new.exactly(1)
       @return_values = ReturnValues.new
       @yield_parameters = YieldParameters.new
       @backtrace = backtrace || caller

data/lib/mocha/mock.rb

@@ -330,8 +330,8 @@ module Mocha
       end
     end
 
-    # @private
     if PRE_RUBY_V19
+      # @private
       def respond_to?(symbol, include_private = false)
         respond_to_missing?(symbol, include_private)
       end

data/lib/mocha/mockery.rb

@@ -35,12 +35,13 @@ module Mocha
 
     class << self
       def instance
-        instances.last || Null.new
+        @instances.last || Null.new
       end
 
       def setup
+        @instances ||= []
         mockery = new
-        mockery.logger = instance.logger unless instances.empty?
+        mockery.logger = instance.logger unless @instances.empty?
         @instances.push(mockery)
       end
 
@@ -52,13 +53,6 @@ module Mocha
         instance.teardown
       ensure
         @instances.pop
-        @instances = nil if instances.empty?
-      end
-
-      private
-
-      def instances
-        @instances ||= []
       end
     end
 
@@ -92,11 +86,9 @@ module Mocha
                     end
         raise ExpectationErrorFactory.build(message, backtrace)
       end
-      expectations.each do |e|
-        unless Mocha.configuration.stubbing_method_unnecessarily == :allow
-          next if e.used?
-          on_stubbing_method_unnecessarily(e)
-        end
+      expectations.reject(&:used?).each do |expectation|
+        signature_proc = lambda { expectation.method_signature }
+        check(:stubbing_method_unnecessarily, 'method unnecessarily', signature_proc, expectation.backtrace)
       end
     end
 
@@ -120,9 +112,9 @@ module Mocha
 
     def mocha_inspect
       message = ''
-      message << "unsatisfied expectations:\n- #{unsatisfied_expectations.map(&:mocha_inspect).join("\n- ")}\n" unless unsatisfied_expectations.empty?
-      message << "satisfied expectations:\n- #{satisfied_expectations.map(&:mocha_inspect).join("\n- ")}\n" unless satisfied_expectations.empty?
-      message << "states:\n- #{state_machines.map(&:mocha_inspect).join("\n- ")}" unless state_machines.empty?
+      message << "unsatisfied expectations:\n- #{unsatisfied_expectations.map(&:mocha_inspect).join("\n- ")}\n" if unsatisfied_expectations.any?
+      message << "satisfied expectations:\n- #{satisfied_expectations.map(&:mocha_inspect).join("\n- ")}\n" if satisfied_expectations.any?
+      message << "states:\n- #{state_machines.map(&:mocha_inspect).join("\n- ")}\n" if state_machines.any?
       message
     end
 
@@ -139,11 +131,6 @@ module Mocha
       check(:stubbing_method_on_non_mock_object, 'method on non-mock object', signature_proc)
     end
 
-    def on_stubbing_method_unnecessarily(expectation)
-      signature_proc = lambda { expectation.method_signature }
-      check(:stubbing_method_unnecessarily, 'method unnecessarily', signature_proc, expectation.backtrace)
-    end
-
     attr_writer :logger
 
     def logger