flexmock 1.0.3 → 1.0.4

data/README.rdoc

@@ -1,9 +1,9 @@
-= Flex Mock -- Making Mocking Easy
+        = Flex Mock -- Making Mocking Easy
 
 FlexMock is a simple, but flexible, mock object library for Ruby unit
 testing.
 
-Version :: 1.0.3
+Version :: 1.0.4
 
 = Links
 
@@ -254,6 +254,48 @@ constraints to your expectation. Here are some examples:
         at_least.twice.at_most.times(10).
         and_return { rand }
 
+Expectation are always matched in order of declaration. That means if
+you have a general expectation before a more specific expectation, the
+general expectation will have an opportunity to match first,
+effectively hiding the second expectation.
+
+For example:
+
+    mock.should_receive(:average)              # Matches any call to average
+    mock.should_receive(:average).with(1).once # Fails because it never matches
+
+In the example, the second expectation will never be triggered because
+all calls to average will be handled by the first expectation. Since
+the second expectation is require to match one time, this test will
+fail.
+
+Reversing the order of the expections so that the more specific
+expectation comes first will fix that problem.
+
+If an expectation has a count requirement (e.g. <code>once</code> or
+<code>times</code>), then once it has matched its expected number of
+times, it will let other expectations have a chance to match.
+
+For example:
+
+    mock.should_receive(:average).once.and_return(1)
+    mock.should_receive(:average).once.and_return(2)
+    mock.should_receive(:average).and_return(3)
+
+In the example, the first time average is called, the first
+expectation is matched an average will return 1. The second time
+average is called, the second expectation matches and 2 is returned.
+For all calls to average after that, the third expectation returning 3
+will be used.
+
+Occasionally it is useful define a set of expecations in a setup
+method of a test and override those expectations in specific tests. If
+you mark an expectation with the <code>by_default</code> marker, that
+expectation will be used only if there are no non-default expectations
+on that method name. See "by_default" below.
+
+=== Expectation Criteria
+
 The following methods may be used to create and refine expectations on
 a mock object. See theFlexMock::Expectation for more details.
 

data/doc/releases/flexmock-1.0.3.rdoc

@@ -0,0 +1,159 @@
+= FlexMock 1.0.3 Released
+
+FlexMock is a flexible mocking library for use in unit testing and
+behavior specification in Ruby.  Release 1.0.0 is a minor release with
+a few bug fixes.
+
+== Changes in 1.0.3
+
+=== Features
+
+* Better error messages when a mock is called the incorrect number of
+  times
+
+* Better stack output when validations fail during teardown.
+
+== Changes in 1.0.2
+
+=== Bug Fixes
+
+* Quick definitions now obey base class restrictions
+
+== Changes in 1.0.1
+
+=== Features
+
+* Better Ruby 1.8 compatibility
+
+== Changes in 1.0.0
+
+=== Features
+
+* Mocks may now have a base class that limits what methods may be
+  mocked. This allows early detection of outdated mock setups when the
+  methods in the class are refactored.
+
+* Spy assertions are now allowed. The verification of the calling of
+  mocked methods may now be done in the "then" portion of the test,
+  after the code under test has been run. This allows for much more
+  natural Given/When/Then style testing.
+
+* A custom assert method (assert_spy_called) has been added to make
+  spy assertions easy when using Test::Unit or MiniTest.
+
+* An RSpec matcher (have_received) has been added to make spy
+  assertions easy when using RSpec.
+
+=== Bug Fixes
+
+* Now correctly handling the mocking of meta-programmed methods.
+
+* Using the documented +singleton_methods+ method.
+
+* Accidently trying to partial mock a regular mock is now a no-op.
+
+== 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.
+
+* Easy mocking of chains of method calls.
+
+* 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:
+
+  RSpec.configure do |config|
+    config.mock_with :flexmock
+  end
+
+  describe Dog do
+    it "wags its tail when happy" do
+      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.
+
+Here's the same thing using the new spy support:
+
+  describe Dog do
+    it "wags its tail when happy" do
+      tail = flexmock("tail")
+      dog = Dog.new(tail)
+      dog.happy
+      tail.should have_received(:wag)
+    end
+  end
+
+This style works particularly well with the rspec-given library.
+
+  require 'rspec/given'
+
+  describe Dog do
+    context "when the dog is happy" do
+      Given(:tail) { flexmock(:on, Tail) }
+      Given(:dog) { Dog.new(tail) }
+
+      When { dog.happy }
+
+      Then { tail.should have_received(:wag) }
+    end
+  end
+
+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)
+
+You will find documentation at: http://flexmock.rubyforge.org.
+
+-- Jim Weirich

data/lib/flexmock/core.rb

@@ -99,13 +99,16 @@ class FlexMock
     self
   end
 
+  CallRecord = Struct.new(:method_name, :args, :expectation)
+
   # Handle missing methods by attempting to look up a handler.
   def method_missing(sym, *args, &block)
-    @calls << [sym, block_given? ? args + [block] : args]
+    enhanced_args = block_given? ? args + [block] : args
+    call_record = CallRecord.new(sym, enhanced_args)
+    @calls << call_record
     flexmock_wrap do
       if handler = @expectations[sym]
-        args << block  if block_given?
-        handler.call(*args)
+        handler.call(enhanced_args, call_record)
       elsif @base_class && @base_class.flexmock_defined?(sym)
         FlexMock.undefined
       elsif @ignore_missing
@@ -143,8 +146,8 @@ class FlexMock
   # True if the mock received the given method and arguments.
   def flexmock_received?(sym, args, options={})
     count = 0
-    @calls.each { |call_sym, call_args|
-      count += 1 if (call_sym == sym) && ArgumentMatching.all_match?(args, call_args)
+    @calls.each { |call_record|
+      count += 1 if (call_record.method_name == sym) && ArgumentMatching.all_match?(args, call_record.args)
     }
     if options[:times]
       result = count == options[:times]

data/lib/flexmock/core_class_methods.rb

@@ -50,11 +50,17 @@ class FlexMock
 
     # Class method to format a method name and argument list as a nice
     # looking string.
-    def format_args(sym, args)  # :nodoc:
+    def format_call(sym, args)  # :nodoc:
+      "#{sym}(#{format_args(args)})"
+    end
+
+    # Class method to format a list of args (the part between the
+    # parenthesis).
+    def format_args(args)
       if args
-        "#{sym}(#{args.collect { |a| a.inspect }.join(', ')})"
+        args.collect { |a| a.inspect }.join(', ')
       else
-        "#{sym}(*args)"
+        "*args"
       end
     end
 

data/lib/flexmock/expectation.rb

@@ -49,7 +49,23 @@ class FlexMock
     end
 
     def to_s
-      FlexMock.format_args(@sym, @expected_args)
+      FlexMock.format_call(@sym, @expected_args)
+    end
+
+    # Return a description of the matching features of the
+    # expectation. Matching features include:
+    #
+    # * name of the method
+    # * argument matchers
+    # * call count validators
+    #
+    def description
+      result = "should_receive(#{@sym.inspect})"
+      result << ".with(#{FlexMock.format_args(@expected_args)})" if @expected_args
+      @count_validators.each do |validator|
+        result << validator.describe
+      end
+      result
     end
 
     # Verify the current call with the given arguments matches the

data/lib/flexmock/expectation_director.rb

@@ -35,10 +35,11 @@ class FlexMock
     # but at least we will get a good failure message).  Finally,
     # check for expectations that don't have any argument matching
     # criteria.
-    def call(*args)
+    def call(args, call_record=nil)
       exp = find_expectation(*args)
+      call_record.expectation = exp if call_record
       FlexMock.check(
-        "no matching handler found for " + FlexMock.format_args(@sym, args)) { ! exp.nil? }
+        "no matching handler found for " + FlexMock.format_call(@sym, args)) { ! exp.nil? }
       exp.verify_call(*args)
     end
 

data/lib/flexmock/spy_describers.rb

@@ -2,16 +2,16 @@ class FlexMock
 
     module SpyDescribers
       def describe_spy_expectation(spy, sym, args, options={})
-        describe(spy, sym, args, options)
+        describe_spy(spy, sym, args, options)
       end
 
       def describe_spy_negative_expectation(spy, sym, args, options={})
-        describe(spy, sym, args, options, " NOT")
+        describe_spy(spy, sym, args, options, " NOT")
       end
 
       private
 
-      def describe(spy, sym, args, options, not_clause="")
+      def describe_spy(spy, sym, args, options, not_clause="")
         result = "expected "
         result << call_description(sym, args)
         result << " to#{not_clause} be received by "
@@ -29,8 +29,10 @@ class FlexMock
           result << "No messages have been received\n"
         else
           result << "The following messages have been received:\n"
-          spy.flexmock_calls.each do |call_sym, call_args|
-            result << "    " << call_description(call_sym, call_args) << "\n"
+          spy.flexmock_calls.each do |call_record|
+            result << "    " << call_description(call_record.method_name, call_record.args)
+            result << " matched by " << call_record.expectation.description if call_record.expectation
+            result << "\n"
           end
         end
         result

data/lib/flexmock/validators.rb

@@ -32,9 +32,24 @@ class FlexMock
       n < @limit
     end
 
+    # Pluralize "call"
     def calls(n)
       n == 1 ? "call" : "calls"
     end
+
+    # Human readable description of the validator
+    def describe
+      case @limit
+      when 0
+        ".never"
+      when 1
+        ".once"
+      when 2
+        ".twice"
+      else
+        ".times(#{@limit})"
+      end
+    end
   end
 
   ####################################################################
@@ -48,7 +63,7 @@ class FlexMock
         FlexMock.framework_adapter.assert_block(
           lambda {
             "Method '#{@exp}' called incorrect number of times\n" +
-            "#{@limit} #{calls(@limit)} expected\n" +
+            "#{@limit} matching #{calls(@limit)} expected\n" +
             "#{n} matching #{calls(n)} found\n" +
             describe_calls(@exp.mock)
           }
@@ -68,13 +83,22 @@ class FlexMock
         FlexMock.framework_adapter.assert_block(
           lambda {
             "Method '#{@exp}' called incorrect number of times\n" +
-            "At least #{@limit} #{calls(@limit)} expected\n" +
+            "At least #{@limit} matching #{calls(@limit)} expected\n" +
             "#{n} matching #{calls(n)} found\n" +
             describe_calls(@exp.mock)
           }) { n >= @limit }
       end
     end
 
+    # Human readable description of the validator.
+    def describe
+      if @limit == 0
+        ".zero_or_more_times"
+      else
+        ".at_least#{super}"
+      end
+    end
+
     # If the expectation has been called +n+ times, is it still
     # eligible to be called again?  Since this validator only
     # establishes a lower limit, not an upper limit, then the answer
@@ -94,11 +118,17 @@ class FlexMock
         FlexMock.framework_adapter.assert_block(
           lambda {
             "Method '#{@exp}' called incorrect number of times\n" +
-            "At most #{@limit} #{calls(@limit)} expected\n" +
+            "At most #{@limit} matching #{calls(@limit)} expected\n" +
             "#{n} matching #{calls(n)} found\n" +
             describe_calls(@exp.mock)
           }) { n <= @limit }
       end
     end
+
+    # Human readable description of the validator
+    def describe
+      ".at_most#{super}"
+    end
+
   end
 end

data/lib/flexmock/version.rb

@@ -3,7 +3,7 @@ class FlexMock
     NUMBERS = [
       MAJOR = 1,
       MINOR = 0,
-      BUILD = 3,
+      BUILD = 4,
     ]
   end
 

data/test/assert_spy_called_test.rb

@@ -76,7 +76,7 @@ class AssertSpyCalledTest < Test::Unit::TestCase
     end
   end
 
-  def test_assert_error_lists_calls_actually_made
+  def test_assert_error_lists_calls_actually_made_without_handled_by
     spy.foo
     spy.bar(1)
     ex = assert_fails(/The following messages have been received/) do
@@ -85,6 +85,19 @@ class AssertSpyCalledTest < Test::Unit::TestCase
     assert_match(/  foo\(\)/, ex.message)
     assert_match(/  bar\(1\)/, ex.message)
     assert_no_match(/  baz\(\)/, ex.message)
+    assert_no_match(/handled by/, ex.message)
+  end
+
+  def test_assert_error_lists_calls_actually_made_with_handled_by
+    spy.should_receive(:foo).once
+    spy.foo
+    spy.bar(1)
+    ex = assert_fails(/The following messages have been received/) do
+      assert_spy_called spy, :baz
+    end
+    assert_match(/  foo\(\) matched by should_receive\(:foo\)/, ex.message)
+    assert_match(/  bar\(1\)/, ex.message)
+    assert_no_match(/  baz\(\)/, ex.message)
   end
 
   def test_assert_errors_say_no_calls_made

data/test/deprecated_methods_test.rb

@@ -174,7 +174,7 @@ class TestFlexMock < Test::Unit::TestCase
     s { @mock.mock_handle(:xyzzy) { got_it = true } }
     method_proc = @mock.method(:xyzzy)
     assert_not_nil method_proc
-    method_proc.call
+    method_proc.call([])
     assert(got_it, "method proc should run")
   end
 

data/test/expectation_description_test.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+
+#---
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
+# 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 'test/test_setup'
+
+class ExpectationDescriptionTest < Test::Unit::TestCase
+  include FlexMock::TestCase
+
+  def setup
+    @mock = flexmock("mock")
+    @exp = FlexMock::Expectation.new(@mock, :foo, "file.rb:3")
+  end
+
+  def test_basic_description
+    assert_equal "should_receive(:foo)", @exp.description
+  end
+
+  def test_with_no_args
+    @exp.with()
+    assert_equal "should_receive(:foo).with()", @exp.description
+  end
+
+  def test_with_simple_args
+    @exp.with(1, "HI")
+    assert_equal "should_receive(:foo).with(1, \"HI\")", @exp.description
+  end
+
+  def test_with_never
+    @exp.never
+    assert_equal "should_receive(:foo).never", @exp.description
+  end
+
+  def test_with_once
+    @exp.once
+    assert_equal "should_receive(:foo).once", @exp.description
+  end
+
+  def test_with_twice
+    @exp.twice
+    assert_equal "should_receive(:foo).twice", @exp.description
+  end
+
+  def test_with_3
+    @exp.times(3)
+    assert_equal "should_receive(:foo).times(3)", @exp.description
+  end
+
+  def test_with_at_least_once
+    @exp.at_least.once
+    assert_equal "should_receive(:foo).at_least.once", @exp.description
+  end
+
+  def test_with_at_least_10
+    @exp.at_least.times(10)
+    assert_equal "should_receive(:foo).at_least.times(10)", @exp.description
+  end
+
+  def test_with_at_most_once
+    @exp.at_most.once
+    assert_equal "should_receive(:foo).at_most.once", @exp.description
+  end
+
+  def test_with_zero_or_more_times
+    @exp.at_most.zero_or_more_times
+    assert_equal "should_receive(:foo).zero_or_more_times", @exp.description
+  end
+
+  def test_with_at_least_1_at_most_10
+    @exp.at_least.once.at_most.times(10)
+    assert_equal "should_receive(:foo).at_least.once.at_most.times(10)", @exp.description
+  end
+end

data/test/should_ignore_missing_test.rb

@@ -63,7 +63,7 @@ class TestShouldIgnoreMissing < Test::Unit::TestCase
     @mock.should_receive(:known_foo).once
     method_proc = @mock.method(:known_foo)
     assert_not_nil method_proc
-    method_proc.call
+    method_proc.call([])
   end
 
   def test_not_calling_method_proc_will_fail_count_constraints

metadata

@@ -1,29 +1,25 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: flexmock
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 1.0.4
   prerelease: 
-  version: 1.0.3
 platform: ruby
-authors: 
+authors:
 - Jim Weirich
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-09-18 00:00:00 Z
+date: 2012-10-12 00:00:00.000000000Z
 dependencies: []
-
-description: "\n      FlexMock is a extremely simple mock object class compatible\n      with the Test::Unit framework.  Although the FlexMock's\n      interface is simple, it is very flexible.\n    "
+description: ! "\n      FlexMock is a extremely simple mock object class compatible\n
+  \     with the Test::Unit framework.  Although the FlexMock's\n      interface is
+  simple, it is very flexible.\n    "
 email: jim.weirich@gmail.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.rdoc
 - CHANGES
-- doc/examples/rspec_examples_spec.rdoc
-- doc/examples/test_unit_examples_test.rdoc
 - doc/GoogleExample.rdoc
 - doc/releases/flexmock-0.4.0.rdoc
 - doc/releases/flexmock-0.4.1.rdoc
@@ -45,7 +41,10 @@ extra_rdoc_files:
 - doc/releases/flexmock-0.8.5.rdoc
 - doc/releases/flexmock-0.9.0.rdoc
 - doc/releases/flexmock-1.0.0.rdoc
-files: 
+- doc/releases/flexmock-1.0.3.rdoc
+- doc/examples/rspec_examples_spec.rdoc
+- doc/examples/test_unit_examples_test.rdoc
+files:
 - CHANGES
 - Gemfile
 - Gemfile.lock
@@ -93,6 +92,7 @@ files:
 - test/demeter_mocking_test.rb
 - test/deprecated_methods_test.rb
 - test/examples_from_readme_test.rb
+- test/expectation_description_test.rb
 - test/extended_should_receive_test.rb
 - test/flexmodel_test.rb
 - test/naming_test.rb
@@ -116,8 +116,6 @@ files:
 - test/undefined_test.rb
 - flexmock.blurb
 - install.rb
-- doc/examples/rspec_examples_spec.rdoc
-- doc/examples/test_unit_examples_test.rdoc
 - doc/GoogleExample.rdoc
 - doc/releases/flexmock-0.4.0.rdoc
 - doc/releases/flexmock-0.4.1.rdoc
@@ -139,36 +137,36 @@ files:
 - doc/releases/flexmock-0.8.5.rdoc
 - doc/releases/flexmock-0.9.0.rdoc
 - doc/releases/flexmock-1.0.0.rdoc
+- doc/releases/flexmock-1.0.3.rdoc
+- doc/examples/rspec_examples_spec.rdoc
+- doc/examples/test_unit_examples_test.rdoc
 homepage: https://github.com/jimweirich/flexmock
 licenses: []
-
 post_install_message: 
-rdoc_options: 
+rdoc_options:
 - --title
 - FlexMock
 - --main
 - README.rdoc
 - --line-numbers
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.15
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Simple and Flexible Mock Objects for Testing
 test_files: []
-