flexmock 0.1.7 → 0.2.0

data/CHANGELOG

@@ -1,5 +1,10 @@
 = Changes for FlexMock
 
+== Version 0.2.0
+
+* Added record mode for building expectations.
+* Fixed a bunch of documentation.
+
 == Version 0.1.7
 
 * Bumped version because 0.1.6 was uploaded to the wrong Rubyforge area.

data/README

@@ -3,7 +3,7 @@
 FlexMock is a simple mock object for unit testing.  The interface is
 simple, but still provides a good bit of flexibility.
 
-Version :: 0.1.7
+Version :: 0.2.0
 
 = Links
 
@@ -49,62 +49,163 @@ Here's the complete example:
 
 == Quick Reference
 
-The following declarators may be used to create the proper
-expectations on a FlexMock object.
+=== Expectation Declarators
 
-* <tt>should_receive(<em>symbol</em>)</tt> -- Declares that a message
-  named <em>symbol</em> will be sent to the mock object.  Further
-  refinements on this expected message (called an expectation) may be
-  chained to the +should_receive+ call.
-* <tt>with(<em>arglist</em>)</tt> -- Declares that this expectation
-  matches messages that match the given argument list.  The
-  <tt>===</tt> operator is used on a argument by argument basis to
+Expectation declarators are used to specify the expectations placed
+upon received method calls.  The following declarators may be used to
+create the proper expectations on a FlexMock object.
+
+* <b><tt>should_receive(<em>symbol</em>)</tt></b> -- Declares that a
+  message named <em>symbol</em> will be sent to the mock object.
+  Further refinements on this expected message (called an expectation)
+  may be chained to the +should_receive+ call.
+
+* <b><tt>should_expect</tt></b> -- Creates a mock recording object
+  that will translate received method calls into mock expectations.
+  The recorder is passed to a block supplied with the +should_expect+
+  method.  See examples below.
+
+* <b><tt>with(<em>arglist</em>)</tt></b> -- Declares that this
+  expectation matches messages that match the given argument list.
+  The <tt>===</tt> operator is used on a argument by argument basis to
   determine matching.  This means that most literal values match
   literally, class values match any instance of a class and regular
   expression match any matching string (after a +to_s+ conversion).
-* <tt>with_any_args</tt> -- Declares that this expectation matches the
-  message with any argument (default)
-* <tt>with_no_args</tt> -- Declares that this expectation matches
-  messages with no arguments
-* <tt>returns(<em>value</em>)</tt> -- Declares that the message will
-  return the given value (<tt>returns(nil)</tt> is the default).
-* <tt>returns { code ... }</tt> -- Declares that the message will
-  return whatever the block calculates.
-* <tt>zero_or_more_times</tt> -- Declares that the message is may be
-  sent zero or more times (default, equivalent to
+  See argument validators (below) for details on argument validation
+  options.
+
+* <b><tt>with_any_args</tt></b> -- Declares that this expectation
+  matches the message with any argument (default)
+
+* <b><tt>with_no_args</tt></b> -- Declares that this expectation
+  matches messages with no arguments
+
+* <b><tt>returns(<em>value</em>)</tt></b> -- Declares that the message
+  will return the given value (<tt>returns(nil)</tt> is the default).
+
+* <b><tt>returns { |args| code ... }</tt></b> -- Declares that the
+  message will return whatever the block calculates.  The actual
+  arguments in the message will be passed to the block.
+
+* <b><tt>zero_or_more_times</tt></b> -- Declares that the message is
+  may be sent zero or more times (default, equivalent to
   <tt>at_least.never</tt>).
-* <tt>once</tt> -- Declares that the message is only sent once.
-  <tt>at_least</tt> / <tt>at_most</tt> modifiers are allowed.
-* <tt>twice</tt> -- Declares that the message is only sent twice.
+
+* <b><tt>once</tt></b> -- Declares that the message is only sent once.
   <tt>at_least</tt> / <tt>at_most</tt> modifiers are allowed.
-* <tt>never</tt> -- Declares that the message is never sent.
+
+* <b><tt>twice</tt></b> -- Declares that the message is only sent
+  twice.  <tt>at_least</tt> / <tt>at_most</tt> modifiers are allowed.
+
+* <b><tt>never</tt></b> -- Declares that the message is never sent.
   <tt>at_least</tt> / <tt>at_most</tt> modifiers are allowed.
-* <tt>times(<em>n</em>)</tt> -- Declares that the message is sent
-  <em>n</em> times.  <tt>at_least</tt> / <tt>at_most</tt> modifiers
-  are allowed.
-* <tt>at_least</tt> -- Modifies the immediately following message
-  count declarator so that it means the message is sent at least that
-  number of times.  E.g. <tt>at_least.once</tt> means the message is
-  sent at least once during the test, but may be sent more often.
-  Both <tt>at_least</tt> and <tt>at_most</tt> may be specified on the
-  same expectation.
-* <tt>at_most</tt> -- Similar to <tt>at_least</tt>, but puts an upper
-  limit on the number of messages.  Both <tt>at_least</tt> and
+
+* <b><tt>times(<em>n</em>)</tt></b> -- Declares that the message is
+  sent <em>n</em> times.  <tt>at_least</tt> / <tt>at_most</tt>
+  modifiers are allowed.
+
+* <b><tt>at_least</tt></b> -- Modifies the immediately following
+  message count declarator so that it means the message is sent at
+  least that number of times.  E.g. <tt>at_least.once</tt> means the
+  message is sent at least once during the test, but may be sent more
+  often.  Both <tt>at_least</tt> and <tt>at_most</tt> may be specified
+  on the same expectation.
+
+* <b><tt>at_most</tt></b> -- Similar to <tt>at_least</tt>, but puts an
+  upper limit on the number of messages.  Both <tt>at_least</tt> and
   <tt>at_most</tt> may be specified on the same expectation.
-* <tt>ordered</tt> -- Declares that the message is ordered and is
-  expected to be received in a certain position in a sequence of
+
+* <b><tt>ordered</tt></b> -- Declares that the message is ordered and
+  is expected to be received in a certain position in a sequence of
   messages.  The message should arrive after and previously declared
   ordered messages and prior to any following declared ordered
   messages.  Unordered messages are ignored when considering the
   message order.
-* <tt>ordered(<em>n</em>)</tt> -- Declares that the message is ordered
-  with a specific order number.  Order numbers are normally supplied
-  sequentially starting with 1.  Explicitly ordered messages must have
-  a sequence number greater than the prior implicit order number.
-  Using explicit order allows messages to be grouped so that the order
-  of messages in a group (sharing an order number) can be received in
-  any sequence, but the order between groups is still maintained.  See
-  the explicit ordering example below.
+
+* <b><tt>ordered(<em>group</em>)</tt></b> -- Declare that the given
+  method belongs to an order group.  Methods within the group may be
+  received in any order.  Ordered messages outside the group must be
+  received either before or after the grouped messages.
+
+  For example, in the following, messages +flip+ and +flop+ may be
+  received in any order (because they are in the same group), but must
+  occur strictly after +start+ but before +end+.  The message
+  +any_time+ may be received at any time because it is not ordered.
+    
+        m = FlexMock.new
+        m.should_receive(:any_time)
+        m.should_receive(:start).ordered
+        m.should_receive(:flip).ordered(:flip_flop_group)
+        m.should_receive(:flop).ordered(:flip_flop_group)
+        m.should_receive(:end).ordered
+    
+=== Argument Validation
+
+The values passed to the +with+ declarator determine the criteria for
+matching expectations.  The first expectation found that matches the
+arguments in a mock method call will be used to validate that mock
+method call.
+
+The following rules are used for argument matching:
+
+* A +with+ parameter that is a class object will match any actual
+  argument that is an instance of that class.
+
+  Examples:
+
+     with(Integer)     will match    f(3)
+
+* A regular expression will match any actual argument that matches the
+  regular expression.  Non-string actual arguments are converted to
+  strings via +to_s+ before applying the regular expression.
+
+  Examples:
+
+    with(/^src/)      will match    f("src_object")
+    with(/^3\./)      will match    f(3.1415972)
+
+* Most other objects will match based on equal values.
+
+  Examples:
+
+      with(3)         will match    f(3)
+      with("hello")   will match    f("hello")
+  
+* If you wish to override the default matching behavior and force
+  matching by equality, you can use teh FlexMock.eq convenience
+  method.  This is mostly used when you wish to match class objects,
+  since the default matching behavior for class objects is to match
+  instances, not themselves.
+
+  Examples:
+
+      with(FlexMock.eq(Integer))    will match       f(Integer)
+      with(FlexMock.eq(Integer))    will NOT match   f(3)
+
+  If the user includes the FlexMock::ArgumentTypes module in the test
+  class, the above examples can be shortened to:
+
+      with(eq(Integer))             will match       f(Integer)
+      with(eq(Integer))             will NOT match   f(3)
+
+* If you wish to match _anything_, then use the <tt>FlexMock.any</tt>
+  method in the with argument list.
+
+  Examples (assumes FlexMock::ArguementTypes has been included):
+
+      with(any)             will match       f(3)
+      with(any)             will match       f("hello")
+      with(any)             will match       f(Integer)
+      with(any)             will match       f(nil)
+
+* If you wish to specify a complex matching criteria, use the
+  <tt>FlexMock.on(&block)</tt> with the logic contained in the block.
+
+  Examples (assumes FlexMock::ArguementTypes has been included):
+
+      with(on { |arg| (arg % 2) == 0 } )
+
+  will match any even integer.
 
 == Examples
 
@@ -115,7 +216,7 @@ argument of 5.
 
    FlexMock('db').use |db|
      db.should_receive(:query).and_return([1,2,3])
-     db.should_recieve(:update).with(5).and_return(nil).once
+     db.should_receive(:update).with(5).and_return(nil).once
      # test code here
    end
 
@@ -125,18 +226,18 @@ All the query message must occur before any of the update messages.
 
    FlexMock('db').use |db|
      db.should_receive(:query).and_return([1,2,3]).ordered
-     db.should_recieve(:update).and_return(nil).ordered
+     db.should_receive(:update).and_return(nil).ordered
      # test code here
    end
 
 === Expect several queries with different parameters
 
 The queries should happen after startup but before finish.  The
-queries themselves may happen in any order (because they have the same
-order number).  The first two queries should happen exactly once, but
-the third query (which matches any query call with a four character
-parameter) may be called multiple times (but at least once).  Startup
-and finish must also happen exactly once.
+queries themselves may happen in any order (because they are in the
+same order group).  The first two queries should happen exactly once,
+but the third query (which matches any query call with a four
+character parameter) may be called multiple times (but at least once).
+Startup and finish must also happen exactly once.
 
 Also note that we use the +with+ method to match different arguement
 values to figure out what value to return.
@@ -153,6 +254,19 @@ values to figure out what value to return.
      # test code here
    end
 
+=== Same as above, but using the record mode interface
+
+   FlexMock('db').use |db|
+     db.should_expect do |rec|
+       rec.startup.once.ordered
+       rec.query("CPWR") { 12.3 }.once.ordered(:queries)
+       rec.query("MSFT") { 10.0 }.once.ordered(:queries)
+       rec.query(/^....$/) { 3.3 }.at_least.once.ordered(:queries)
+       rec.finish.once.ordered
+     end
+     # test code here
+   end
+
 === Expect multiple calls, returning a different value each time
 
 Sometimes you need to return different values for each call to a

data/Rakefile

@@ -8,7 +8,7 @@ require 'rake/testtask'
 
 CLOBBER.include("html", 'pkg')
 
-PKG_VERSION = '0.1.7'
+PKG_VERSION = '0.2.0'
 
 PKG_FILES = FileList[
   '[A-Z]*',
@@ -52,7 +52,7 @@ end
 
 task :rdoc => ["README"]
 file "README" => ["Rakefile"] do
-  ruby %{-i.bak -pe 'sub!(/^Version *:: *(\\d+\\.)+\\d+ *$/, "Version :: #{PKG_VERSION}")' README}
+  ruby %{-i.bak -pe 'sub!(/^Version *:: *(\\d+\\.)+\\d+ *$/, "Version :: #{PKG_VERSION}")' README} # "
 end
 
 # Package Task -------------------------------------------------------
@@ -112,6 +112,12 @@ else
   end
 end
 
+desc "Display a list of all the rubyfiles in the project."
+task :rubyfiles do
+  puts FileList['**/*.rb']
+end
+task :rf => :rubyfiles
+
 require 'rake/contrib/publisher'
 require 'rake/contrib/sshpublisher'
 
@@ -129,4 +135,8 @@ task :publish => [:rdoc] do
   blurb_publisher.upload
 end
 
+SVNHOME = 'svn://localhost/software/flexmock'
 
+task :tag do
+  sh %{svn copy #{SVNHOME}/trunk #{SVNHOME}/tags/rel-#{PKG_VERSION} -m 'Release #{PKG_VERSION}'}
+end

data/lib/flexmock.rb

@@ -30,6 +30,9 @@ require 'test/unit'
 #   m.should_receive(:downcase).with(String).
 #     returns { |s| s.downcase }.once
 #
+  class FlexMock
+  end
+
 class FlexMock
   include Test::Unit::Assertions
 
@@ -118,6 +121,22 @@ class FlexMock
     result
   end
 
+  # Declare that the mock object should expect methods by providing a
+  # recorder for the methods and having the user invoke the expected
+  # methods in a block.  Further expectations may be applied the
+  # result of the recording call.
+  #
+  # Example Usage:
+  #
+  #   mock.should_expect do |record|
+  #     record.add(Integer, 4) { |a, b|
+  #       a + b
+  #     }.at_least.once
+  #
+  def should_expect
+    yield Recorder.new(self)
+  end
+
   class << self
     include Test::Unit::Assertions
 
@@ -279,6 +298,9 @@ class FlexMock
       EqualMatcher.new(obj)
     end
 
+    # Return an argument matcher that matches any object, that when
+    # passed to the supplied block, will cause the block to return
+    # true.
     def on(&block)
       ProcMatcher.new(&block)
     end
@@ -514,7 +536,7 @@ class FlexMock
     # (e.g. specifying that a group of messages may be received in any
     # order as long as they all come after another group of messages),
     # a _group_ _name_ may be specified in the +ordered+ calls.  All
-    # messages within the same group may be recieved in any order.
+    # messages within the same group may be received in any order.
     #
     # For example, in the following, messages +flip+ and +flop+ may be
     # received in any order (because they are in the same group), but
@@ -542,5 +564,22 @@ class FlexMock
     end
   end
 
+  ####################################################################
+  # Translate arbitrary method calls into expectations on the given
+  # mock object.
+  #
+  class Recorder
+    # Create a method recorder for the mock +mock+.
+    def initialize(mock)
+      @mock = mock
+    end
+
+    # Record an expectation for receiving the method +sym+ with the
+    # given arguments.
+    def method_missing(sym, *args, &block)
+      @mock.should_receive(sym).and_return(&block).with(*args)
+    end
+  end
+  
   extend ArgumentTypes
 end

data/test/test_record_mode.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'flexmock'
+
+module FailureAssertion
+  private
+  def assert_fails
+    assert_raise(Test::Unit::AssertionFailedError) do
+      yield
+    end
+  end
+end
+
+class TestRecordMode < Test::Unit::TestCase
+  include FlexMock::ArgumentTypes
+  include FailureAssertion
+
+  def test_recording_mode_works
+    FlexMock.use("mock") do |mock|
+      mock.should_expect do |r|
+        r.f { :answer }
+      end
+      assert_equal :answer, mock.f
+    end
+  end
+
+  def test_arguments_are_passed_to_recording_mode_block
+    FlexMock.new("mock") do |mock|
+      mock.should_expect do |recorder|
+        recorder.f do |arg|
+          assert_equal :arg, arg
+          :answer
+        end
+      end
+      assert_equal :answer, f(:arg)
+    end
+  end
+
+  def test_recording_mode_handles_multiple_returns
+    FlexMock.use("mock") do |mock|
+      mock.should_expect do |r|
+        answers = [1, 2]
+        r.f { answers.shift }
+      end
+      assert_equal 1, mock.f
+      assert_equal 2, mock.f
+    end
+  end
+
+  def test_recording_mode_does_not_specify_order
+    FlexMock.use("mock") do |mock|
+      mock.should_expect do |r|
+        r.f { 1 }
+        r.g { 2 }
+      end
+      assert_equal 2, mock.g
+      assert_equal 1, mock.f
+    end
+  end
+
+  def test_recording_mode_gets_block_args_too
+    FlexMock.use("mock") do |mock|
+      mock.should_expect do |r|
+        r.f(1, Proc) { |arg, block|
+          assert_not_nil block
+          block.call
+        }
+      end
+
+      assert_equal :block_result, mock.f(1) { :block_result }
+    end
+  end
+
+  def test_recording_mode_should_validate_args_with_equals
+    assert_fails do
+      FlexMock.use("mock") do |mock|
+        mock.should_expect do |r|
+          r.f(1)
+        end
+        mock.f(2)
+      end
+    end
+  end
+
+  def test_recording_mode_should_allow_arg_contraint_validation
+    assert_fails do
+      FlexMock.use("mock") do |mock|
+        mock.should_expect do |r|
+          r.f(1)
+        end
+        mock.f(2)
+      end
+    end
+  end
+
+  def test_recording_mode_should_handle_multiplicity_contraints
+    assert_fails do
+      FlexMock.use("mock") do |mock|
+        mock.should_expect do |r|
+          r.f { :result }.once
+        end
+        mock.f
+        mock.f
+      end
+    end
+  end
+
+end

metadata

@@ -1,57 +1,61 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.11.3
+rubygems_version: 0.8.11.6
 specification_version: 1
 name: flexmock
 version: !ruby/object:Gem::Version 
-  version: 0.1.7
-date: 2005-11-13 00:00:00 -05:00
+  version: 0.2.0
+date: 2006-03-21 00:00:00 -05:00
 summary: Simple and Flexible Mock Objects for Testing
 require_paths: 
-  - lib
+- lib
 email: jim@weirichhouse.org
 homepage: http://onestepback.org/software/flexmock
 rubyforge_project: 
-description: "FlexMock is a extremely simple mock object class compatible with the Test::Unit
-  framework.  Although the FlexMock's  interface is simple, it is very flexible."
+description: FlexMock is a extremely simple mock object class compatible with the Test::Unit framework.  Although the FlexMock's  interface is simple, it is very flexible.
 autorequire: 
 default_executable: 
 bindir: bin
 has_rdoc: true
 required_ruby_version: !ruby/object:Gem::Version::Requirement 
   requirements: 
-    - 
-      - ">"
-      - !ruby/object:Gem::Version 
-        version: 0.0.0
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
   version: 
 platform: ruby
 signing_key: 
 cert_chain: 
 authors: 
-  - Jim Weirich
+- Jim Weirich
 files: 
-  - README
-  - Rakefile
-  - CHANGELOG
-  - lib/flexmock.rb
-  - test/test_mock.rb
-  - test/test_example.rb
-  - test/test_naming.rb
-  - test/test_samples.rb
-  - test/test_should_receive.rb
-  - flexmock.blurb
-  - install.rb
+- CHANGELOG
+- Rakefile
+- README
+- lib/flexmock.rb
+- test/test_record_mode.rb
+- test/test_should_receive.rb
+- test/test_samples.rb
+- test/test_mock.rb
+- test/test_naming.rb
+- test/test_example.rb
+- flexmock.blurb
+- install.rb
 test_files: []
+
 rdoc_options: 
-  - "--title"
-  - Flex Mock
-  - "--main"
-  - README
-  - "--line-numbers"
+- --title
+- Flex Mock
+- --main
+- README
+- --line-numbers
 extra_rdoc_files: 
-  - README
-  - CHANGELOG
+- CHANGELOG
+- README
 executables: []
+
 extensions: []
+
 requirements: []
-dependencies: []
+
+dependencies: []
+