flexmock 0.5.1 → 0.6.0

data/Rakefile

@@ -1,15 +1,25 @@
 # Rakefile for flexmock        -*- ruby -*-
 
+#---
+# Copyright 2003, 2004, 2005, 2006, 2007 by Jim Weirich (jim@weirichhouse.org).
+# All rights reserved.
+
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#+++
+
 require 'rubygems'
 require 'rake/gempackagetask'
 require 'rake/clean'
 require 'rake/rdoctask'
 require 'rake/testtask'
+require 'rake/contrib/rubyforgepublisher'
 
 CLEAN.include('*.tmp')
 CLOBBER.include("html", 'pkg')
 
-PKG_VERSION = '0.5.1'
+PKG_VERSION = '0.6.0'
 
 PKG_FILES = FileList[
   '[A-Z]*',
@@ -26,7 +36,6 @@ RDOC_FILES = FileList[
   'doc/**/*.rdoc',
 ]
 
-
 task :default => [:test_all]
 task :test_all => [:test]
 task :test_units => [:test]
@@ -43,7 +52,16 @@ end
 Rake::TestTask.new(:test_extended) do |t|
   t.test_files = FileList['test/extended/test_*.rb']
   t.verbose = true
-  t.verbose = true
+  t.warning = true
+end
+
+task :rspec do
+  ENV['RUBYLIB'] = "/Users/jim/working/svn/software/rspec/rspec/lib:/Users/jim/working/svn/software/flexmock/lib"
+  sh 'echo $RUBYLIB'
+  ruby "/Users/jim/working/svn/software/rspec/rspec/bin/spec test/rspec_integration/*_spec.rb" rescue nil
+  puts
+  puts "*** There should be two failures in the above report. ***"
+  puts
 end
 
 # RCov Target --------------------------------------------------------
@@ -142,18 +160,21 @@ task :rf => :rubyfiles
 require 'rake/contrib/publisher'
 require 'rake/contrib/sshpublisher'
 
-task :publish => [:rdoc] do
-  html_publisher = Rake::SshFreshDirPublisher.new(
+publisher = Rake::CompositePublisher.new
+publisher.add(Rake::RubyForgePublisher.new('flexmock', 'jimweirich'))
+publisher.add(Rake::SshFreshDirPublisher.new(
     'umlcoop',
     'htdocs/software/flexmock',
-    'html')
-  blurb_publisher = Rake::SshFilePublisher.new(
+    'html'))
+publisher.add(Rake::SshFilePublisher.new(
     'umlcoop',
     'htdocs/software/flexmock',
     '.',
-    'flexmock.blurb')
-  html_publisher.upload
-  blurb_publisher.upload
+    'flexmock.blurb'))
+
+desc "Publish the documentation on public websites"
+task :publish => [:rdoc] do
+  publisher.upload
 end
 
 SVNHOME = 'svn://localhost/software/flexmock'

data/doc/GoogleExample.rdoc

@@ -0,0 +1,275 @@
+= Extended FlexMock Example Using Google4R
+
+Google4R is a simple Ruby wrapper around the Google APIs.  In this extended example, we will use FlexMock to test software that uses the Google APIs, without every communicating with Google itself.
+
+== Purchase.rb
+
+Here is the bit of code that we will be testing...
+
+  require 'google4r/checkout'
+  require 'item'
+
+  class Purchase
+
+    def initialize(config)
+      @frontend = Frontend.new(config)
+      @frontend.tax_table_factory = TaxTableFactory.new
+    end
+
+    # Purchase the +quantity+ items identified by +item_id+.  Return the
+    # confirmation page URL.
+    def purchase(item_id, quantity=1)
+      item = Item.find(item_id)
+      checkout = @frontend.create_checkout_command
+      checkout.cart.create_item do |cart_item|
+        cart_item.name = item.name
+        cart_item.description = item.description
+        cart_item.unit_price = item.unit_price
+        cart_item.quantity = quantity
+      end
+      response = checkout.send_to_google_checkout
+      response.redirect_url
+    end
+
+  end
+
++FrontEnd+ is a Google4R class that provides a lot of the front end work for
+talking to the Google APIs. The config object given to the Purchase
+initializer is simply a hash of values defining the merchant_id, merchant_key
+and sandbox flag. To use the real Google checkout APIs, you will need to
+obtains a merchant id and key from Google. Since we will be mocking the Google
+interaction, we can use dummy values in our test.  
+
+The tax table factory is required by the Google4R software.  We provide the following simplified one.  Read the Google API documents for more information.
+
+  class TestTaxTableFactory
+    def effective_tax_tables_at(time)
+      tax_free_table = TaxTable.new(false)
+      tax_free_table.name = "default table"
+      tax_free_table.create_rule do |rule|
+        rule.area = UsCountryArea.new(UsCountryArea::ALL)
+        rule.rate = 0.0
+      end  
+      return [tax_free_table]
+    end
+  end
+
++Item+ is simply an ActiveRecord class that we are using to hold our purchase item information.  It should respond to the +name+, +description+ and +unit_price+ messages.
+
+== Testing Without Using External Resources
+
+Our first test attempt will be to run the +purchase+ method without talking to
+either the live Google web services, or hitting an actual ActiveRecord
+database.
+
+=== Mocking Active Record
+
+The ActiveRecord part is easy to mock.  The following will handle it:
+
+  flexmock(Item).should_receive(:find).with(1).and_return(
+    flexmock("guitar",
+      :name => "Deschutes",
+      :description => "Deschutes model Guitar",
+      :unit_price => Money.new(2400.00)))
+
+We have mocked out the +find+ method on +Item+ so that whenever we call find
+with an integer argument of 1, we will return a mock item that will report its
+name, description and unit_price. This gives us an item for testing without
+actually reading the database.
+
+=== Mocking the Google Web Services Call
+
+Next we want to prevent the Google4R API from actually talking to the live web
+service. Everything that happens in the purchase method is all done locally
+except for the final call to +send_to_google_checkout+. All we need to do is
+mock out that one method.
+
+  flexmock(Google4R::Checkout::CheckoutCommand).new_instances do |instance|
+    instance.should_receive(:send_to_google_checkout).once.
+      and_return(flexmock(:redirect_url => "http://google.response.url"))
+  end
+
+When we ask +FrontEnd+ to create a check out command, it returns an instance
+of <tt>Google4R::Checkout::CheckoutCommand</tt>. We then use flexmock to
+specify that when Google4R::Checkout::CheckoutCommand creates a new instance,
+it should actually return a partial mock of that instance. The block given to
+the +new_instances+ method allows us to configure the mocked checkout command.
+We tell it return a response object (yes, another mock) that report our dummy
+response URL.
+
+=== The Final Result
+
+Here is the complete unit test:
+
+  def test_buying_a_guitar
+    # Setup
+    flexmock(Item).should_receive(:find).with(1).and_return(
+      flexmock("guitar",
+        :name => "Deschutes",
+        :description => "Deschutes model Guitar",
+        :unit_price => Money.new(2400.00)))
+        
+    flexmock(Google4R::Checkout::CheckoutCommand).new_instances do |instance|
+      instance.should_receive(:send_to_google_checkout).once.
+        and_return(flexmock(:redirect_url => "http://google.response.url"))
+    end
+
+    # Execute
+    p = Purchase.new({ 
+      :merchant_id => 'dummy_id', 
+      :merchant_key => 'dummy_key',
+      :use_sandbox => true })
+    url = p.purchase(1)
+
+    # Assert
+    assert_equal "http://google.response.url", url
+  end
+  
+== Testing the Details
+
+The above test is fine as far as it goes. It demonstrates how to use mocks to
+avoid talking to external resources such as databases and web services.  But as a unit test, it is sorely lacking in several areas. 
+
+All the test really demonstrates is that the +send_to_google_checkout+ method is called.  There are no tests to ensure that the right item descriptions and prices are correctly stored in the cart.  In fact, if we rewrote the purchase method as follows:
+
+  def purchase(item_id, quantity=1)
+    @frontend.create_checkout_command.send_to_google_checkout.redirect_url
+  end  
+
+it would still pass the unit test we designed, even though the rewrite is obviously an incorrect implementation.
+
+A more complete test is a bit more complicated.  Here are the details.
+
+=== Mocking Active Record
+
+Our incorrect version of purchase never calls the +find+ method of Item.  We can easily test for that by adding a +once+ constraint one that mock specification.  Since find is a read-only method, we don't really care if it is called multiple times, as long as it is called at least one time, so we will add an +at_least+ modifier as well.
+
+Finally, we are going to break the guitar mock out into its own declaration.  The reason will become obvious in a bit.
+
+  mock_guitar = flexmock("guitar",
+    :name => "Deschutes",
+    :description => "Deschutes model guitar",
+    :unit_price => Money.new(2400.00))
+
+  flexmock(Item).should_receive(:find).with(1).at_least.once.
+    and_return(mock_guitar)
+
+=== Mocking a Cart Item
+
+The next bit is a wee bit complicated, but we will handle it a little bit at a time so that it doesn't become overwhelming.
+
+There are three main objects in the Google checkout API that we deal with in the next section.:  (1) the checkout command object returned by the front end, (2) the cart object returned by the checkout command, and (3) the item passed to the block in the +create_item+ call.
+
+We will tackle them in reverse order, starting with the item objects given to the +create_item+ block.  The item must respond to four attribute assignments.  This is straightforward to mock, just make sure you include the +once+ constraint so that the assignments are required. 
+
+  mock_item = flexmock("item")
+  mock_item.should_receive(:name=).with(mock_guitar.name).once
+  mock_item.should_receive(:description=).with(mock_guitar.description).once
+  mock_item.should_receive(:unit_price=).with(mock_guitar.unit_price).once
+  mock_item.should_receive(:quantity=).with(1).once
+
+Notice how we used the mock_guitar object defined earlier to provide values in the +with+ constraint.  This way we don't have to repeat the explicit strings and values we are checking.  (Keep it DRY!).
+
+=== Mocking the Cart
+
+The mock cart object will pass the mock_item to a block when the +create_item+ method is called.  We specify that with the following:
+
+  mock_cart = flexmock("cart")
+  mock_cart.should_receive(:create_item).with(Proc).once.and_return { |block|
+    block.call(mock_item)
+  }
+
+FlexMock objects can handle blocks passed to them by treating them as the final object in the calling list.  Use +Proc+ in the +with+ constraint to match the block and then invoke the block explicitly via <tt>block.call(...)</tt> in the +and_return+ specification.
+
+=== Mocking the Checkout Command
+
+Finally, we tie it all together by mocking the checkout command.  As before, we use +new_instances+ to force newly created checkout commands to be stubbed.  This time we not only mockout the +send_to_google+ method, but we also mock the +cart+ command to return the carefully crafted +mock_cart+ object from the previous section.
+
+  flexmock(Google4R::Checkout::CheckoutCommand).new_instances do |instance|
+    instance.should_receive(:cart).with().once.and_return(mock_cart)
+    instance.should_receive(:send_to_google_checkout).once.
+      and_return(flexmock(:redirect_url => "http://google.response.url"))
+  end
+
+=== The Final Test Method
+
+Here is the complete detailed version of the test method.
+
+  def test_buying_a_guitar_with_details
+    # Setup
+    mock_guitar = flexmock("guitar",
+      :name => "Deschutes",
+      :description => "Deschutes model guitar",
+      :unit_price => Money.new(2400.00))
+
+    flexmock(Item).should_receive(:find).with(1).at_least.once.
+      and_return(mock_guitar)
+
+    mock_item = flexmock("item")
+    mock_item.should_receive(:name=).with(mock_guitar.name).once
+    mock_item.should_receive(:description=).with(mock_guitar.description).once
+    mock_item.should_receive(:unit_price=).with(mock_guitar.unit_price).once
+    mock_item.should_receive(:quantity=).with(1).once
+
+    mock_cart = flexmock("cart")
+    mock_cart.should_receive(:create_item).with(Proc).once.and_return { |block|
+      block.call(mock_item)
+    }
+
+    flexmock(Google4R::Checkout::CheckoutCommand).new_instances do |instance|
+      instance.should_receive(:cart).with().once.and_return(mock_cart)
+      instance.should_receive(:send_to_google_checkout).once.
+        and_return(flexmock(:redirect_url => "http://google.response.url"))
+    end
+
+    # Execute
+    p = Purchase.new({ 
+      :merchant_id => 'dummy_id', 
+      :merchant_key => 'dummy_key',
+      :use_sandbox => true })
+    url = p.purchase(1)
+
+    # Assert
+    assert_equal "http://google.response.url", url
+  end
+
+== Summary
+
+Testing with mock objects can get complex. We used seven different mock or
+partial mock objects in testing the interaction of our code with the Google
+checkout API. Most testing scenarios won't require that many, but anytime your
+code touches something external, it might require a mock object for testing.
+
+We should stop and ask ourselves: was it worth it? It seems like an awful lot
+of work just to test a very simple purchase method. Wouldn't it just be easier
+to just use the Google API directly for testing and forget about the mocks?
+
+Perhaps, but using mock objects have several definite advantages:
+
+* You can run the test at any time without worrying whether Google, the
+  internet, or anything else is up and connected.
+
+* You can easy test for error conditions using mock objects. For example, does
+  your code correctly handle the case where you get an exception when
+  connecting to google? Mocks can easily create those error conditions that
+  are difficult to achieve with real objects.
+  
+  E.g.
+  
+     instance.should_receive(:send_to_google_checkout).once.
+       and_return { raise Google4R::Checkout::GoogleCheckoutError }
+
+Some might point out that in the final test method we are hardly using
+Google4R software at all, most of the code we interact with are mock objects.
+Doesn't that defeat the purpose of testing?
+
+The answer is simple. Always keep in mind what you are testing. The goal of
+the TestPurchase test case is not the make sure the Google4R code is correct,
+but that our Purchase class correctly interoperates with it. We do that by
+carefully stating what methods are called with what arguments and what they
+return. The test just checks that we are using to external software as we
+expect it to. We don't actually care about the Google4R software itself in
+this test case (presumably we do have tests that cover Google4R, but those are
+different tests).
+
+In the end, mock objects are a power tool to have in your testing toolbox.

data/doc/releases/flexmock-0.6.0.rdoc

@@ -0,0 +1,136 @@
+= FlexMock 0.6.0 Released
+
+FlexMock is a flexible mocking library for use in unit testing and behavior specification in Ruby.  Version 0.6.0 introduces a number of API enhancements to make testing with mocks even easier than before.
+
+== New in 0.6.0
+
+* Better integration with Test::Unit (no need to explicitly include
+  FlexMock::TestCase).
+
+* Integration with RSpec (version 0.9.0 or later of RSpec is required).
+
+* The +flexmock+ method will now create both regular mocks and partial mocks.
+    
+     flexmock()          # => a full mock
+     flexmock(person)    # => a partial mock based on person
+
+  (+flexstub+ is still included for backwards compatibility).
+
+* Quick and simple mocks my now be created using an expectation hash. For
+  example:
+
+    flexmock(:foo => 10, :bar => "Hello")
+    
+  will create a mock with two methods, :foo and :bar,defined. :foo will
+  return 10 when invoked, and :bar will return "Hello".
+
+* The +should_receive+ method will now allow multiple methods (with the same
+  constraints) be defined in a single call. For example, the following
+  declares that both :read and :write need to be called at least one time each
+  on the mock object.
+
+    flexmock.should_receive(:read, :write).at_least.once
+
+
+* +should_recieve+ now will allow expectation hashes as arguments. This is
+  similar to the list of methods, but allows each defined method to have its
+  own return value.
+
+    flexmock.should_receive(:name => "John", :age => 32)
+
+
+* In addition to using a block for defining constrains, constraints may now be
+  applied directly to the return value of +new_instances+. Combined with the
+  expectation hashes supported by +should_receive+, simple mocking scenarios
+  have become much more succinct. For example:
+
+      flexmock(Person).new_instances.should_receive(:name => "John", :age => 32)
+
+* Improved implementation, allowing for more flexible use and greater
+  consistency between full mock and partial mocks.
+
+* Version 0.6.0 also includes a fix for an incompatibility with some older
+  versions of RCov. The FlexMock Rakefile now includes a RCov task (and we
+  have 100% code coverage).
+
+== What is FlexMock?
+
+FlexMock is a flexible framework for creating mock object for testing. When
+running unit tests, it is often desirable to use isolate the objects being
+tested from the "real world" by having them interact with simplified test
+objects. Sometimes these test objects simply return values when called, other
+times they verify that certain methods were called with particular arguments
+in a particular order.
+
+FlexMock makes creating these test objects easy.
+
+=== Features
+
+* Easy integration with both Test::Unit and RSpec. Mocks created with the
+  flexmock method are automatically verified at the end of the test or
+  example.
+
+* A fluent interface that allows mock behavior to be specified very
+  easily.
+
+* A "record mode" where an existing implementation can record its
+  interaction with a mock for later validation against a new
+  implementation.
+
+* Easy mocking of individual methods in existing, non-mock objects.
+
+* The ability to cause classes to instantiate test instances (instead of real
+  instances) for the duration of a test.
+
+=== Example
+
+Suppose you had a Dog object that wagged a tail when it was happy.
+Something like this:
+
+  class Dog
+    def initialize(a_tail)
+      @tail = a_tail
+    end
+    def happy
+      @tail.wag
+    end
+  end
+
+To test the +Dog+ class without a real +Tail+ object (perhaps because
+real +Tail+ objects activate servos in some robotic equipment), you
+can do something like this:
+
+require 'test/unit'
+require 'flexmock/test_unit'
+
+  class TestDog < Test::Unit::TestCase
+    def test_dog_wags_tail_when_happy
+      tail = flexmock("tail")
+      tail.should_receive(:wag).once
+      dog = Dog.new(tail)
+      dog.happy
+    end
+  end
+
+FlexMock will automatically verify that the mocked tail object received the
+message +wag+ exactly one time. If it doesn't, the test will not pass.
+
+See the FlexMock documentation at http://flexmock.rubyforge.org for details on
+specifying arguments and return values on mocked methods, as well as a simple
+technique for mocking tail objects when the Dog class creates the tail objects
+directly.
+
+== Availability
+
+You can make sure you have the latest version with a quick RubyGems command:
+
+  gem install flexmock    (you may need root/admin privileges)
+
+Otherwise, you can get it from the more traditional places:
+
+Download::  http://rubyforge.org/project/showfiles.php?group_id=170
+
+You will find documentation at: http://flexmock.rubyforge.org.
+
+-- Jim Weirich
+