flexmock 0.9.0 → 1.0.0.beta.1

data/doc/releases/flexmock-1.0.0.rdoc

@@ -0,0 +1,128 @@
+= FlexMock 1.0.0 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.0
+
+* 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.
+
+== 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.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #---
-# Copyright 2003-2011 by Jim Weirich (jim@weirichhouse.org).
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
 # All rights reserved.
 
 # Permission is granted for use, copying, modification, distribution,

data/lib/flexmock/argument_matchers.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #---
-# Copyright 2003-2011 by Jim Weirich (jim@weirichhouse.org).
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
 # All rights reserved.
 #
 # Permission is granted for use, copying, modification, distribution,
@@ -54,7 +54,7 @@ class FlexMock
   end
 
   ####################################################################
-  # Match only things where the block evaluates to true.
+  # Match hashes that match all the fields of +hash+.
   class HashMatcher
     def initialize(hash)
       @hash = hash
@@ -68,7 +68,7 @@ class FlexMock
   end
 
   ####################################################################
-  # Match only things where the block evaluates to true.
+  # Match objects that implement all the methods in +methods+.
   class DuckMatcher
     def initialize(methods)
       @methods = methods
@@ -81,5 +81,18 @@ class FlexMock
     end
   end
 
+  ####################################################################
+  # Match objects that implement all the methods in +methods+.
+  class OptionalProcMatcher
+    def initialize
+    end
+    def ===(target)
+      ArgumentMatching.missing?(target) || Proc === target
+    end
+    def inspect
+      "optional_proc"
+    end
+  end
+  OPTIONAL_PROC_MATCHER = OptionalProcMatcher.new
 
 end

data/lib/flexmock/argument_matching.rb

@@ -0,0 +1,33 @@
+class FlexMock
+  module ArgumentMatching
+    module_function
+
+    MISSING_ARG = Object.new
+
+    def all_match?(expected_args, actual_args)
+      return true if expected_args.nil?
+      return false if actual_args.size > expected_args.size
+      i = 0
+      while i < actual_args.size
+        return false unless match?(expected_args[i], actual_args[i])
+        i += 1
+      end
+      while i < expected_args.size
+        return false unless match?(expected_args[i], MISSING_ARG)
+        i += 1
+      end
+      true
+    end
+
+    # Does the expected argument match the corresponding actual value.
+    def match?(expected, actual)
+      expected === actual ||
+      expected == actual ||
+      ( Regexp === expected && expected === actual.to_s )
+    end
+
+    def missing?(arg)
+      arg == MISSING_ARG
+    end
+  end
+end

data/lib/flexmock/argument_types.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #---
-# Copyright 2003-2011 by Jim Weirich (jim@weirichhouse.org).
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
 # All rights reserved.
 
 # Permission is granted for use, copying, modification, distribution,
@@ -48,6 +48,10 @@ class FlexMock
     def ducktype(*methods)
       DuckMatcher.new(methods)
     end
+
+    def optional_proc
+      OPTIONAL_PROC_MATCHER
+    end
   end
   extend ArgumentTypes
 

data/lib/flexmock/base.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #---
-# Copyright 2003-2011 by Jim Weirich (jim@weirichhouse.org).
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
 # All rights reserved.
 
 # Permission is granted for use, copying, modification, distribution,

data/lib/flexmock/composite.rb

@@ -1,10 +1,10 @@
 #!/usr/bin/env ruby
 #
-#  Created by Jim Weirich on 2007-04-14.
-#  Copyright (c) 2007. All rights reserved.
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
+# All rights reserved.
 
 require 'flexmock/noop'
 
 class FlexMock
 
-end
+end

data/lib/flexmock/core.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #---
-# Copyright 2003-2011 by Jim Weirich (jim@weirichhouse.org).
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
 # All rights reserved.
 #
 # Permission is granted for use, copying, modification, distribution,
@@ -12,6 +12,8 @@
 require 'flexmock/errors'
 require 'flexmock/composite'
 require 'flexmock/ordering'
+require 'flexmock/argument_matching'
+require 'flexmock/explicit_needed'
 
 ######################################################################
 # FlexMock is a flexible mock object framework for supporting testing.
@@ -57,6 +59,8 @@ class FlexMock
     @expectations = Hash.new
     @ignore_missing = false
     @verified = false
+    @calls = []
+    @base_class = nil
     container = UseContainer.new if container.nil?
     container.flexmock_remember(self)
   end
@@ -85,6 +89,7 @@ class FlexMock
   # Ignore all undefined (missing) method calls.
   def should_ignore_missing
     @ignore_missing = true
+    self
   end
   alias mock_ignore_missing should_ignore_missing
 
@@ -95,10 +100,13 @@ class FlexMock
 
   # Handle missing methods by attempting to look up a handler.
   def method_missing(sym, *args, &block)
+    @calls << [sym, block_given? ? args + [block] : args]
     flexmock_wrap do
       if handler = @expectations[sym]
         args << block  if block_given?
         handler.call(*args)
+      elsif @base_class && @base_class.instance_methods.include?(sym)
+        FlexMock.undefined
       elsif @ignore_missing
         FlexMock.undefined
       else
@@ -126,6 +134,27 @@ class FlexMock
     @expectations[method_name]
   end
 
+  def flexmock_spies_on(base_class)
+    @base_class = base_class
+  end
+
+  def flexmock_was_called_with?(sym, args, options={})
+    count = 0
+    @calls.each { |call_sym, call_args, call_block|
+      count += 1 if (call_sym == sym) && ArgumentMatching.all_match?(args, call_args)
+    }
+    if options[:times]
+      result = count == options[:times]
+    else
+      result = count > 0
+    end
+    result
+  end
+
+  def flexmock_invoke_original(sym, args)
+    return FlexMock.undefined
+  end
+
   # Override the built-in +method+ to include the mocked methods.
   def method(sym)
     @expectations[sym] || super
@@ -162,9 +191,10 @@ class FlexMock
       result = Expectation.new(self, sym)
       @expectations[sym] << result
       override_existing_method(sym) if flexmock_respond_to?(sym)
+      result = ExplicitNeeded.new(result, sym, @base_class) if
+        @base_class && ! @base_class.instance_methods.include?(sym)
       result
     end
-    @last_expectation
   end
 
   # Declare that the mock object should expect methods by providing a

data/lib/flexmock/core_class_methods.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #---
-# Copyright 2003-2011 by Jim Weirich (jim@weirichhouse.org).
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
 # All rights reserved.
 
 # Permission is granted for use, copying, modification, distribution,

data/lib/flexmock/default_framework_adapter.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #---
-# Copyright 2003-2011 by Jim Weirich (jim@weirichhouse.org).
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
 # All rights reserved.
 
 # Permission is granted for use, copying, modification, distribution,

data/lib/flexmock/deprecated_methods.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #---
-# Copyright 2003-2011 by Jim Weirich (jim@weirichhouse.org).
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
 # All rights reserved.
 #
 # Permission is granted for use, copying, modification, distribution,

data/lib/flexmock/errors.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #---
-# Copyright 2003-2011 by Jim Weirich (jim@weirichhouse.org).
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
 # All rights reserved.
 #
 # Permission is granted for use, copying, modification, distribution,

data/lib/flexmock/expectation.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #---
-# Copyright 2003-2011 by Jim Weirich (jim@weirichhouse.org).
+# Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
 # All rights reserved.
 
 # Permission is granted for use, copying, modification, distribution,
@@ -10,6 +10,7 @@
 #+++
 
 require 'flexmock/noop'
+require 'flexmock/argument_matching'
 
 class FlexMock
 
@@ -127,18 +128,7 @@ class FlexMock
     # Does the argument list match this expectation's argument
     # specification.
     def match_args(args)
-      # TODO: Rethink this:
-      # return false if @expected_args.nil?
-      return true if @expected_args.nil?
-      return false if args.size != @expected_args.size
-      (0...args.size).all? { |i| match_arg(@expected_args[i], args[i]) }
-    end
-
-    # Does the expected argument match the corresponding actual value.
-    def match_arg(expected, actual)
-      expected === actual ||
-      expected == actual ||
-      ( Regexp === expected && expected === actual.to_s )
+      ArgumentMatching.all_match?(@expected_args, args)
     end
 
     # Declare that the method should expect the given argument list.
@@ -268,6 +258,12 @@ class FlexMock
     end
     alias :throws :and_throw
 
+    def pass_thru
+      and_return { |*args|
+        @mock.flexmock_invoke_original(@sym, args)
+      }
+    end
+
     # Declare that the method may be called any number of times.
     def zero_or_more_times
       at_least.never
@@ -385,6 +381,12 @@ class FlexMock
     end
     private :define_ordered
 
+    # No-op for allowing explicit calls when explicit not explicitly
+    # needed.
+    def explicit
+      self
+    end
+
     def by_default
       expectations = mock.flexmock_expectations_for(@sym)
       expectations.defaultify_expectation(self) if expectations