mocha 1.10.2 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0071e59a90a0d4f365ff5e19e4a0b5f74483d10c41fd77362d3414071fe4829b
-  data.tar.gz: 0a22b3a9cd04dce410fe6ef613e6c2a81fb905bbf60ac01228f8aa19852d6d8a
+  metadata.gz: 77366bffa410729ac6089097db85ded323e74d1ec7bc6eb0ea13ae4a18b44eac
+  data.tar.gz: f9f3c89bbc29393e99ec62e0d1395ed4fa4863d0f790d24bbe6be3537450e4c1
 SHA512:
-  metadata.gz: 91678a1e05d7516e2079604c19a97c0b67d6127e4efb1e152ae81735c12561b80c32f28d7318270247b9fa0cc659f976067c1baf074293c060f05db2090b4203
-  data.tar.gz: 298befb4573b09e6c597c03af24f083a5de24be1ccebc172f8efa4ac5debf6d5bfbc6da062edd2f2925b0864b020faf55644ba88ffaa55161c806613d6a0b6dd
+  metadata.gz: 91e277be3c868ef2f6655016a53f040835b8e9d6390c789b6f047be72e9b96726865eefcb161b86d0f8e89ead1c58e9adbf1a1cbcdf9cba8a0f0b536de86222d
+  data.tar.gz: 4b7bf751e350762a5a3d9cd17fbe1a590ff5122a718417b75304fa86f8323b20652a24584cedabd859395aeef004402e57c70c15cd88746032659b0d9df4cccf

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 [Circle CI](https://app.circleci.com/pipelines/github/freerange/mocha).
 * 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 [![CircleCI status of freerange/mocha](https://circleci.com/gh/freerange/mocha.svg?style=shield&circle-token=bc1f6576c77da43ec58badde9273fa4eb1d7f53a)](https://app.circleci.com/pipelines/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 CircleCI build is passing - https://app.circleci.com/pipelines/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,92 @@
 # Release Notes
 
+## 1.13.0
+
+### External changes
+
+* Add `ParameterMatchers#has_keys` - thanks to @cstyles for #512 (18d8104)
+* Fix misleading exception message in `ParameterMatchers#has_entry` - thanks to @cstyles for #513 (9c4ef13)
+* Only add dependency on rubocop if we're actually going to use it (f2f879f)
+* Fix rake dependency constraints for older Ruby versions (7ce5f29)
+
+### Internal changes
+
+* Check documentation can be generated as part of CircleCI build (b30d9a9)
+* Add --fail-on-warning option to yard rake task (53a6ee3)
+* Add a weekly scheduled build to the CircleCI build (fd2a4c6)
+* Add Ruby v1.8 to the CircleCI build matrix (818ca03)
+* Add API token to fix CircleCI badge in README (607c5aa)
+* Provide wrapped option for #mocha_inspect on hashes & arrays (d8f44bc)
+* Use CircleCI instead of TravisCI for automated builds (c98c6ec)
+* Switch to newer default Travis CI build env (c78f75c)
+* Use latest Ruby versions in Travis CI builds (9e0043a)
+* Use latest JRuby v9.2.18 in Travis CI builds (8c99a1b)
+* Use consistent JRuby versions in Travis CI builds (0f849aa)
+* Use more recent version of JRuby in Travis CI build matrix (58653db)
+
+## 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):

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}", '--fail-on-warning']
   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

@@ -65,8 +65,8 @@ 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)
+    #
+    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]
@@ -91,7 +91,6 @@ module Mocha
       mock.expects(expectations)
       mock
     end
-    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
 
     # Builds a new mock object
     #

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

data/lib/mocha/configuration.rb

@@ -43,7 +43,7 @@ module Mocha
       :stubbing_non_public_method => :allow,
       :stubbing_method_on_nil => :prevent,
       :display_matching_invocations_on_failure => false,
-      :reinstate_undocumented_behaviour_from_v1_9 => false
+      :reinstate_undocumented_behaviour_from_v1_9 => true
     }.freeze
 
     attr_reader :options
@@ -258,7 +258,7 @@ module Mocha
     #
     # Enabling this configuration option reinstates the previous behaviour, but displays a deprecation warning.
     #
-    # @param [Boolean] value +true+ to reinstate undocumented behaviour; disabled by default.
+    # @param [Boolean] value +true+ to reinstate undocumented behaviour; enabled by default.
     #
     # @example Reinstate undocumented behaviour for {API#mock}
     #   Mocha.configure do |c|

data/lib/mocha/expectation.rb

@@ -10,6 +10,7 @@ require 'mocha/in_state_ordering_constraint'
 require 'mocha/change_state_side_effect'
 require 'mocha/cardinality'
 require 'mocha/configuration'
+require 'mocha/block_matcher'
 
 module Mocha
   # Methods on expectations returned from {Mock#expects}, {Mock#stubs}, {ObjectMethods#expects} and {ObjectMethods#stubs}.
@@ -41,7 +42,7 @@ module Mocha
     #   object.expected_method
     #   # => verify fails
     def times(range)
-      @cardinality = Cardinality.times(range)
+      @cardinality.times(range)
       self
     end
 
@@ -67,7 +68,7 @@ module Mocha
     #   object.expected_method
     #   # => verify fails
     def twice
-      @cardinality = Cardinality.exactly(2)
+      @cardinality.exactly(2)
       self
     end
 
@@ -92,7 +93,7 @@ module Mocha
     #   object.expects(:expected_method).once
     #   # => verify fails
     def once
-      @cardinality = Cardinality.exactly(1)
+      @cardinality.exactly(1)
       self
     end
 
@@ -109,7 +110,7 @@ module Mocha
     #   object.expects(:expected_method).never
     #   # => verify succeeds
     def never
-      @cardinality = Cardinality.exactly(0)
+      @cardinality.exactly(0)
       self
     end
 
@@ -129,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
 
@@ -148,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+.
@@ -166,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
 
@@ -185,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+.
@@ -224,7 +223,49 @@ 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 the expected method must be called with a block.
+    #
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Expected method must be called with a block.
+    #   object = mock()
+    #   object.expects(:expected_method).with_block_given
+    #   object.expected_method { 1 + 1 }
+    #   # => verify succeeds
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).with_block_given
+    #   object.expected_method
+    #   # => verify fails
+    def with_block_given
+      @block_matcher = BlockMatchers::BlockGiven.new
+      self
+    end
+
+    # Modifies expectation so that the expected method must be called without a block.
+    #
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Expected method must be called without a block.
+    #   object = mock()
+    #   object.expects(:expected_method).with_no_block_given
+    #   object.expected_method
+    #   # => verify succeeds
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).with_block_given
+    #   object.expected_method { 1 + 1 }
+    #   # => verify fails
+    def with_no_block_given
+      @block_matcher = BlockMatchers::NoBlockGiven.new
+      self
+    end
+
+    # 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.
     #
@@ -234,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()
@@ -256,13 +296,14 @@ module Mocha
     #   fibonacci.next_pair { |first, second| sum = first + second }
     #   sum # => 2
     def yields(*parameters)
-      @yield_parameters.add(*parameters)
-      self
+      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.
+    # @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.
     # @see #then
     #
@@ -283,7 +324,7 @@ module Mocha
     #   rows_from_first_invocation # => [['old_row1_col1', 'old_row1_col2'], ['old_row2_col1', '']]
     #   rows_from_second_invocation # => [['new_row1_col1', ''], ['new_row2_col1', 'new_row2_col2']]
     def multiple_yields(*parameter_groups)
-      @yield_parameters.multiple_add(*parameter_groups)
+      @yield_parameters.add(*parameter_groups)
       self
     end
 
@@ -415,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
@@ -443,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
@@ -511,9 +549,10 @@ module Mocha
       @mock = mock
       @method_matcher = MethodMatcher.new(expected_method_name.to_sym)
       @parameters_matcher = ParametersMatcher.new
+      @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
@@ -551,7 +590,7 @@ module Mocha
 
     # @private
     def match?(invocation)
-      @method_matcher.match?(invocation.method_name) && @parameters_matcher.match?(invocation.arguments) && in_correct_order?
+      @method_matcher.match?(invocation.method_name) && @parameters_matcher.match?(invocation.arguments) && @block_matcher.match?(invocation.block) && in_correct_order?
     end
 
     # @private
@@ -601,7 +640,9 @@ module Mocha
 
     # @private
     def method_signature
-      "#{@mock.mocha_inspect}.#{@method_matcher.mocha_inspect}#{@parameters_matcher.mocha_inspect}"
+      signature = "#{@mock.mocha_inspect}.#{@method_matcher.mocha_inspect}#{@parameters_matcher.mocha_inspect}"
+      signature << " #{@block_matcher.mocha_inspect}" if @block_matcher.mocha_inspect
+      signature
     end
   end
 end