mocha 0.3.3 → 0.4.0

data/README

@@ -1,12 +1,12 @@
 = Mocha
 
-Mocha is a library for mocking and stubbing within a TestCase[http://www.ruby-doc.org/core/classes/Test/Unit.html] using a syntax like that of JMock[http://www.jmock.org], and SchMock[http://rubyforge.org/projects/schmock].
+Mocha is a library for mocking and stubbing using a syntax like that of JMock[http://www.jmock.org], and SchMock[http://rubyforge.org/projects/schmock]. Most commonly Mocha is used in conjunction with Test::Unit[http://www.ruby-doc.org/core/classes/Test/Unit.html], but it can be used in other contexts.
 
-One of its main advantages is that it allows you to mock and stub methods on _real_ (non-mock) classes and instances. You can for example stub ActiveRecord[http://api.rubyonrails.com/classes/ActiveRecord/Base.html] instance methods like +create+, +save+, +destroy+ and even class methods like +find+ to avoid hitting the database in unit tests. This is a feature that is not currently offered by other Ruby[http://www.ruby-doc.org/] mocking libraries like FlexMock[http://onestepback.org/software/flexmock] and RSpec[http://rspec.rubyforge.org].
+One of its main advantages is that it allows you to mock and stub methods on _real_ (non-mock) classes and instances. You can for example stub ActiveRecord[http://api.rubyonrails.com/classes/ActiveRecord/Base.html] instance methods like +create+, +save+, +destroy+ and even class methods like +find+ to avoid hitting the database in unit tests.
 
-Mocha provides a unified, simple and readable syntax for both traditional mocking and for mocking with non-mock objects.
+Mocha provides a unified, simple and readable syntax for both traditional mocking and for mocking with _real_ objects.
 
-Mocha has been harvested from projects at Reevoo[http://www.reevoo.com] by me (James[http://blog.floehopper.org]) and my colleagues Ben[http://www.reevoo.com/blogs/bengriffiths/], Chris[http://blog.seagul.co.uk] and Paul[http://po-ru.com]. Mocha is in use on real-world Rails[http://www.rubyonrails.org] projects.
+Mocha has been harvested from projects at Reevoo[http://www.reevoo.com] by me (James[http://blog.floehopper.org]) and my colleagues Ben[http://www.reevoo.com/blogs/bengriffiths], Chris[http://blog.seagul.co.uk] and Paul[http://po-ru.com]. Mocha is in use on real-world Rails[http://www.rubyonrails.org] projects.
 
 == Download and Installation
 

data/RELEASE

@@ -1,3 +1,35 @@
+= 0.4.0
+
+- Allow naming of mocks (patch from Chris Roos).
+- Specify multiple return values for consecutive calls.
+- Improved consistency of expectation error messages.
+- Allow mocking of Object instance methods e.g. kind_of?, type.
+- Provide aliased versions of #expects and #stubs to allow mocking of these methods.
+- Added at_least, at_most, at_most_once methods to expectation.
+- Allow expects and stubs to take a hash of method and return values.
+- Eliminate warning: "instance variable @yield not initialized" (patch from Xavier Shay).
+- Restore instance methods on partial mocks (patch from Chris Roos).
+- Allow stubbing of a method with non-word characters in its name (patch from Paul Battley).
+- Removed coupling to Test::Unit.
+- Allow specified exception instance to be raised (patch from Chris Roos).
+- Make mock object_id appear in hex like normal Ruby inspect (patch from Paul Battley).
+- Fix path to object.rb in rdoc rake task (patch from Tomas Pospisek).
+- Reverse order in which expectations are matched, so that last expectation is matched first. This allows e.g. a call to #stubs to be effectively overridden by a call to #expects (patch from Tobias Lutke).
+- Stubba & SmartTestCase modules incorporated into Mocha module so only need to require 'mocha' - no longer need to require 'stubba'.
+- AutoMocha removed.
+
+= 0.3.3
+
+- Quick bug fix to restore instance methods on partial mocks (for Kevin Clark).
+
+= 0.3.2
+
+- Examples added.
+
+= 0.3.1
+
+- Dual licensing with MIT license added.
+
 = 0.3.0
 
 * Rails plugin.

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake/gempackagetask'
 require 'rake/contrib/sshpublisher'
 
 module Mocha
-  VERSION = "0.3.3"
+  VERSION = "0.4.0"
 end
 
 desc "Default task is currently to run all tests"
@@ -23,7 +23,7 @@ Rake::RDocTask.new do |task|
   task.rdoc_dir = 'doc'
   task.template = "html_with_google_analytics"
   task.options << "--line-numbers" << "--inline-source"
-  task.rdoc_files.include('README', 'RELEASE', 'COPYING', 'MIT-LICENSE', 'agiledox.txt', 'lib/mocha/auto_verify.rb', 'lib/mocha/mock_methods.rb', 'lib/mocha/expectation.rb', 'lib/stubba/object.rb')
+  task.rdoc_files.include('README', 'RELEASE', 'COPYING', 'MIT-LICENSE', 'agiledox.txt', 'lib/mocha/auto_verify.rb', 'lib/mocha/mock_methods.rb', 'lib/mocha/expectation.rb', 'lib/mocha/object.rb')
 end
 task :rdoc => :examples
 
@@ -88,7 +88,7 @@ specification = Gem::Specification.new do |s|
   s.rdoc_options << '--title' << 'Mocha' << '--main' << 'README' << '--line-numbers'
                          
   s.autorequire = 'mocha'
-  s.files = FileList['{lib,test}/**/*.rb', '[A-Z]*'].exclude('TODO').to_a
+  s.files = FileList['{lib,test,examples}/**/*.rb', '[A-Z]*'].exclude('TODO').to_a
 	s.test_file = "test/all_tests.rb"
 end
 

data/examples/misc.rb

@@ -0,0 +1,36 @@
+# Mocking a class method
+
+  product = Product.new
+  Product.expects(:find).with(1).returns(product)
+  assert_equal product, Product.find(1)
+
+# Mocking an instance method on a real object
+
+  product = Product.new
+  product.expects(:save).returns(true)
+  assert product.save
+
+# Stubbing instance methods on real object
+
+  prices = [stub(:pence => 1000), stub(:pence => 2000)]
+  product = Product.new
+  product.stubs(:prices).returns(prices)
+  assert_equal [1000, 2000], product.prices.collect {|p| p.pence}
+
+# Stubbing an instance method on all instances of a class
+
+  Product.any_instance.stubs(:name).returns('stubbed_name')
+  product = Product.new
+  assert_equal 'stubbed_name', product.name
+
+# Traditional mocking
+
+  object = mock()
+  object.expects(:expected_method).with(:p1, :p2).returns(:result)
+  assert_equal :result, object.expected_method(:p1, :p2)
+
+# Shortcuts
+
+  object = stub(:method1 => :result1, :method2 => :result2)
+  assert_equal :result1, object.method1
+  assert_equal :result2, object.method2

data/examples/mocha.rb

@@ -0,0 +1,26 @@
+class Enterprise
+
+  def initialize(dilithium)
+    @dilithium = dilithium
+  end
+
+  def go(warp_factor)
+    warp_factor.times { @dilithium.nuke(:anti_matter) }
+  end
+
+end
+
+require 'test/unit'
+require 'rubygems'
+require 'mocha'
+
+class EnterpriseTest < Test::Unit::TestCase
+
+  def test_should_boldly_go
+    dilithium = mock()
+    dilithium.expects(:nuke).with(:anti_matter).at_least_once  # auto-verified at end of test
+    enterprise = Enterprise.new(dilithium)
+    enterprise.go(2)
+  end
+
+end

data/examples/stubba.rb

@@ -0,0 +1,65 @@
+class Order
+
+  attr_accessor :shipped_on
+
+  def total_cost
+    line_items.inject(0) { |total, line_item| total + line_item.price } + shipping_cost
+  end
+
+  def total_weight
+    line_items.inject(0) { |total, line_item| total + line_item.weight }
+  end
+
+  def shipping_cost
+    total_weight * 5 + 10
+  end
+
+  class << self
+
+    def find_all
+      # Database.connection.execute('select * from orders...
+    end
+  
+    def number_shipped_since(date)
+      find_all.select { |order| order.shipped_on > date }.size
+    end
+
+    def unshipped_value
+      find_all.inject(0) { |total, order| order.shipped_on ? total : total + order.total_cost }
+    end
+
+  end
+
+end
+
+require 'test/unit'
+require 'rubygems'
+require 'stubba'
+
+class OrderTest < Test::Unit::TestCase
+
+  # illustrates stubbing instance method
+  def test_should_calculate_shipping_cost_based_on_total_weight
+    order = Order.new
+    order.stubs(:total_weight).returns(10)
+    assert_equal 60, order.shipping_cost
+  end
+
+  # illustrates stubbing class method
+  def test_should_count_number_of_orders_shipped_after_specified_date
+    now = Time.now; week_in_secs = 7 * 24 * 60 * 60
+    order_1 = Order.new; order_1.shipped_on = now - 1 * week_in_secs
+    order_2 = Order.new; order_2.shipped_on = now - 3 * week_in_secs
+    Order.stubs(:find_all).returns([order_1, order_2])
+    assert_equal 1, Order.number_shipped_since(now - 2 * week_in_secs)
+  end
+
+  # illustrates stubbing instance method for all instances of a class
+  def test_should_calculate_value_of_unshipped_orders
+    Order.stubs(:find_all).returns([Order.new, Order.new, Order.new])
+    Order.any_instance.stubs(:shipped_on).returns(nil)
+    Order.any_instance.stubs(:total_cost).returns(10)
+    assert_equal 30, Order.unshipped_value
+  end
+
+end

data/lib/mocha.rb

@@ -1,7 +1,19 @@
-require 'smart_test_case'
-require 'mocha/auto_verify'
-require 'shared/backtracefilter'
+require 'mocha_standalone'
+require 'mocha/test_case_adapter'
+
+require 'test/unit/testcase'
+
+module Test
+
+  module Unit
+
+    class TestCase
+  
+      include Mocha::Standalone
+      include Mocha::TestCaseAdapter
+      
+    end
+
+  end
 
-class Test::Unit::TestCase
-  include Mocha::AutoVerify unless ancestors.include?(Mocha::AutoVerify)
 end

data/lib/{stubba → mocha}/any_instance_method.rb

@@ -1,6 +1,6 @@
-require 'stubba/class_method'
+require 'mocha/class_method'
 
-module Stubba
+module Mocha
 
   class AnyInstanceMethod < ClassMethod
   

data/lib/mocha/auto_verify.rb

@@ -6,12 +6,9 @@ require 'mocha/mock'
 #
 # See Mocha::MockMethods for methods on mock objects.
 module Mocha
+  
   module AutoVerify
   
-    def self.included(base) # :nodoc:
-      base.add_teardown_method(:teardown_mocks)
-    end
-
     def mocks # :nodoc:
       @mocks ||= []
     end
@@ -19,7 +16,7 @@ module Mocha
     def reset_mocks # :nodoc:
       @mocks = nil
     end
-  
+    
     # :call-seq: mock(name) -> mock object
     #            mock(expected_methods = {}) -> mock object
     #            mock(name, expected_methods = {}) -> mock object
@@ -83,9 +80,12 @@ module Mocha
       name, expectations = name_and_expectations_from_args(args)
       build_mock_with_expectations(:stub_everything, expectations, name)
     end
+    
+    def verify_mocks # :nodoc:
+      mocks.each { |mock| mock.verify { yield if block_given? } }
+    end
 
     def teardown_mocks # :nodoc:
-      mocks.each { |mock| mock.verify { add_assertion } }
       reset_mocks
     end
   
@@ -94,7 +94,7 @@ module Mocha
       expectation_type = :stubs if expectation_type == :stub_everything
       mock = Mocha::Mock.new(stub_everything, name)
       expectations.each do |method, result|
-        mock.send(expectation_type, method).returns(result)
+        mock.__send__(expectation_type, method).returns(result)
       end
       mocks << mock
       mock

data/lib/{stubba → mocha}/central.rb

@@ -1,4 +1,4 @@
-module Stubba
+module Mocha
   
   class Central
   
@@ -20,7 +20,7 @@ module Stubba
     end
     
     def unique_mocks
-      stubba_methods.collect { |method| method.mock }.uniq
+      stubba_methods.inject({}) { |mocks, method| mocks[method.mock.__id__] = method.mock; mocks }.values
     end
   
     def unstub_all

data/lib/{stubba → mocha}/class_method.rb

@@ -1,6 +1,6 @@
 require 'mocha/metaclass'
 
-module Stubba
+module Mocha
 
   class ClassMethod
   
@@ -26,29 +26,26 @@ module Stubba
     end
   
     def hide_original_method
-      stubbee.metaclass.class_eval "alias_method :#{hidden_method}, :#{method}" if stubbee.metaclass.method_defined?(method)
+      stubbee.__metaclass__.class_eval "alias_method :#{hidden_method}, :#{method}" if stubbee.__metaclass__.method_defined?(method)
     end
   
     def define_new_method
-      stubbee.metaclass.class_eval "def #{method}(*args, &block); mocha.method_missing(:#{method}, *args, &block); end"
+      stubbee.__metaclass__.class_eval "def #{method}(*args, &block); mocha.method_missing(:#{method}, *args, &block); end"
     end
   
     def remove_new_method
-      stubbee.metaclass.class_eval "remove_method :#{method}"
+      stubbee.__metaclass__.class_eval "remove_method :#{method}"
     end
   
     def restore_original_method
-      stubbee.metaclass.class_eval "alias_method :#{method}, :#{hidden_method}; remove_method :#{hidden_method}" if stubbee.metaclass.method_defined?(hidden_method)
+      stubbee.__metaclass__.class_eval "alias_method :#{method}, :#{hidden_method}; remove_method :#{hidden_method}" if stubbee.__metaclass__.method_defined?(hidden_method)
     end
   
     def hidden_method
-      "__stubba__#{method.to_s.sub('!', '_exclamation_mark').sub('?', '_question_mark')}__stubba__"
+      method_name = method.to_s.gsub(/\W/) {|s| "_substituted_character_#{s[0]}_" }
+      "__stubba__#{method_name}__stubba__"
     end  
   
-    def cannot_replace_method_error
-      Test::Unit::AssertionFailedError.new("Cannot replace #{method} because it is not defined in #{stubbee}.")
-    end
-  
     def eql?(other)
       return false unless (other.class == self.class)
       (stubbee == other.stubbee) and (method == other.method)

data/lib/mocha/expectation.rb

@@ -1,5 +1,12 @@
 require 'mocha/infinite_range'
 require 'mocha/pretty_parameters'
+require 'mocha/expectation_error'
+
+class Object
+
+  alias_method :__is_a__, :is_a?
+
+end
 
 module Mocha
   # Methods on expectations returned from Mocha::MockMethods#expects and Mocha::MockMethods#stubs
@@ -13,19 +20,17 @@ module Mocha
       def ==(other)
         true
       end
-      def to_s
-        "** any **"
-      end
     end
   
     attr_reader :method_name, :backtrace
 
-    def initialize(method_name, backtrace = nil)
-      @method_name = method_name
+    def initialize(mock, method_name, backtrace = nil)
+      @mock, @method_name = mock, method_name
       @count = 1
       @parameters, @parameter_block = AlwaysEqual.new, nil
       @invoked, @return_value = 0, nil
       @backtrace = backtrace || caller
+      @yield = nil
     end
     
     def yield?
@@ -79,11 +84,12 @@ module Mocha
     #   object.expected_method # => verify succeeds
     def never
       times(0)
+      self
     end
   
-    # :call-seq: at_least(minimum) -> expectation
+    # :call-seq: at_least(minimum_number_of_times) -> expectation
     #
-    # Modifies expectation so that the expected method must be called at least a +minimum+ number of times.
+    # Modifies expectation so that the expected method must be called at least a +minimum_number_of_times+.
     #   object = mock()
     #   object.expects(:expected_method).at_least(2)
     #   3.times { object.expected_method } # => verify succeeds
@@ -91,8 +97,8 @@ module Mocha
     #   object = mock()
     #   object.expects(:expected_method).at_least(2)
     #   object.expected_method # => verify fails
-    def at_least(minimum)
-      times(Range.at_least(minimum))
+    def at_least(minimum_number_of_times)
+      times(Range.at_least(minimum_number_of_times))
       self
     end
   
@@ -111,6 +117,36 @@ module Mocha
       self
     end
   
+    # :call-seq: at_most(maximum_number_of_times) -> expectation
+    #
+    # Modifies expectation so that the expected method must be called at most a +maximum_number_of_times+.
+    #   object = mock()
+    #   object.expects(:expected_method).at_most(2)
+    #   2.times { object.expected_method } # => verify succeeds
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).at_most(2)
+    #   3.times { object.expected_method } # => verify fails
+    def at_most(maximum_number_of_times)
+      times(Range.at_most(maximum_number_of_times))
+      self
+    end
+  
+    # :call-seq: at_most_once() -> expectation
+    #
+    # Modifies expectation so that the expected method must be called at most once.
+    #   object = mock()
+    #   object.expects(:expected_method).at_most_once
+    #   object.expected_method # => verify succeeds
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).at_most_once
+    #   2.times { object.expected_method } # => verify fails
+    def at_most_once()
+      at_most(1)
+      self
+    end
+  
     # :call-seq: with(*arguments, &parameter_block) -> expectation
     #
     # Modifies expectation so that the expected method must be called with specified +arguments+.
@@ -151,19 +187,25 @@ module Mocha
     end
 
     # :call-seq: returns(value) -> expectation
+    # :call-seq: returns(*values) -> expectation
     #
     # Modifies expectation so that when the expected method is called, it returns the specified +value+.
     #   object = mock()
-    #   object.expects(:expected_method).returns('result')
-    #   object.expected_method # => 'result'
+    #   object.stubs(:stubbed_method).returns('result')
+    #   object.stubbed_method # => 'result'
+    #   object.stubbed_method # => 'result'
+    # If multiple +values+ are given, these are returned in turn on consecutive calls to the method.
+    #   object = mock()
+    #   object.stubs(:stubbed_method).returns(1, 2)
+    #   object.stubbed_method # => 1
+    #   object.stubbed_method # => 2
     # If +value+ is a Proc, then expected method will return result of calling Proc.
     #   object = mock()
-    #   results = [111, 222]
-    #   object.stubs(:expected_method).returns(lambda { results.shift })
-    #   object.expected_method # => 111
-    #   object.expected_method # => 222
-    def returns(value)
-      @return_value = value
+    #   object.stubs(:stubbed_method).returns(lambda { rand(100) })
+    #   object.stubbed_method # => 41
+    #   object.stubbed_method # => 77
+    def returns(*values)
+      @return_value = (values.size > 1) ? lambda { values.shift } : @return_value = values.first
       self
     end
   
@@ -174,7 +216,7 @@ module Mocha
     #   object.expects(:expected_method).raises(Exception, 'message')
     #   object.expected_method # => raises exception of class Exception and with message 'message'
     def raises(exception = RuntimeError, message = nil)
-      @return_value = lambda{ raise exception, message }
+      @return_value = message ? lambda { raise exception, message } : lambda { raise exception }
       self
     end
 
@@ -183,22 +225,33 @@ module Mocha
     def invoke
       @invoked += 1
       yield(*@parameters_to_yield) if yield? and block_given?
-      @return_value.is_a?(Proc) ? @return_value.call : @return_value
+      @return_value.__is_a__(Proc) ? @return_value.call : @return_value
     end
 
     def verify
       yield(self) if block_given?
       unless (@count === @invoked) then
-        failure = Test::Unit::AssertionFailedError.new("#{message}: expected calls: #{@count}, actual calls: #{@invoked}")
-        failure.set_backtrace(backtrace)
-        raise failure
+        error = ExpectationError.new(error_message(@count, @invoked))
+        error.set_backtrace(filtered_backtrace)
+        raise error
       end
     end
+    
+    def mocha_lib_directory
+      File.expand_path(File.join(File.dirname(__FILE__), "..")) + File::SEPARATOR
+    end
+    
+    def filtered_backtrace
+      backtrace.reject { |location| Regexp.new(mocha_lib_directory).match(File.expand_path(location)) }
+    end
   
-    def message
-      params = @parameters.is_a?(Array) ? @parameters : [@parameters.to_s]
-      params = PrettyParameters.new(params)
-      ":#{@method_name}(#{params.pretty})"
+    def method_signature
+      return "#{method_name}" if @parameters.__is_a__(AlwaysEqual)
+      "#{@method_name}(#{PrettyParameters.new(@parameters).pretty})"
+    end
+    
+    def error_message(expected_count, actual_count)
+      "#{@mock.mocha_inspect}.#{method_signature} - expected calls: #{expected_count}, actual calls: #{actual_count}"
     end
   
     # :startdoc:
@@ -217,20 +270,22 @@ module Mocha
 
   class MissingExpectation < Expectation
   
-    def initialize(method_name, mock, expectations = [])
-      super(method_name)
-      @mock, @expectations = mock, expectations
+    def initialize(mock, method_name)
+      super
       @invoked = true
     end
   
     def verify
-      msg = "Unexpected message #{message} sent to #{@mock.mocha_inspect}"
-      msg << "\nSimilar expectations #{similar_expectations.collect { |expectation| expectation.message }.join("\n") }" unless similar_expectations.empty?
-      raise Test::Unit::AssertionFailedError, msg if @invoked
+      msg = error_message(0, 1)
+      similar_expectations_list = similar_expectations.collect { |expectation| expectation.method_signature }.join("\n")
+      msg << "\nSimilar expectations:\n#{similar_expectations_list}" unless similar_expectations.empty?
+      error = ExpectationError.new(msg)
+      error.set_backtrace(filtered_backtrace)
+      raise error if @invoked
     end
   
     def similar_expectations
-      @expectations.select { |expectation| expectation.method_name == self.method_name }
+      @mock.expectations.select { |expectation| expectation.method_name == self.method_name }
     end
   
   end