mocha 0.14.0 → 1.0.0.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b1d70e16a4b44a20689afee9a18311ac4fd1fc74
+  data.tar.gz: f09339da5ed1062102aecb18a9461b89314b2fad
+SHA512:
+  metadata.gz: ef120f8f4200434740018195cbada145b17ae893cb615cd45de7b75131acfc1712c0e8779b74a3d3591235382d4cc5babd432a2e78638b349730dd18dc628cf1
+  data.tar.gz: cc80f87dde614a0a06141edabbebc81696ffed1541349ecbcc9fd444888729130f66f9b219bc6e1fc4d9159f86e3db820e8c7fcaa8d801b98e4285f63f6bd3f4

data/README.md

@@ -15,17 +15,17 @@ Install the latest version of the gem with the following command...
 
     $ gem install mocha
 
-Note: If you are intending to use Mocha with Test::Unit or MiniTest, you should only load Mocha *after* loading the relevant test library...
+Note: If you are intending to use Mocha with Test::Unit or MiniTest, you should only setup Mocha *after* loading the relevant test library...
 
     require "test/unit"
     require "mocha/setup"
 
 #### Bundler
 
-If you're using Bundler, ensure the correct load order by not auto-requiring Mocha in the `Gemfile` and then load it later once you know the test library has been loaded...
+If you're using Bundler, include Mocha in the `Gemfile` and then setup Mocha later once you know the test library has been loaded...
 
     # Gemfile
-    gem "mocha", :require => false
+    gem "mocha"
 
     # Elsewhere after Bundler has loaded gems
     require "test/unit"
@@ -33,10 +33,10 @@ If you're using Bundler, ensure the correct load order by not auto-requiring Moc
 
 #### Rails
 
-If you're loading Mocha using Bundler within a Rails application, you should ensure Mocha is not auto-required (as above) and load Mocha manually e.g. at the bottom of your `test_helper.rb`.
+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`.
 
     # Gemfile in Rails app
-    gem "mocha", :require => false
+    gem "mocha"
 
     # At bottom of test_helper.rb
     require "mocha/setup"
@@ -47,7 +47,10 @@ Install the Rails plugin...
 
     $ rails plugin install git://github.com/freerange/mocha.git
 
-Note: As of version 0.9.8, the Mocha plugin is not automatically loaded at plugin load time. Instead it must be manually loaded e.g. at the bottom of your `test_helper.rb`.
+Note: As of version 0.9.8, the Mocha plugin is not automatically setup at plugin load time. Instead it must be manually setup e.g. at the bottom of your `test_helper.rb`.
+
+    # At bottom of test_helper.rb
+    require "mocha/setup"
 
 #### Know Issues
 
@@ -193,6 +196,18 @@ class OrderTest < Test::Unit::TestCase
 end
 ```
 
+### Thread safety
+
+Mocha is currently *not* thread-safe. There are two main reasons for this: (a) in multi-threaded code Mocha exceptions may be raised in a thread other than the one which is running the test and thus a Mocha exception may not be correctly intercepted by Mocha exception handling code; and (b) partial mocking changes the state of objects in the `ObjectSpace` which is shared across all threads in the Ruby process and this access to what is effectively global state is not synchronized.
+
+### Expectation matching / invocation order
+
+Stubs and expectations are basically the same thing. A stub is just an expectation of zero or more invocations. The `Expectation#stubs` method is syntactic sugar to make the intent of the test more explicit.
+
+When a method is invoked on a mock object, the mock object searches through its expectations from newest to oldest to find one that matches the invocation. After the invocation, the matching expectation might stop matching further invocations.
+
+See the [documentation](http://gofreerange.com/mocha/docs/Mocha/Mock.html) for `Mocha::Mock` for further details.
+
 ### Useful Links
 
 * [Official Documentation](http://gofreerange.com/mocha/docs/)
@@ -208,8 +223,13 @@ end
 ### Contributing
 
 * Fork the repository.
-* Make your changes in a branch (including tests).
-* Ensure all of the tests run against all supported versions of Test::Unit, MiniTest & Ruby by running ./build-matrix.rb (note that currently this makes a *lot* of assumptions about your local environment e.g. rbenv installed with specific Ruby versions).
+* Make your changes in a branch.
+* Add tests for new behaviour. Modify existing tests for changes to existing behaviour.
+* Run `bin/build-matrix` from the root directory and ensure all the tests pass.
+  * This script depends on `rbenv` being installed.
+  * You must have all the ruby versions listed in `.travis.yml` under the `rvm` key installed (currently 1.8.7, 1.9.3 & 2.0.0).
+  * I use `rbenv-aliases` to alias the patch versions.
+  * Note that the build matrix takes quite a while to run.
 * Send us a pull request from your fork/branch.
 
 ### Contributors

data/RELEASE.md

@@ -1,5 +1,45 @@
 # Release Notes
 
+## 1.0.0.alpha
+
+* Assume 'mocha' has been required when requiring 'mocha/setup'.
+* Provide shortcuts for integrating with specific test library i.e. `require 'mocha/test_unit'` or `require 'mocha/mini_test'`
+as alternatives to `require 'mocha/setup'`.
+* Do not automatically try to integrate with test libraries. Since the automatic test library integration functionality
+requires the test library to be loaded and this doesn't usually happen until *after* the bundle is loaded, it makes things
+simpler if we use `require 'mocha/setup'` to explicitly setup Mocha when we know the test library has been loaded. Fixes #146 & #155.
+* Consider stubs on superclasses if none exist on primary receiver. Largely based on changes suggested by @ccutrer in #145.
+Note: this may break existing tests which rely on the old behaviour. Stubbing a superclass method and then invoking that
+method on a child class would previously cause an unexpected invocation error. By searching up through the inheritance
+hierarchy for each of the delegate mock objects, we can provide more intuitive behaviour. Instead of an unexpected invocation
+error, invoking the method on the child class will cause the stubbed method on the superclass to be used.
+* Run the standard test suite against Ruby 2.1.0 in the build matrix.
+* Avoid recursion when constructing unexpected invocation message. Fixes #168.
+* Run integration tests against Ruby 2.0.0 with latest Test::Unit gem in the build matrix.
+* Test::Unit is not available in Ruby v1.9.3 standard library, so remove it from the build matrix.
+* Force use of Test::Unit runner, etc in relevant integration tests. Prior to this, I don't think we were really testing the
+Mocha integration with Test::Unit much, because, although `TestUnitTest` was a subclass of `Test::Unit::TestCase`, the
+important test case instances are the temporary ones built by `TestRunner#run_as_test` et al. Prior to this change, these
+would only have used Test::Unit where MiniTest was not available *at all* i.e. only in early versions of Ruby and when the
+MiniTest gem was not loaded.
+* Reset environment variables between build matrix builds.
+* Only activate integration with relevant test library for each of the integration tests.
+* Include standard build combinations from Travis CI config i.e. builds using standard library versions of test libraries.
+* Add explanation of method dispatch. Heavily based on the relevant jMock v1 documentation. Fixes #172.
+* Make class_eval line number more accurate. This sets the line number as the line number of the `def` statement. Closes #169.
+* Allow nesting of `responds_with` parameter matcher. Closes #166.
+* Define `Mocha` module before it's referenced. The test helper defines a class `TestCase` within the `Mocha` module. When
+running the tests inside the bundle, the `Mocha` module happens to be defined at this point. However when running the tests outside the bundle, it is not defined and so an exception is raised: `uninitialized constant Mocha (NameError)`. Fixes #163.
+* Document lack of thread-safety. Fixes #154.
+* Document how to use the build-matrix script. Fixes #160.
+* Stubbing non-public method should use same visibility. This will probably break some existing tests that were somehow relying
+on the stubbed method being public while the original method was protected or private. Fixes #150.
+* Remove ruby version map from build matrix script. I'm using the `rbenv-aliases` plugin to alias minor versions to the
+relevant patch version.
+* Fix `build-matrix.rb` script. Also use `.travis.yml` to decide what combinations to run. This means we
+can now simulate the Travis CI build locally and avoid duplication. Fixes #157.
+
+
 ## 0.14.0
 
 * Official support for MiniTest v5. All tests now pass on the continuous integration build.

data/bin/build-matrix

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+require 'yaml'
+
+def execute(*commands)
+  commands.each do |command|
+    system(command)
+    unless $?.success?
+      message = [
+        "Executing shell command failed.",
+        "  Command: #{command}",
+        "  Status:  #{$?.exitstatus}"
+      ].join("\n")
+      raise message
+    end
+  end
+end
+
+def reset_bundle
+  execute(
+    "rm -rf .bundle/gems",
+    "rm -rf gemfiles/.bundle/gems",
+    "rm -f *.lock",
+    "rm -f gemfiles/*.lock"
+  )
+end
+
+def with_rbenv(command)
+  %{export PATH="$HOME/.rbenv/bin:$PATH"; eval "$(rbenv init -)"; #{command}}
+end
+
+def run(ruby_version, gemfile, task = "test")
+  ENV["RBENV_VERSION"] = ruby_version
+  ENV["BUNDLE_GEMFILE"] = gemfile
+  ENV["MOCHA_OPTIONS"] = "debug"
+  ENV["MOCHA_NO_DOCS"] = "true"
+  reset_bundle
+  execute(
+    with_rbenv("bundle install --gemfile=#{gemfile}"),
+    with_rbenv("bundle exec rake #{task}"),
+  )
+end
+
+travis_config = YAML.load(File.read('.travis.yml'))
+build_configs = travis_config['matrix']['include']
+travis_config['rvm'].each do |ruby_version|
+  travis_config['gemfile'].each do |gemfile|
+    travis_config['env'].each do |env|
+      build_configs << { 'rvm' => ruby_version, 'gemfile' => gemfile, 'env' => env }
+    end
+  end
+end
+
+build_configs.each do |config|
+  ruby_version = config['rvm']
+  gemfile = config['gemfile']
+  environment_variables = Hash[*config['env'].split.flat_map { |e| e.split('=') }]
+  original_environment_variables = {}
+  begin
+    environment_variables.each do |k, v|
+      original_environment_variables[k] = ENV[k]
+      ENV[k] = v
+    end
+    p [ruby_version, gemfile, environment_variables]
+    run(ruby_version, gemfile)
+  ensure
+    original_environment_variables.each do |k, v|
+      ENV[k] = v
+    end
+  end
+end

data/lib/mocha.rb

@@ -1,8 +1 @@
 require 'mocha/version'
-require 'mocha/integration'
-require 'mocha/deprecation'
-
-Mocha::Deprecation.warning("Change `require 'mocha'` to `require 'mocha/setup'`.")
-
-require 'mocha/setup'
-

data/lib/mocha/any_instance_method.rb

@@ -32,11 +32,11 @@ module Mocha
     end
 
     def define_new_method
-      stubbee.class_eval(%{
+      stubbee.class_eval(<<-CODE, __FILE__, __LINE__ + 1)
         def #{method}(*args, &block)
           self.class.any_instance.mocha.method_missing(:#{method}, *args, &block)
         end
-      }, __FILE__, __LINE__)
+      CODE
     end
 
     def remove_new_method

data/lib/mocha/class_method.rb

@@ -54,11 +54,14 @@ module Mocha
     end
 
     def define_new_method
-      stubbee.__metaclass__.class_eval(%{
+      stubbee.__metaclass__.class_eval(<<-CODE, __FILE__, __LINE__ + 1)
         def #{method}(*args, &block)
           mocha.method_missing(:#{method}, *args, &block)
         end
-      }, __FILE__, __LINE__)
+      CODE
+      if @original_visibility
+        Module.instance_method(@original_visibility).bind(stubbee.__metaclass__).call(method)
+      end
     end
 
     def remove_new_method

data/lib/mocha/detection/mini_test.rb

@@ -0,0 +1,25 @@
+module Mocha
+  module Detection
+    module MiniTest
+      def self.testcase
+        if defined?(::Minitest::Test)
+          ::Minitest::Test
+        elsif defined?(::MiniTest::Unit::TestCase)
+          ::MiniTest::Unit::TestCase
+        else
+          nil
+        end
+      end
+
+      def self.version
+        if defined?(::MiniTest::Unit::VERSION)
+          ::MiniTest::Unit::VERSION
+        elsif defined?(::Minitest::VERSION)
+          ::Minitest::VERSION
+        else
+          '0.0.0'
+        end
+      end
+    end
+  end
+end

data/lib/mocha/detection/test_unit.rb

@@ -0,0 +1,29 @@
+module Mocha
+  module Detection
+    module TestUnit
+      def self.testcase
+        if defined?(::Test::Unit::TestCase) &&
+          !(defined?(::MiniTest::Unit::TestCase) && (::Test::Unit::TestCase < ::MiniTest::Unit::TestCase)) &&
+          !(defined?(::MiniTest::Spec) && (::Test::Unit::TestCase < ::MiniTest::Spec))
+          ::Test::Unit::TestCase
+        else
+          nil
+        end
+      end
+
+      def self.version
+        version = '1.0.0'
+        if testcase
+          begin
+            require 'test/unit/version'
+          rescue LoadError
+          end
+          if defined?(::Test::Unit::VERSION)
+            version = ::Test::Unit::VERSION
+          end
+        end
+        version
+      end
+    end
+  end
+end

data/lib/mocha/expectation_list.rb

@@ -2,8 +2,8 @@ module Mocha
 
   class ExpectationList
 
-    def initialize
-      @expectations = []
+    def initialize(expectations = [])
+      @expectations = expectations
     end
 
     def add(expectation)
@@ -47,6 +47,10 @@ module Mocha
       @expectations.any?
     end
 
+    def +(other)
+      self.class.new(self.to_a + other.to_a)
+    end
+
     private
 
     def matching_expectations(method_name, *arguments)

data/lib/mocha/integration.rb

@@ -6,8 +6,8 @@ module Mocha
   module Integration
     def self.activate
       if [Integration::TestUnit, Integration::MiniTest].map(&:activate).none?
-        Deprecation.warning("Test::Unit or MiniTest must be loaded *before* Mocha.")
-        Deprecation.warning("If you're integrating with a test library other than Test::Unit or MiniTest, you should use `require 'mocha/api'` instead of `require 'mocha'`.")
+        Deprecation.warning("Test::Unit or MiniTest must be loaded *before* `require 'mocha/setup'`.")
+        Deprecation.warning("If you're integrating with a test library other than Test::Unit or MiniTest, you should use `require 'mocha/api'` instead of `require 'mocha/setup'`.")
       end
     end
   end

data/lib/mocha/integration/mini_test.rb

@@ -1,5 +1,7 @@
 require 'mocha/debug'
 
+require 'mocha/detection/mini_test'
+
 require 'mocha/integration/mini_test/nothing'
 require 'mocha/integration/mini_test/version_13'
 require 'mocha/integration/mini_test/version_140'
@@ -16,13 +18,8 @@ module Mocha
   module Integration
     module MiniTest
       def self.activate
-        return false unless defined?(::MiniTest::Unit::TestCase)
-
-        mini_test_version = begin
-          Gem::Version.new(::MiniTest::Unit::VERSION)
-        rescue LoadError
-          Gem::Version.new('0.0.0')
-        end
+        return false unless Detection::MiniTest.testcase
+        mini_test_version = Gem::Version.new(Detection::MiniTest.version)
 
         Debug.puts "Detected MiniTest version: #{mini_test_version}"
 
@@ -40,15 +37,13 @@ module Mocha
           MiniTest::Nothing
         ].detect { |m| m.applicable_to?(mini_test_version) }
 
-        target = defined?(Minitest::Test) ? ::Minitest::Test : ::MiniTest::Unit::TestCase
+        target = Detection::MiniTest.testcase
         unless target < integration_module
           Debug.puts "Applying #{integration_module.description}"
           target.send(:include, integration_module)
         end
+        true
       end
-      true
     end
   end
 end
-
-

data/lib/mocha/integration/test_unit.rb

@@ -1,5 +1,7 @@
 require 'mocha/debug'
 
+require 'mocha/detection/test_unit'
+
 require 'mocha/integration/test_unit/nothing'
 require 'mocha/integration/test_unit/ruby_version_185_and_below'
 require 'mocha/integration/test_unit/ruby_version_186_and_above'
@@ -13,15 +15,8 @@ module Mocha
   module Integration
     module TestUnit
       def self.activate
-        return false unless defined?(::Test::Unit::TestCase) && !(defined?(::MiniTest::Unit::TestCase) && (::Test::Unit::TestCase < ::MiniTest::Unit::TestCase)) && !(defined?(::MiniTest::Spec) && (::Test::Unit::TestCase < ::MiniTest::Spec))
-
-        test_unit_version = begin
-          require 'test/unit/version'
-          Gem::Version.new(::Test::Unit::VERSION)
-        rescue LoadError
-          Gem::Version.new('1.0.0')
-        end
-
+        return false unless Detection::TestUnit.testcase
+        test_unit_version = Gem::Version.new(Detection::TestUnit.version)
         ruby_version = Gem::Version.new(RUBY_VERSION.dup)
 
         Debug.puts "Detected Ruby version: #{ruby_version}"

data/lib/mocha/mini_test.rb

@@ -0,0 +1,3 @@
+require "mocha/integration/mini_test"
+
+Mocha::Integration::MiniTest.activate

data/lib/mocha/mock.rb

@@ -2,6 +2,7 @@ require 'metaclass'
 require 'mocha/expectation'
 require 'mocha/expectation_list'
 require 'mocha/names'
+require 'mocha/receivers'
 require 'mocha/method_matcher'
 require 'mocha/parameters_matcher'
 require 'mocha/unexpected_invocation'
@@ -12,7 +13,59 @@ module Mocha
 
   # Traditional mock object.
   #
-  # All methods return an {Expectation} which can be further modified by methods on {Expectation}.
+  # All methods return an {Expectation} which can be further modified by
+  # methods on {Expectation}.
+  #
+  # Stubs and expectations are basically the same thing. A stub is just an
+  # expectation of zero or more invocations. The {#stubs} method is syntactic
+  # sugar to make the intent of the test more explicit.
+  #
+  # When a method is invoked on a mock object, the mock object searches through
+  # its expectations from newest to oldest to find one that matches the
+  # invocation. After the invocation, the matching expectation might stop
+  # matching further invocations. For example, an +expects(:foo).once+
+  # expectation only matches once and will be ignored on future invocations
+  # while an +expects(:foo).at_least_once+ expectation will always be matched
+  # against invocations.
+  #
+  # This scheme allows you to:
+  #
+  # - Set up default stubs in your the +setup+ method of your test class and
+  #   override some of those stubs in individual tests.
+  # - Set up different +once+ expectations for the same method with different
+  #   action per invocation. However, it's better to use the
+  #   {Expectation#returns} method with multiple arguments to do this, as
+  #   described below.
+  #
+  # However, there are some possible "gotchas" caused by this scheme:
+  #
+  # - if you create an expectation and then a stub for the same method, the
+  #   stub will always override the expectation and the expectation will never
+  #   be met.
+  # - if you create a stub and then an expectation for the same method, the
+  #   expectation will match, and when it stops matching the stub will be used
+  #   instead, possibly masking test failures.
+  # - if you create different expectations for the same method, they will be
+  #   invoked in the opposite order than that in which they were specified,
+  #   rather than the same order.
+  #
+  # The best thing to do is not set up multiple expectations and stubs for the
+  # same method with exactly the same matchers. Instead, use the
+  # {Expectation#returns} method with multiple arguments to create multiple
+  # actions for a method. You can also chain multiple calls to
+  # {Expectation#returns} and {Expectation#raises} (along with syntactic sugar
+  # {Expectation#then} if desired).
+  #
+  # @example
+  #   object = mock()
+  #   object.stubs(:expected_method).returns(1, 2).then.raises(Exception)
+  #   object.expected_method # => 1
+  #   object.expected_method # => 2
+  #   object.expected_method # => raises exception of class Exception1
+  #
+  # If you want to specify more complex ordering or order invocations across
+  # different mock objects, use the {Expectation#in_sequence} method to
+  # explicitly define a total or partial ordering of invocations.
   class Mock
 
     # Adds an expectation that the specified method must be called exactly once with any parameters.
@@ -194,12 +247,14 @@ module Mocha
     end
 
     # @private
-    def initialize(mockery, name = nil, &block)
+    def initialize(mockery, name = nil, receiver = nil, &block)
       @mockery = mockery
       @name = name || DefaultName.new(self)
+      @receiver = receiver || DefaultReceiver.new(self)
       @expectations = ExpectationList.new
       @everything_stubbed = false
       @responder = nil
+      @unexpected_invocation = nil
       instance_eval(&block) if block
     end
 
@@ -223,18 +278,28 @@ module Mocha
       @everything_stubbed = true
     end
 
+    # @private
+    def all_expectations
+      @receiver.mocks.inject(ExpectationList.new) { |e, m| e + m.__expectations__ }
+    end
+
     # @private
     def method_missing(symbol, *arguments, &block)
       if @responder and not @responder.respond_to?(symbol)
         raise NoMethodError, "undefined method `#{symbol}' for #{self.mocha_inspect} which responds like #{@responder.mocha_inspect}"
       end
-      if matching_expectation_allowing_invocation = @expectations.match_allowing_invocation(symbol, *arguments)
+      if matching_expectation_allowing_invocation = all_expectations.match_allowing_invocation(symbol, *arguments)
         matching_expectation_allowing_invocation.invoke(&block)
       else
-        if (matching_expectation = @expectations.match(symbol, *arguments)) || (!matching_expectation && !@everything_stubbed)
-          matching_expectation.invoke(&block) if matching_expectation
-          message = UnexpectedInvocation.new(self, symbol, *arguments).to_s
-          message << @mockery.mocha_inspect
+        if (matching_expectation = all_expectations.match(symbol, *arguments)) || (!matching_expectation && !@everything_stubbed)
+          if @unexpected_invocation.nil?
+            @unexpected_invocation = UnexpectedInvocation.new(self, symbol, *arguments)
+            matching_expectation.invoke(&block) if matching_expectation
+            message = @unexpected_invocation.full_description
+            message << @mockery.mocha_inspect
+          else
+            message = @unexpected_invocation.short_description
+          end
           raise ExpectationErrorFactory.build(message, caller)
         end
       end
@@ -249,7 +314,7 @@ module Mocha
           @responder.respond_to?(symbol)
         end
       else
-        @everything_stubbed || @expectations.matches_method?(symbol)
+        @everything_stubbed || all_expectations.matches_method?(symbol)
       end
     end