mocha 0.3.1 → 0.3.2

data/README

@@ -1,164 +1,35 @@
 = Mocha
 
-Mocha is a library for mocking and stubbing within tests 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 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 comes in four parts:
+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].
 
-1. Mocha - traditional mock objects with expectations and verification
-2. Stubba - allows mocking and stubbing of methods on real (non-mock) classes
-3. AutoMocha - magically provides mocks in the place of undefined classes
-4. SmartTestCase - allows addition of multiple setup and teardown methods for a Test::Unit::TestCase
+Mocha provides a unified, simple and readable syntax for both traditional mocking and for mocking with non-mock objects.
 
-Stubba and AutoMocha are the main difference between this mocking library and others like FlexMock[http://onestepback.org/software/flexmock] and RSpec[http://rspec.rubyforge.org].
-
-== Provenance
-
-Mocha and Stubba have been created by amalgamating a number of techniques developed by me (James[http:blog.floehopper.org]) and my Reevoo[http://www.reevoo.com] colleagues (Ben[http://www.reevoo.com/blogs/bengriffiths/], Chris[http://blog.seagul.co.uk] and Paul[http://po-ru.com]) into a common syntax. They are both in use on real-world Rails[http://www.rubyonrails.org] projects. AutoMocha is more experimental and is at an earlier stage of development. SmartTestCase has been exrtacted from Mocha and Stubba to remove duplication and allow its use in isolation.
+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
 
-You can download Mocha from here[http://rubyforge.org/projects/mocha] or install it with the following command.
+Install the gem with the following command...
 
- $ gem install mocha
+  $ gem install mocha
  
-== Ruby on Rails plugin
+Or install the Rails[http://www.rubyonrails.org] plugin...
 
   $ script/plugin install svn://rubyforge.org/var/svn/mocha/trunk
 
-== License
-
-Copyright Revieworld Ltd. 2006
- 	
-You may use, copy and redistribute this library under the same terms as Ruby itself (see http://www.ruby-lang.org/en/LICENSE.txt) or under the MIT license (see http://mocha.rubyforge.org/files/MIT-LICENSE.html).
+Or download Mocha from here - http://rubyforge.org/projects/mocha
 
 == Examples
 
-See MochaAcceptanceTest, StubbaAcceptanceTest, AutoMochaAcceptanceTest and unit tests for more examples.
-
-=== Mocha Example
-
-  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
-
-=== Stubba Example
-
-  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
+* Quick Start - {Usage Examples}[link:examples/misc.html]
+* Traditional mocking - {Star Trek Example}[link:examples/mocha.html]
+* Setting expectations on real classes - {Order Example}[link:examples/stubba.html]
+* More examples on {Floehopper's Blog}[http://blog.floehopper.org]
+* {Mailing List Archives}[http://rubyforge.org/pipermail/mocha-developer/]
 
-      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
-
-=== AutoMocha Example
-  
-  class Article
-  
-    attr_reader :id
-
-    def accepted_comments
-      Comment.find_all_by_article_id(self.id).select { |comment| comment.accepted? }
-    end
-
-  end
-
-  require 'rubygems'
-  require 'auto_mocha'
-  require 'test/unit'
-
-  class OrderTest < Test::Unit::TestCase
-
-    # illustrates stubbing of previously undefined class Comment
-    def test_should_return_accepted_comments_for_this_article
-      unaccepted_comment = stub(:accepted? => false)
-      accepted_comment = stub(:accepted? => true)
-      comments = [unaccepted_comment, accepted_comment]
-      Comment.stubs(:find_all_by_article_id).returns(comments)
-      article = Article.new
-      assert_equal [accepted_comment], article.accepted_comments
-    end
-
-  end
+== License
 
+Copyright Revieworld Ltd. 2006
+ 	
+You may use, copy and redistribute this library under the same terms as {Ruby itself}[http://www.ruby-lang.org/en/LICENSE.txt] or under the {MIT license}[http://mocha.rubyforge.org/files/MIT-LICENSE.html].

data/Rakefile

@@ -3,6 +3,10 @@ require 'rake/rdoctask'
 require 'rake/gempackagetask'
 require 'rake/contrib/sshpublisher'
 
+module Mocha
+  VERSION = "0.3.2"
+end
+
 desc "Default task is currently to run all tests"
 task :default => :test_all
 
@@ -17,12 +21,14 @@ Rake::RDocTask.new do |task|
   task.main = 'README'
   task.title = 'Mocha'
   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/**/*.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/stubba/object.rb')
 end
+task :rdoc => :examples
 
 desc "Upload RDoc to RubyForge"
-task :publish_rdoc => [:rdoc] do
+task :publish_rdoc => [:rdoc, :examples] do
   Rake::SshDirPublisher.new("jamesmead@rubyforge.org", "/var/www/gforge-projects/mocha", "doc").upload
 end
 
@@ -42,16 +48,36 @@ file 'agiledox.txt' do
   end
 end
 
+desc "Convert example ruby files to syntax-highlighted html"
+task :examples do
+  require 'coderay'
+  mkdir_p 'doc/examples'
+  File.open('doc/examples/coderay.css', 'w') do |output|
+    output << CodeRay::Encoders[:html]::CSS.new.stylesheet
+  end
+  ['mocha', 'stubba', 'misc'].each do |filename|
+    File.open("doc/examples/#{filename}.html", 'w') do |file|
+      file << "<html>"
+      file << "<head>"
+      file << %q(<link rel="stylesheet" media="screen" href="coderay.css" type="text/css">)
+      file << "</head>"
+      file << "<body>"
+      file << CodeRay.scan_file("examples/#{filename}.rb").html.div
+      file << "</body>"
+      file << "</html>"
+    end
+  end
+end
+
 Gem::manage_gems
 
 specification = Gem::Specification.new do |s|
 	s.name   = "mocha"
   s.summary = "Mocking and stubbing library"
-	s.version = "0.3.1"
+	s.version = Mocha::VERSION
 	s.author = 'James Mead'
 	s.description = <<-EOF
     Mocking and stubbing library with JMock/SchMock syntax, which allows mocking and stubbing of methods on real (non-mock) classes.
-    Includes auto-mocking which magically provides mocks for undefined classes, facilitating unit tests with no external dependencies.
   EOF
 	s.email = 'mocha-developer@rubyforge.org'
   s.homepage = 'http://mocha.rubyforge.org'
@@ -62,11 +88,39 @@ 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]*'].to_a
+  s.files = FileList['{lib,test}/**/*.rb', '[A-Z]*'].exclude('TODO').to_a
 	s.test_file = "test/all_tests.rb"
 end
 
 Rake::GemPackageTask.new(specification) do |package|
 	 package.need_zip = true
 	 package.need_tar = true
-end
+end
+
+task :verify_user do
+  raise "RUBYFORGE_USER environment variable not set!" unless ENV['RUBYFORGE_USER']
+end
+
+task :verify_password do
+  raise "RUBYFORGE_PASSWORD environment variable not set!" unless ENV['RUBYFORGE_PASSWORD']
+end
+
+desc "Publish package files on RubyForge."
+task :publish_packages => [:verify_user, :verify_password, :package] do
+  require 'meta_project'
+  require 'rake/contrib/xforge'
+  release_files = FileList[
+    "pkg/mocha-#{Mocha::VERSION}.gem",
+    "pkg/mocha-#{Mocha::VERSION}.tgz",
+    "pkg/mocha-#{Mocha::VERSION}.zip"
+  ]
+
+  Rake::XForge::Release.new(MetaProject::Project::XForge::RubyForge.new('mocha')) do |release|
+    release.user_name = ENV['RUBYFORGE_USER']
+    release.password = ENV['RUBYFORGE_PASSWORD']
+    release.files = release_files.to_a
+    release.release_name = "Mocha #{Mocha::VERSION}"
+    release.release_changes = ''
+    release.release_notes = ''
+  end
+end

data/lib/mocha.rb

@@ -3,5 +3,5 @@ require 'mocha/auto_verify'
 require 'shared/backtracefilter'
 
 class Test::Unit::TestCase
-  include AutoVerify unless ancestors.include?(AutoVerify)
+  include Mocha::AutoVerify unless ancestors.include?(Mocha::AutoVerify)
 end

data/lib/mocha/auto_verify.rb

@@ -1,46 +1,113 @@
 require 'mocha/mock'
 
-module AutoVerify
+# Methods added to TestCase allowing creation of mock objects.
+#
+# Mocks created this way will have their expectations automatically verified at the end of the test.
+#
+# See Mocha::MockMethods for methods on mock objects.
+module Mocha
+  module AutoVerify
   
-  def self.included(base)
-    base.add_teardown_method(:teardown_mocks)
-  end
+    def self.included(base) # :nodoc:
+      base.add_teardown_method(:teardown_mocks)
+    end
 
-  def mocks
-    @mocks ||= []
-  end
+    def mocks # :nodoc:
+      @mocks ||= []
+    end
   
-  def reset_mocks
-    @mocks = nil
-  end
-
-  def mock(expectations = {})
-    build_mock_with_expectations(:expects, expectations)
-  end
+    def reset_mocks # :nodoc:
+      @mocks = nil
+    end
   
-  def stub(expectations = {})
-    build_mock_with_expectations(:stubs, expectations)
-  end
+    # :call-seq: mock(name) -> mock object
+    #            mock(expected_methods = {}) -> mock object
+    #            mock(name, expected_methods = {}) -> mock object
+    #
+    # Creates a mock object.
+    #
+    # +name+ is a +String+ identifier for the mock object.
+    #
+    # +expected_methods+ is a +Hash+ with expected method name symbols as keys and corresponding return values as values.
+    #
+    # Note that (contrary to expectations set up by #stub) these expectations <b>must</b> be fulfilled during the test.
+    #   def test_product
+    #     product = mock('ipod_product', :manufacturer => 'ipod', :price => 100)
+    #     assert_equal 'ipod', product.manufacturer
+    #     assert_equal 100, product.price
+    #     # an error will be raised unless both Product#manufacturer and Product#price have been called
+    #   end 
+    def mock(*args)
+      name, expectations = name_and_expectations_from_args(args)
+      build_mock_with_expectations(:expects, expectations, name)
+    end
   
-  def stub_everything(expectations = {})
-    build_mock_with_expectations(:stub_everything, expectations)
-  end
+    # :call-seq: stub(name) -> mock object
+    #            stub(stubbed_methods = {}) -> mock object
+    #            stub(name, stubbed_methods = {}) -> mock object
+    #
+    # Creates a mock object.
+    #
+    # +name+ is a +String+ identifier for the mock object.
+    #
+    # +stubbed_methods+ is a +Hash+ with stubbed method name symbols as keys and corresponding return values as values.
+    #
+    # Note that (contrary to expectations set up by #mock) these expectations <b>need not</b> be fulfilled during the test.
+    #   def test_product
+    #     product = stub('ipod_product', :manufacturer => 'ipod', :price => 100)
+    #     assert_equal 'ipod', product.manufacturer
+    #     assert_equal 100, product.price
+    #     # an error will not be raised even if Product#manufacturer and Product#price have not been called
+    #   end
+    def stub(*args)
+      name, expectations = name_and_expectations_from_args(args)
+      build_mock_with_expectations(:stubs, expectations, name)
+    end
+  
+    # :call-seq: stub_everything(name) -> mock object
+    #            stub_everything(stubbed_methods = {}) -> mock object
+    #            stub_everything(name, stubbed_methods = {}) -> mock object
+    #
+    # Creates a mock object that accepts calls to any method.
+    #
+    # By default it will return +nil+ for any method call.
+    #
+    # +name+ and +stubbed_methods+ work in the same way as for #stub.
+    #   def test_product
+    #     product = stub_everything('ipod_product', :price => 100)
+    #     assert_nil product.manufacturer
+    #     assert_nil product.any_old_method
+    #     assert_equal 100, product.price
+    #   end
+    def stub_everything(*args)
+      name, expectations = name_and_expectations_from_args(args)
+      build_mock_with_expectations(:stub_everything, expectations, name)
+    end
 
-  def teardown_mocks
-    mocks.each { |mock| mock.verify { add_assertion } }
-    reset_mocks
-  end
+    def teardown_mocks # :nodoc:
+      mocks.each { |mock| mock.verify { add_assertion } }
+      reset_mocks
+    end
   
-  def build_mock_with_expectations(expectation_type = :expects, expectations = {})
-    stub_everything = (expectation_type == :stub_everything)
-    expectation_type = :stubs if expectation_type == :stub_everything
-    mock = Mocha::Mock.new(stub_everything)
-    expectations.each do |method, result|
-      mock.send(expectation_type, method).returns(result)
+    def build_mock_with_expectations(expectation_type = :expects, expectations = {}, name = nil) # :nodoc:
+      stub_everything = (expectation_type == :stub_everything)
+      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)
+      end
+      mocks << mock
+      mock
+    end
+    
+  private
+
+    def name_and_expectations_from_args(args) # :nodoc:
+      name = args.first.is_a?(String) ? args.delete_at(0) : nil
+      expectations = args.first || {}
+      [name, expectations]
     end
-    mocks << mock
-    mock
+  
   end
   
-end
-
+end

data/lib/mocha/expectation.rb

@@ -2,8 +2,11 @@ require 'mocha/infinite_range'
 require 'mocha/pretty_parameters'
 
 module Mocha
+  # Methods on expectations returned from Mocha::MockMethods#expects and Mocha::MockMethods#stubs
   class Expectation
   
+    # :stopdoc:
+    
     class InvalidExpectation < Exception; end
     
     class AlwaysEqual
@@ -37,47 +40,146 @@ module Mocha
       end
     end
 
+    # :startdoc:
+    
+    # :call-seq: times(range) -> expectation
+    #
+    # Modifies expectation so that the number of calls to the expected method must be within a specific +range+.
+    #
+    # +range+ can be specified as an exact integer or as a range of integers
+    #   object = mock()
+    #   object.expects(:expected_method).times(3)
+    #   3.times { object.expected_method } # => verify succeeds
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).times(3)
+    #   2.times { object.expected_method } # => verify fails
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).times(2..4)
+    #   3.times { object.expected_method } # => verify succeeds
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).times(2..4)
+    #   object.expected_method # => verify fails
     def times(range)
       @count = range
       self
     end
   
+    # :call-seq: never -> expectation
+    #
+    # Modifies expectation so that the expected method must never be called.
+    #   object = mock()
+    #   object.expects(:expected_method).never
+    #   object.expected_method # => verify fails
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).never
+    #   object.expected_method # => verify succeeds
     def never
       times(0)
     end
   
+    # :call-seq: at_least(minimum) -> expectation
+    #
+    # 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
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).at_least(2)
+    #   object.expected_method # => verify fails
     def at_least(minimum)
       times(Range.at_least(minimum))
       self
     end
   
+    # :call-seq: at_least_once() -> expectation
+    #
+    # Modifies expectation so that the expected method must be called at least once.
+    #   object = mock()
+    #   object.expects(:expected_method).at_least_once
+    #   object.expected_method # => verify succeeds
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).at_least_once
+    #   # => verify fails
     def at_least_once()
       at_least(1)
       self
     end
   
+    # :call-seq: with(*arguments, &parameter_block) -> expectation
+    #
+    # Modifies expectation so that the expected method must be called with specified +arguments+.
+    #   object = mock()
+    #   object.expects(:expected_method).with(:param1, :param2)
+    #   object.expected_method(:param1, :param2) # => verify succeeds
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).with(:param1, :param2)
+    #   object.expected_method(:param3) # => verify fails
+    # If a +parameter_block+ is given, the block is called with the parameters passed to the expected method.
+    # The expectation is matched if the block evaluates to +true+.
+    #   object = mock()
+    #   object.expects(:expected_method).with() { |value| value % 4 == 0 }
+    #   object.expected_method(16) # => verify succeeds
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).with() { |value| value % 4 == 0 }
+    #   object.expected_method(17) # => verify fails
     def with(*arguments, &parameter_block)
       @parameters, @parameter_block = arguments, parameter_block
       class << @parameters; def to_s; join(', '); end; end
       self
     end
   
+    # :call-seq: yields(*parameters) -> expectation
+    #
+    # Modifies expectation so that when the expected method is called, it yields with the specified +parameters+.
+    #   object = mock()
+    #   object.expects(:expected_method).yields('result')
+    #   yielded_value = nil
+    #   object.expected_method { |value| yielded_value = value }
+    #   yielded_value # => 'result'
     def yields(*parameters)
       @yield = true
       @parameters_to_yield = parameters
       self
     end
 
+    # :call-seq: returns(value) -> 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'
+    # 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
       self
     end
   
+    # :call-seq: raises(exception = RuntimeError, message = nil) -> expectation
+    #
+    # Modifies expectation so that when the expected method is called, it raises the specified +exception+ with the specified +message+.
+    #   object = mock()
+    #   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 }
       self
     end
 
+    # :stopdoc:
+    
     def invoke
       @invoked += 1
       yield(*@parameters_to_yield) if yield? and block_given?
@@ -99,8 +201,12 @@ module Mocha
       ":#{@method_name}(#{params.pretty})"
     end
   
+    # :startdoc:
+    
   end
 
+  # :stopdoc:
+  
   class Stub < Expectation
   
     def verify
@@ -111,14 +217,14 @@ module Mocha
 
   class MissingExpectation < Expectation
   
-    def initialize(method_name, expectations = [])
+    def initialize(method_name, mock, expectations = [])
       super(method_name)
-      @expectations = expectations
+      @mock, @expectations = mock, expectations
       @invoked = true
     end
   
     def verify
-      msg = "Unexpected message #{message}"
+      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
     end
@@ -128,4 +234,7 @@ module Mocha
     end
   
   end
+
+  # :startdoc:
+  
 end