handoff 0.0.1 → 0.1.0

data/README

@@ -3,8 +3,9 @@ stdlib module +Forwardable+ makes implementing delegation simple and readable.
 Handoff is intended to make the code to test it just as simple and 
 readable.
 
-Handoff depends on Mocha and Stubba (http://mocha.rubyforge.org/).
+Handoff depends on Mocha and Stubba (http://mocha.rubyforge.org).
 
-Here's example_test.rb to give you an idea of what your tests will look like:
+Here's example_test.rb to give you an idea of what you can do:
 
  :include: test/example_test.rb
+

data/lib/handoff/argument_normalizer.rb

@@ -1,18 +1,15 @@
 module Handoff
-=begin rdoc
-Module mixed into a *args array to munge it into a hash keying delegating 
-method names to target method names.
-=end
+  # Handoff internal.
   module ArgumentNormalizer
   
     def to_method_map
-      return self.first if self.size == 1 && self.first.is_a?(Hash)
+      return first if size == 1 && first.respond_to?(:each_pair)
       to_self_referencing_hash
     end
     
     def to_self_referencing_hash
       hash = Hash.new
-      self.each {|sym| hash[sym]=sym}
+      each {|method_symbol| hash[method_symbol] = method_symbol}
       hash
     end
   

data/lib/handoff/assertion.rb

@@ -1,22 +1,28 @@
 require 'handoff/argument_normalizer'
+require 'handoff/usage_error'
 
 module Handoff
   # This is where the fluent stuff is.
   # Get an assertion by calling Handoff#assert_handoff.  Specify the delegating
-  # behavior with from or from_any, to, and for_method or for_methods.
+  # behavior with 
+  # * +from+ or +from_any+, 
+  # * +to+, 
+  # * +for+, +for_method+ or +for_methods+, and
+  # * (optionally) +with+ or +with_arguments+.
   class Assertion
     
+    # :stopdoc:
+    
     attr_reader :method_map
-    attr_reader :object_under_test
-    private :method_map, :object_under_test
+    attr_reader :delegator
+    private :method_map, :delegator
     
-    # Creates an expectation on the mock delegate that it will be touched later
-    # to give a failure if the user forgets to specify everything required.
     def initialize mock_delegate
       @mock_delegate = mock_delegate
-      @mock_delegate.expects(:called!)
     end
     
+    # :startdoc:
+    
     # Creates an instance of +class_under_test+ with no arguments and uses it
     # as the object under test.
     def from_any class_under_test
@@ -24,20 +30,20 @@ module Handoff
     end
     
     # Specifies the object being tested, returning self.
-    def from object_under_test
-      @object_under_test = object_under_test
+    def from delegator
+      @delegator = delegator
       self
     end
     
     # Specifies the accessor the object under test will use to acquire its delegate, 
     # returning self.
     def to(delegate_accessor)
-      @object_under_test.expects(delegate_accessor).at_least_once.returns(@mock_delegate)
+      @delegate_accessor = delegate_accessor
       self
     end
     
     # Tells the assertion what delegating methods to test and what methods in the delegate
-    # they should delegate to.  Then actually does the testing.
+    # they should delegate to.
     # 
     # :call-seq: for_methods(:delegating_method1, :delegating_method2, ...)
     #            for_methods({:delegating_method1 => :target_method1, :delegating_method2 => :target_method2})
@@ -46,25 +52,49 @@ module Handoff
     #          a Hash mapping methods in the delegating class to methods in the delegate.
     def for_methods(*args)
       @method_map = args.extend(ArgumentNormalizer).to_method_map
-      conduct
+      self
     end
-    alias for_method  for_methods
+    alias for_method for_methods
+    alias for for_methods
+    
+    def with_arguments *args
+      @args = args
+    end
+    alias with with_arguments
+    
+    # Specifies that the assertion should pass no arguments to the delegating method and 
+    # require that no arguments are sent to the target method.
+    # Equivalent to calling +with_arguments+ with no arguments.
+    def with_no_arguments
+      with_arguments
+    end
+    
+    # :stopdoc:
     
-    private
     def conduct
-      @mock_delegate.called!
+      validate_sufficiently_specified
+      @delegator.expects(@delegate_accessor).at_least_once.returns(@mock_delegate)
       expected_returns = {}
       method_map.each_pair do |delegating_method, target|
         expected_returns[delegating_method] = "#{delegating_method.to_s}_return"
-        @mock_delegate.expects(target).returns(expected_returns[delegating_method])
+        expectation = @mock_delegate.expects(target).returns(expected_returns[delegating_method])
+        expectation.with(*@args) unless @args.nil?
       end
       method_map.each_pair do |delegating_method, target|
-        actual = object_under_test.send(delegating_method)
+        send_args = [delegating_method, @args].flatten
+        actual = delegator.send(*send_args)
         unless actual.equal? expected_returns[delegating_method]
-          raise "expected #{delegating_method.to_s} to return #{expected_returns[method]}, but was #{actual}"
+          raise "expected #{delegating_method.to_s} to return #{expected_returns[delegating_method]}, but was #{actual}"
         end
       end
     end
     
+    private
+    def validate_sufficiently_specified
+      raise UsageError, "Object under test must be specified with 'from' or 'from_any'" unless @delegator
+      raise UsageError, "Delegate accessor must be specified with 'to'" unless @delegate_accessor
+      raise UsageError, "Delegating methods must be specified with 'for_method' or 'for_methods'" unless @method_map
+    end
+    # :startdoc:
   end
 end

data/lib/handoff/usage_error.rb

@@ -0,0 +1,4 @@
+module Handoff
+  class UsageError < RuntimeError
+  end
+end

data/lib/handoff.rb

@@ -1,18 +1,40 @@
 require 'handoff/assertion'
-require 'test/unit'
 
 # +require+ (or +require_gem+) 'handoff' and #assert_handoff can 
-# be called from any +Test::Unit::TestCase+ test method to create 
+# be called from any Test::Unit::TestCase test method to create 
 # a new Handoff::Assertion.
 # 
-# After defining Handoff, This file includes it in Test::Unit::TestCase.
+# After defining Handoff, this file includes it in Test::Unit::TestCase.
 module Handoff
   
   # Creates an Assertion, handing a it a mock named 'handoff delegate' on which
   # expectations will be set.
   def assert_handoff
-    Handoff::Assertion.new(self.mock('handoff delegate'))
+    a = Handoff::Assertion.new(self.mock('handoff delegate'))
+    handoff_assertions << a
+    a
   end
+  
+  def handoff_assertions
+    @handoff_assertions ||= []
+  end
+  
+  def conduct_and_clear_handoffs
+    begin
+      handoff_assertions.each {|a| a.conduct }
+    ensure
+      handoff_assertions.clear
+    end
+  end
+  
+  def self.included(base)
+    base.class_eval do
+      add_teardown_method :conduct_and_clear_handoffs
+    end
+  end
+  
 end
 
-Test::Unit::TestCase.send :include, Handoff
+class Test::Unit::TestCase
+  include Handoff unless ancestors.include?(Handoff)
+end

data/test/example_test.rb

@@ -1,30 +1,32 @@
 # This example is only helpful if you're familiar with Forwardable from the 
 # stdlib, which you should be if you're coding delegating behavior in Ruby.  
-# Here comes an example of something you might have in your code base, but 
-# haven't managed to test readably.  You might have some code like this that's 
-# tested in very long methods which either repeat but varying set-ups
-# Foo is a simple delegating class, which normally wouldn't live in 
-# your test.
+# 
+# Foo is a simple delegating class.  We want to specify that delegation in
+# its unit test.
 class Foo
   require 'forwardable'
   extend Forwardable
   def_delegators :bar, :baz, :bat
   def_delegator :bar, :baq, :bar_baq
   def_delegator :bar, :ban, :bar_ban
+  
+  # Foo#bar gets the delegate.  This is not what Handoff tests.
+  # Rather, Handoff will mock this method and ensure that the 
+  # delegating methods defined above use it correctly.
   def bar
-    @bar ||= BarFactory.create_for(Foo) # gets the delegate ... this is not what we're testing
+    @bar ||= BarFactory.create
   end
 end
 
 require 'test/unit'
 require 'rubygems'
 
-require File.dirname(__FILE__) + '/../lib/handoff' # I require it this way because I don't want the installed gem.
-# require 'handoff' # this is how you'd require handoff (or do require_gem w/ a version).
-
-require 'mocha' # you need to require mocha and stubba in your test
+require 'mocha' # You need to require mocha and stubba in your test.
 require 'stubba' # ditto
 
+require File.dirname(__FILE__) + '/../lib/handoff' # I require it this way because I don't want the installed gem.
+# require 'handoff' # This is how you'd require handoff (or do require_gem w/ a version).
+
 class ExampleTest < Test::Unit::TestCase
   
   def test_using_from_and_single_method
@@ -36,6 +38,15 @@ class ExampleTest < Test::Unit::TestCase
   end
   
   def test_showing_delegating_methods_with_names_different_than_their_delegate_methods
-    assert_handoff.from(Foo.new).to(:bar).for_methods(:bar_baq => :baq, :bar_ban => :ban)
+    assert_handoff.from(Foo.new).to(:bar).for(:bar_baq => :baq, :bar_ban => :ban)
   end
+  
+  def test_specifying_args
+    assert_handoff.from(Foo.new).to(:bar).for(:baz).with('arg1', 2, :three)
+  end
+  
+  def test_specifying_some_arg
+    assert_handoff.from(Foo.new).to(:bar).for(:baz).with_no_arguments
+  end
+  
 end

data/test/handoff/assertion_test.rb

@@ -9,32 +9,88 @@ module Handoff
   class AssertionTest < Test::Unit::TestCase
     
     test 'should construct instance to test and return self when from_any is called' do
-      mock_class = mock(:new => nil)
-      mock_delegate = mock
-      assertion = Assertion.new(mock_delegate)
-      mock_delegate.expectations.clear
-      assert_same assertion, assertion.from_any(mock_class)
+      assertion = Assertion.new(nil)
+      assert_same assertion, assertion.from_any(mock('class under test', :new => nil))
     end
     
-    test 'should create expectation on creation to guard against incomplete usage' do
-      mock_delegate = mock
-      Assertion.new(mock_delegate)
-      assert_equal :called!, mock_delegate.expectations.first.method_name
-      mock_delegate.expectations.clear
-    end
-    
-    test 'should create expectations on mock_delegate and object under test once fully specified' do
-      cut = define_class(Object, <<-EOS)
+    test 'should create expectations on mock_delegate and object under test upon conduct' do
+      cut = Class.new do
         extend Forwardable
         def_delegator :asdf, :meth
         attr_reader :asdf
-      EOS
+      end
       mock_delegate = mock
       object_under_test = cut.new
-      Assertion.new(mock_delegate).from(object_under_test).to(:asdf).for_method(:meth)
+      assertion = Assertion.new(mock_delegate).from(object_under_test).to(:asdf).for_method(:meth)
+      assertion.conduct
       assert_equal :asdf, object_under_test.mocha.expectations.first.method_name
       assert_equal :meth, mock_delegate.expectations.last.method_name
     end
     
+    test 'should create mock_delegate expectation with arguments when supplied' do
+      delegator = Class.new do
+        extend Forwardable
+        def_delegator :delegate, :meth
+        attr_reader :delegate
+      end.new
+      assertion = Assertion.new(mock_delegate = mock).from(delegator).to(:delegate).for(:meth)
+      assertion.with('arg1', :arg2, 3)
+      assertion.conduct
+      assert_true mock_delegate.expectations.first.match?(:meth, 'arg1', :arg2, 3)
+      assert_false mock_delegate.expectations.first.match?(:meth)
+      assert_false mock_delegate.expectations.first.match?(:meth, 'arg1')
+    end
+    
+    { 
+      :with => lambda {|assertion| assertion.with},
+      :with_no_arguments => lambda {|assertion| assertion.with_no_arguments}
+    }.each_pair do |method, proc|
+      test "should force no args when #{method} is used to specify none" do
+        delegator = Class.new do
+          extend Forwardable
+          def_delegator :delegate, :meth
+          attr_reader :delegate
+        end.new
+        assertion = Assertion.new(mock_delegate = mock).from(delegator).to(:delegate).for(:meth)
+        proc.call(assertion)
+        assertion.conduct
+        assert_true mock_delegate.expectations.first.match?(:meth)
+        assert_false mock_delegate.expectations.first.match?(:meth, 'arg1')
+      end
+    end
+    
+    test 'should allow for args or no args if nothing specified' do
+      delegator = Class.new do
+        extend Forwardable
+        def_delegator :delegate, :meth
+        attr_reader :delegate
+      end.new
+      assertion = Assertion.new(mock_delegate = mock).from(delegator).to(:delegate).for(:meth)
+      assertion.conduct
+      assert_true mock_delegate.expectations.first.match?(:meth)
+      assert_true mock_delegate.expectations.first.match?(:meth, 'arg1')
+    end
+    
+    test 'validates presence of delegator, delegate accessor, and delegating methods' do
+      assertion = Assertion.new(mock).from(nil).to(:asdf).for_method(:meth)
+      assert_raises(UsageError) { assertion.conduct }
+      
+      assertion = Assertion.new(mock).from("whatever").to(nil).for_method(:meth)
+      assert_raises(UsageError) { assertion.conduct }
+      
+      assertion = Assertion.new(mock).from("whatever").to(:asdf)
+      assert_raises(UsageError) { assertion.conduct }
+    end
+    
+    test 'for, for_method, and for_methods are aliases' do
+      a = Assertion.new nil
+      assert_equal a.method(:for_methods), a.method(:for_method)
+      assert_equal a.method(:for_methods), a.method(:for)
+    end
+    
+    test 'with_arguments and with are aliases' do
+      a = Assertion.new nil
+      assert_equal a.method(:with_arguments), a.method(:with)
+    end
   end
-end
+end

data/test/handoff_test.rb

@@ -13,5 +13,20 @@ class HandoffTest < Test::Unit::TestCase
     end
     Assertion.expects(:new).with(:mock_return).returns(:new_assertion)
     assert_equal :new_assertion, assert_handoff
+    assert_equal :new_assertion, handoff_assertions.delete(:new_assertion)
+    assert_true handoff_assertions.empty?
+  end
+  
+  test 'should add a teardown method for conducting handoff assertions' do
+    assert_true self.class.teardown_methods.include?(:conduct_and_clear_handoffs)
+  end
+  
+  test 'should conduct each assertion in conduct_and_clear_handoffs' do
+    handoff_assertions << assertion1 = mock(:conduct => nil)
+    handoff_assertions << assertion2 = mock(:conduct => nil)
+    conduct_and_clear_handoffs
+    assert_true handoff_assertions.empty?
+    assertion1.verify
+    assertion2.verify
   end
 end

data/test/test_helper_test.rb

@@ -0,0 +1,10 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class TestHelperTest < Test::Unit::TestCase
+  
+  test 'assert_true passes only for true, not for non-nulls' do
+    assert_true true
+    assert_raises(Test::Unit::AssertionFailedError) { assert_true 'foo' }
+  end
+  
+end

metadata

@@ -3,9 +3,9 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: handoff
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
-date: 2007-01-17 00:00:00 -05:00
-summary: Handoff is a fluent interface for making test assertions about simple delegation.
+  version: 0.1.0
+date: 2007-02-17 00:00:00 -05:00
+summary: Handoff is a fluent interface for making test assertions about delegation.
 require_paths: 
 - lib
 email: ""
@@ -33,10 +33,12 @@ files:
 - lib/handoff.rb
 - lib/handoff/argument_normalizer.rb
 - lib/handoff/assertion.rb
+- lib/handoff/usage_error.rb
 - README
 test_files: 
 - test/example_test.rb
 - test/handoff_test.rb
+- test/test_helper_test.rb
 - test/handoff/argument_normalizer_test.rb
 - test/handoff/assertion_test.rb
 rdoc_options: []