hardmock 1.2.0 → 1.2.3

data/CHANGES

@@ -1,4 +1,29 @@
-Hardmock 1.0.3
+Hardmock 1.2.3
+
+Sat Apr 28 01:16:15 EDT 2007
+
+* Re-release of 1.2.2 (which was canceled)... tasks moved to lib/tasks
+
+Hardmock 1.2.2
+
+Sat Apr 28 00:41:30 EDT 2007
+
+* assert_error has been broken out into its own lib file
+* Gem package can now run all tests successfully
+* Internal code refactoring; a number of classes that were defined in hardmock.rb are now in their own files
+
+Hardmock 1.2.1
+
+Sat Apr 28 00:41:30 EDT 2007
+
+* (botched release, see 1.2.2)
+
+Hardmock 1.2.0
+
+* You can now use "expect" in place of "expects" if you must. 
+* "inspect" has been added to the list of methods NOT erased by MethodCleanout.
+
+Hardmock 1.1.0
 
 * "expects" replaces "expect" ("expect" now raises Hardmock::DeprecationError)
 * "verify_mocks" is now implicit in teardown, you needn't call it anymore

data/README

@@ -7,7 +7,7 @@ Strict, ordered mock objects using very lightweight syntax in your tests.
 
 The basic procedure for using Hardmock in your tests is:
 
-* require 'hardmock'
+* require 'hardmock' (this happens automatically when being used as a Rails plugin)
 * Create some mocks
 * Setup some expectations
 * Execute the target code

data/Rakefile

@@ -1,94 +1,8 @@
 require 'rake'
-require 'rake/testtask'
-require 'rake/rdoctask'
 require 'rubygems'
-require 'rake/gempackagetask'
-require 'rake/contrib/sshpublisher'
-require 'hoe'
 
-HARDMOCK_VERSION = "1.2.0"
+HARDMOCK_VERSION = "1.2.3"
 
-task :default => [ :alltests ]
+Dir["lib/tasks/*.rake"].each { |f| load f }
 
-desc "Run all the tests"
-Rake::TestTask.new("alltests") { |t|
-  t.libs << "test"
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
-}
-
-def add_rdoc_options(options)
-  options << '--line-numbers' << '--inline-source' << '--main' << 'README' << '--title' << 'Hardmock'
-end
-
-desc "Generate RDoc documentation"
-Rake::RDocTask.new { |rdoc|
-  rdoc.rdoc_dir = 'doc'
-  rdoc.title    = "Hardmock: Strict expectation-based mock object library " 
-#  rdoc.options << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object' << '--main' 
-  add_rdoc_options(rdoc.options)
-  rdoc.rdoc_files.include('lib/**/*.rb', 'README','CHANGES','LICENSE')
-}
-
-task :showdoc => [ :rerdoc ] do
-  sh "open doc/index.html"
-end
-
-desc "Generate and upload api docs to rubyforge"
-task :upload_doc => :rerdoc do
-  sh "scp -r doc/* rubyforge.org:/var/www/gforge-projects/hardmock/doc"
-  sh "scp -r homepage/* rubyforge.org:/var/www/gforge-projects/hardmock/"
-end
-
-
-
-gem_spec = Gem::Specification.new do | s |
-  s.name = "hardmock"
-  s.version = HARDMOCK_VERSION
-  s.author = "David Crosby"
-  s.email = "crosby@atomicobject.com"
-  s.platform = Gem::Platform::RUBY
-  s.summary = "A strict, ordered, expectation-oriented mock object library."
-  s.rubyforge_project = 'hardmock'
-  s.homepage = "http://hardmock.rubyforge.org"
-  s.autorequire =  'hardmock'
-
-  s.files = FileList['{lib,test}/**/*.rb', '[A-Z]*'].exclude('TODO').to_a
-
-  s.require_path = "lib"
-  s.test_files = Dir.glob("test/**/*test.rb")
-
-  s.has_rdoc = true
-  s.extra_rdoc_files = ["README","CHANGES","LICENSE"]
-  add_rdoc_options(s.rdoc_options)
-end
-
-Rake::GemPackageTask.new(gem_spec) do |pkg|
-  pkg.need_zip = true
-  pkg.need_tar = true
-end
-
-task :verify_svn_clean do
-	# Get clean
-	sh 'svn up'
-	status = `svn status` 
-	raise "Please get checked-in and cleaned up before releasing.\n#{status}" unless status == ""
-end
-
-desc "Create a release tar.gz file."
-task :release => [:verify_svn_clean, :alltests, :upload_doc, :repackage] do
-  require 'fileutils'
-  include FileUtils::Verbose
-  proj_root = File.expand_path(File.dirname(__FILE__))
-  begin 
-    cd proj_root
-
-
-    # Tag the release by number, then re-tag for stable release (makes nicey nicey for Rails plugin installation)
-    sh "svn cp . svn+ssh://dcrosby42@rubyforge.org/var/svn/hardmock/tags/rel-#{HARDMOCK_VERSION} -m 'Releasing version #{HARDMOCK_VERSION}'"
-    sh "svn del svn+ssh://dcrosby42@rubyforge.org/var/svn/hardmock/tags/hardmock -m 'Preparing to update stable release tag'"
-    sh "svn cp . svn+ssh://dcrosby42@rubyforge.org/var/svn/hardmock/tags/hardmock -m 'Updating stable tag to version #{HARDMOCK_VERSION}'"
- 
-    puts "UPLOAD #{Dir['pkg/*.*']} TO RUBYFORGE RELEASE ZONE"
-  end
-end
+task :default => [ 'test:all' ]

data/config/environment.rb

@@ -0,0 +1,12 @@
+# The path to the root directory of your application.
+APP_ROOT = File.join(File.dirname(__FILE__), '..')
+
+ADDITIONAL_LOAD_PATHS = []
+ADDITIONAL_LOAD_PATHS.concat %w(
+  lib 
+).map { |dir| "#{APP_ROOT}/#{dir}" }.select { |dir| File.directory?(dir) }
+
+# Prepend to $LOAD_PATH
+ADDITIONAL_LOAD_PATHS.reverse.each { |dir| $:.unshift(dir) if File.directory?(dir) }
+
+# Require any additional libraries needed

data/lib/assert_error.rb

@@ -0,0 +1,21 @@
+require 'test/unit/assertions'
+
+module Test::Unit::Assertions
+  # A better 'assert_raise'.  +patterns+ can be one or more Regexps, or a literal String that 
+  # must match the entire error message.
+  def assert_error(err_type,*patterns,&block)
+    assert_not_nil block, "assert_error requires a block"
+    assert((err_type and err_type.kind_of?(Class)), "First argument to assert_error has to be an error type")
+    err = assert_raise(err_type) do
+      block.call
+    end
+    patterns.each do |pattern|
+      case pattern
+      when Regexp
+        assert_match(pattern, err.message) 
+      else
+        assert_equal pattern, err.message
+      end
+    end
+  end
+end

data/lib/hardmock/errors.rb

@@ -0,0 +1,16 @@
+module Hardmock
+  # Raised when:
+  # * Unexpected method is called on a mock object
+  # * Bad arguments passed to an expected call
+  class ExpectationError < StandardError; end
+
+  # Raised for methods that should no longer be called.  Hopefully, the exception message contains helpful alternatives.
+  class DeprecationError < StandardError; end
+
+  # Raised when it is discovered that an expected method call was never made.
+  class VerifyError < StandardError
+    def initialize(msg,unmet_expectations)
+      super("#{msg}:" + unmet_expectations.map { |ex| "\n * #{ex.to_s}" }.join)
+    end
+  end
+end

data/lib/hardmock/expectation.rb

@@ -0,0 +1,220 @@
+require 'hardmock/utils'
+
+module Hardmock
+  class Expectation
+    include Utils
+    attr_reader :block_value
+
+    def initialize(options) #:nodoc:
+      @options = options
+    end
+
+    def apply_method_call(mock,mname,args,block) #:nodoc:
+      unless @options[:mock].equal?(mock)
+        raise anger("Wrong object", mock,mname,args)
+      end
+      unless @options[:method] == mname
+        raise anger("Wrong method",mock,mname,args)
+      end
+
+      # Tester-defined block to invoke at method-call-time:
+      expectation_block = @options[:block]
+
+      expected_args = @options[:arguments]
+      # if we have a block, we can skip the argument check if none were specified
+      unless (expected_args.nil? || expected_args.empty?) && expectation_block && !@options[:suppress_arguments_to_block]
+        unless expected_args == args
+          raise anger("Wrong arguments",mock,mname,args)
+        end
+      end
+
+      relayed_args = args.dup
+      if block
+        if expectation_block.nil?
+          # Can't handle a runtime block without an expectation block
+          raise ExpectationError.new("Unexpected block provided to #{to_s}")
+        else
+          # Runtime blocks are passed as final argument to the expectation block
+          unless @options[:suppress_arguments_to_block]
+            relayed_args << block
+          else
+            # Arguments suppressed; send only the block
+            relayed_args = [block]
+          end
+        end
+      end
+
+      # Run the expectation block:
+      @block_value = expectation_block.call(*relayed_args) if expectation_block
+
+      raise @options[:raises] unless @options[:raises].nil?
+			
+			return_value = @options[:returns]
+			if return_value.nil?
+				return @block_value
+			else
+				return return_value
+			end
+    end
+
+    # Set the return value for an expected method call.
+    # Eg,
+    #   @cash_machine.expects.withdraw(20,:dollars).returns(20.00)
+    def returns(val)
+      @options[:returns] = val
+      self
+    end
+
+    # Rig an expected method to raise an exception when the mock is invoked.
+    #
+    # Eg,
+    #   @cash_machine.expects.withdraw(20,:dollars).raises "Insufficient funds"
+    #
+    # The argument can be:
+    # * an Exception -- will be used directly
+    # * a String -- will be used as the message for a RuntimeError
+    # * nothing -- RuntimeError.new("An Error") will be raised
+    def raises(err=nil)
+      case err
+      when Exception
+        @options[:raises] = err
+      when String
+        @options[:raises] = RuntimeError.new(err)
+      else
+        @options[:raises] = RuntimeError.new("An Error")
+      end
+      self
+    end
+
+    # Convenience method: assumes +block_value+ is set, and is set to a Proc
+    # (or anything that responds to 'call')
+    #
+    #   light_event = @traffic_light.trap.subscribe(:light_changes)
+    #
+    #   # This code will meet the expectation:
+    #   @traffic_light.subscribe :light_changes do |color|
+    #     puts color
+    #   end
+    #
+    # The color-handling block is now stored in <tt>light_event.block_value</tt>
+    #
+    # The block can be invoked like this:
+    #
+    #   light_event.trigger :red
+    # 
+    # See Mock#trap and Mock#expects for information on using expectation objects 
+    # after they are set.
+    #
+    def trigger(*block_arguments)
+      unless block_value
+        raise ExpectationError.new("No block value is currently set for expectation #{to_s}")
+      end
+      unless block_value.respond_to?(:call)
+        raise ExpectationError.new("Can't apply trigger to #{block_value} for expectation #{to_s}")
+      end
+      block_value.call *block_arguments
+    end
+
+    # Used when an expected method accepts a block at runtime.  
+    # When the expected method is invoked, the block passed to
+    # that method will be invoked as well.
+    #
+    # NOTE: ExpectationError will be thrown upon running the expected method
+    # if the arguments you set up in +yields+ do not properly match up with
+    # the actual block that ends up getting passed.
+    # 
+    # == Examples
+    # <b>Single invocation</b>: The block passed to +lock_down+ gets invoked
+    # once with no arguments:
+    #
+    #   @safe_zone.expects.lock_down.yields
+    #
+    #   # (works on code that looks like:)
+    #   @safe_zone.lock_down do 
+    #     # ... this block invoked once
+    #   end
+    # 
+    # <b>Multi-parameter blocks:</b> The block passed to +each_item+ gets
+    # invoked twice, with <tt>:item1</tt> the first time, and with
+    # <tt>:item2</tt> the second time:
+    # 
+    #   @fruit_basket.expects.each_with_index.yields [:apple,1], [:orange,2]
+    #
+    #   # (works on code that looks like:)
+    #   @fruit_basket.each_with_index do |fruit,index|
+    #     # ... this block invoked with fruit=:apple, index=1, 
+    #     # ... and then with fruit=:orange, index=2
+    #   end
+    #
+    # <b>Arrays can be passed as arguments too</b>... if the block 
+    # takes a single argument and you want to pass a series of arrays into it,
+    # that will work as well:
+    #
+    #   @list_provider.expects.each_list.yields [1,2,3], [4,5,6]
+    #
+    #   # (works on code that looks like:)
+    #   @list_provider.each_list do |list|
+    #     # ... list is [1,2,3] the first time
+    #     # ... list is [4,5,6] the second time
+    #   end
+    #
+    # <b>Return value</b>: You can set the return value for the method that
+    # accepts the block like so: 
+    #
+    #   @cruncher.expects.do_things.yields(:bean1,:bean2).returns("The Results")
+    #
+    # <b>Raising errors</b>: You can set the raised exception for the method that
+    # accepts the block. NOTE: the error will be raised _after_ the block has
+    # been invoked.
+    #
+    #   # :bean1 and :bean2 will be passed to the block, then an error is raised:
+    #   @cruncher.expects.do_things.yields(:bean1,:bean2).raises("Too crunchy")
+    #
+    def yields(*items)
+      @options[:suppress_arguments_to_block] = true
+      if items.empty?
+        # Yield once
+        @options[:block] = lambda do |block|
+          if block.arity != 0 and block.arity != -1
+            raise ExpectationError.new("Can't pass #{item.inspect} to block with arity #{block.arity} to <#{to_s}>")
+          end
+          block.call
+        end
+      else
+        # Yield one or more specific items
+        @options[:block] = lambda do |block|
+          items.each do |item|
+            if item.kind_of?(Array) 
+              if block.arity == item.size
+                # Unfold the array into the block's arguments:
+                block.call *item
+              elsif block.arity == 1
+                # Just pass the array in
+                block.call item
+              else
+                # Size mismatch
+                raise ExpectationError.new("Can't pass #{item.inspect} to block with arity #{block.arity} to <#{to_s}>")
+              end
+            else
+              if block.arity != 1
+                # Size mismatch
+                raise ExpectationError.new("Can't pass #{item.inspect} to block with arity #{block.arity} to <#{to_s}>")
+              end
+              block.call item
+            end
+          end
+        end
+      end
+      self
+    end
+
+    def to_s # :nodoc:
+      format_method_call_string(@options[:mock],@options[:method],@options[:arguments])
+    end
+
+    private 
+    def anger(msg, mock,mname,args)
+      ExpectationError.new("#{msg}: expected call <#{to_s}> but was <#{format_method_call_string(mock,mname,args)}>")
+    end
+  end
+end

data/lib/hardmock/expectation_builder.rb

@@ -0,0 +1,9 @@
+require 'hardmock/expectation'
+
+module Hardmock
+  class ExpectationBuilder #:nodoc:
+    def build_expectation(options)
+      Expectation.new(options)
+    end
+  end
+end

data/lib/hardmock/expector.rb

@@ -0,0 +1,26 @@
+require 'hardmock/method_cleanout'
+require 'hardmock/errors'
+
+module Hardmock
+  class Expector #:nodoc:
+    include MethodCleanout
+
+    def initialize(mock,mock_control,expectation_builder)
+      @mock = mock
+      @mock_control = mock_control
+      @expectation_builder = expectation_builder
+    end
+
+    def method_missing(mname, *args, &block)
+      expectation = @expectation_builder.build_expectation(
+        :mock => @mock, 
+        :method => mname, 
+        :arguments => args, 
+        :block => block)
+
+      @mock_control.add_expectation expectation
+      expectation
+    end
+  end
+
+end

data/lib/{method_cleanout.rb → hardmock/method_cleanout.rb}

@@ -1,7 +1,7 @@
 
 module Hardmock #:nodoc:
   module MethodCleanout #:nodoc:
-    SACRED_METHODS = %w|__id__ __send__ equal? object_id send nil? class kind_of? respond_to? inspect|
+    SACRED_METHODS = %w|__id__ __send__ equal? object_id send nil? class kind_of? respond_to? inspect method to_s instance_variables instance_eval ==|
 
     def self.included(base) #:nodoc:
       base.class_eval do

data/lib/hardmock/mock.rb

@@ -0,0 +1,182 @@
+
+module Hardmock
+  # Mock is used to set expectations in your test.  Most of the time you'll use
+  # <tt>#expects</tt> to create expectations.
+  #
+  # Aside from the scant few control methods (like +expects+, +trap+ and +_verify+) 
+  # all calls made on a Mock instance will be immediately applied to the internal
+  # expectation mechanism.
+  #
+  # * If the method call was expected and all the parameters match properly, execution continues
+  # * If the expectation was configured with an expectation block, the block is invoked
+  # * If the expectation was set up to raise an error, the error is raised now
+  # * If the expectation was set up to return a value, it is returned
+  # * If the method call was _not_ expected, or the parameter values are wrong, an ExpectationError is raised.
+  class Mock
+    include Hardmock::MethodCleanout
+
+    # Create a new Mock instance with a name and a MockControl to support it.
+    # If not given, a MockControl is made implicitly for this Mock alone; this means
+    # expectations for this mock are not tied to other expectations in your test.
+    #
+    # It's not recommended to use a Mock directly; see Hardmock and
+    # Hardmock#create_mocks for the more wholistic approach.
+    def initialize(name, mock_control=nil)
+      @name = name
+      @control = mock_control || MockControl.new
+      @expectation_builder = ExpectationBuilder.new
+    end
+
+    def inspect
+      "<Mock #{@name}>"
+    end
+
+    # Begin declaring an expectation for this Mock.
+    #
+    # == Simple Examples
+    # Expect the +customer+ to be queried for +account+, and return <tt>"The
+    # Account"</tt>: 
+    #   @customer.expects.account.returns "The Account"
+    #
+    # Expect the +withdraw+ method to be called, and raise an exception when it
+    # is (see Expectation#raises for more info):
+    #   @cash_machine.expects.withdraw(20,:dollars).raises("not enough money")
+    #
+    # Expect +customer+ to have its +user_name+ set
+    #   @customer.expects.user_name = 'Big Boss'
+    #   
+    # Expect +customer+ to have its +user_name+ set, and raise a RuntimeException when
+    # that happens:
+    #   @customer.expects('user_name=', "Big Boss").raises "lost connection"
+    #
+    # Expect +evaluate+ to be passed a block, and when that happens, pass a value
+    # to the block (see Expectation#yields for more info):
+    #   @cruncher.expects.evaluate.yields("some data").returns("some results")
+    #
+    #
+    # == Expectation Blocks
+    # To do special handling of expected method calls when they occur, you
+    # may pass a block to your expectation, like:
+    #   @page_scraper.expects.handle_content do |address,request,status|
+    #     assert_not_nil address, "Can't abide nil addresses"
+    #     assert_equal "http-get", request.method, "Can only handle GET"
+    #     assert status > 200 and status < 300, status, "Failed status"
+    #     "Simulated results #{request.content.downcase}"
+    #   end
+    # In this example, when <tt>page_scraper.handle_content</tt> is called, its
+    # three arguments are passed to the <i>expectation block</i> and evaluated
+    # using the above assertions.  The last value in the block will be used 
+    # as the return value for +handle_content+
+    #
+    # You may specify arguments to the expected method call, just like any normal
+    # expectation, and those arguments will be pre-validated before being passed
+    # to the expectation block.  This is useful when you know all of the
+    # expected values but still need to do something programmatic.
+    #
+    # If the method being invoked on the mock accepts a block, that block will be
+    # passed to your expectation block as the last (or only) argument.  Eg, the 
+    # convenience method +yields+ can be replaced with the more explicit:
+    #   @cruncher.expects.evaluate do |block|
+    #     block.call "some data"
+    #     "some results"
+    #   end
+    #
+    # The result value of the expectation block becomes the return value for the
+    # expected method call. This can be overidden by using the +returns+ method:
+    #   @cruncher.expects.evaluate do |block|
+    #     block.call "some data"
+    #     "some results"
+    #   end.returns("the actual value")
+    # 
+    # <b>Additionally</b>, the resulting value of the expectation block is stored
+    # in the +block_value+ field on the expectation.  If you've saved a reference 
+    # to your expectation, you may retrieve the block value once the expectation
+    # has been met.
+    #
+    #   evaluation_event = @cruncher.expects.evaluate do |block|
+    #     block.call "some data"
+    #     "some results"
+    #   end.returns("the actual value")
+    #
+    #   result = @cruncher.evaluate do |input|
+    #     puts input  # => 'some data'
+    #   end
+    #   # result is 'the actual value'
+    #   
+    #   evaluation_event.block_value # => 'some results'
+    #
+    def expects(*args, &block)
+      expector = Expector.new(self,@control,@expectation_builder)
+      # If there are no args, we return the Expector
+      return expector if args.empty?
+      # If there ARE args, we set up the expectation right here and return it
+      expector.send(args.shift.to_sym, *args, &block)
+    end
+    alias_method :expect, :expects
+#    def expect(*args, &block) #:nodoc:
+#      raise DeprecationError.new("Please use 'expects' instead of 'expect'.  Sorry about the inconvenience.")
+#    end
+
+    # Special-case convenience: #trap sets up an expectation for a method
+    # that will take a block.  That block, when sent to the expected method, will
+    # be trapped and stored in the expectation's +block_value+ field.
+    # The Expectation#trigger method may then be used to invoke that block.
+    #
+    # Like +expects+, the +trap+ mechanism can be followed by +raises+ or +returns+.
+    #
+    # _Unlike_ +expects+, you may not use an expectation block with +trap+.  If 
+    # the expected method takes arguments in addition to the block, they must
+    # be specified in the arguments to the +trap+ call itself.
+    #
+    # == Example
+    # 
+    #   create_mocks :address_book, :editor_form
+    #
+    #   # Expect a subscription on the :person_added event for @address_book:
+    #   person_event = @address_book.trap.subscribe(:person_added)
+    #
+    #   # The runtime code would look like:
+    #   @address_book.subscribe :person_added do |person_name|
+    #     @editor_form.name = person_name
+    #   end
+    #
+    #   # At this point, the expectation for 'subscribe' is met and the 
+    #   # block has been captured.  But we're not done:
+    #   @editor_form.expects.name = "David"
+    #
+    #   # Now invoke the block we trapped earlier:
+    #    person_event.trigger "David"
+    #
+    #   verify_mocks
+    def trap(*args)
+      Trapper.new(self,@control,ExpectationBuilder.new)
+    end
+
+    def method_missing(mname,*args) #:nodoc:
+      block = nil
+      block = Proc.new if block_given?
+      @control.apply_method_call(self,mname,args,block)
+    end
+
+
+    def _control #:nodoc:
+      @control
+    end
+
+    def _name #:nodoc:
+      @name
+    end
+
+    # Verify that all expectations are fulfilled.  NOTE: this method triggers
+    # validation on the _control_ for this mock, so all Mocks that share the
+    # MockControl with this instance will be included in the verification.
+    #
+    # <b>Only use this method if you are managing your own Mocks and their controls.</b>
+    #
+    # Normal usage of Hardmock doesn't require you to call this; let
+    # Hardmock#verify_mocks do it for you.
+    def _verify
+      @control.verify
+    end
+  end
+end

data/lib/hardmock/mock_control.rb

@@ -0,0 +1,45 @@
+require 'hardmock/utils'
+
+module Hardmock
+  class MockControl #:nodoc:
+    include Utils
+    attr_accessor :name
+
+    def initialize
+      @expectations = []
+      @disappointed = false
+    end
+
+    def happy?
+      @expectations.empty?
+    end
+
+    def disappointed?
+      @disappointed
+    end
+
+    def add_expectation(expectation)
+      @expectations << expectation
+    end
+
+    def apply_method_call(mock,mname,args,block)
+      # Are we even expecting any sort of call?
+      if happy?
+        @disappointed = true
+        raise ExpectationError.new("Surprise call to #{format_method_call_string(mock,mname,args)}")
+      end
+
+      begin
+        @expectations.shift.apply_method_call(mock,mname,args,block)
+      rescue Exception => ouch
+        @disappointed = true
+        raise ouch
+      end
+    end
+
+    def verify
+      @disappointed = !happy?
+      raise VerifyError.new("Unmet expectations", @expectations) unless happy?
+    end
+  end
+end