handoff 0.0.1

data/README

@@ -0,0 +1,10 @@
+Handoff provides a fluent interface for testing simple delegation.  The Ruby 
+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/).
+
+Here's example_test.rb to give you an idea of what your tests will look like:
+
+ :include: test/example_test.rb

data/lib/handoff/argument_normalizer.rb

@@ -0,0 +1,20 @@
+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
+  module ArgumentNormalizer
+  
+    def to_method_map
+      return self.first if self.size == 1 && self.first.is_a?(Hash)
+      to_self_referencing_hash
+    end
+    
+    def to_self_referencing_hash
+      hash = Hash.new
+      self.each {|sym| hash[sym]=sym}
+      hash
+    end
+  
+  end
+end

data/lib/handoff/assertion.rb

@@ -0,0 +1,70 @@
+require 'handoff/argument_normalizer'
+
+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.
+  class Assertion
+    
+    attr_reader :method_map
+    attr_reader :object_under_test
+    private :method_map, :object_under_test
+    
+    # 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
+    
+    # Creates an instance of +class_under_test+ with no arguments and uses it
+    # as the object under test.
+    def from_any class_under_test
+      from(class_under_test.new)
+    end
+    
+    # Specifies the object being tested, returning self.
+    def from object_under_test
+      @object_under_test = object_under_test
+      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)
+      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.
+    # 
+    # :call-seq: for_methods(:delegating_method1, :delegating_method2, ...)
+    #            for_methods({:delegating_method1 => :target_method1, :delegating_method2 => :target_method2})
+    # 
+    # +args+:: symbols representing the delegating methods if they are not renamed, or
+    #          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
+    end
+    alias for_method  for_methods
+    
+    private
+    def conduct
+      @mock_delegate.called!
+      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])
+      end
+      method_map.each_pair do |delegating_method, target|
+        actual = object_under_test.send(delegating_method)
+        unless actual.equal? expected_returns[delegating_method]
+          raise "expected #{delegating_method.to_s} to return #{expected_returns[method]}, but was #{actual}"
+        end
+      end
+    end
+    
+  end
+end

data/lib/handoff.rb

@@ -0,0 +1,18 @@
+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 
+# a new Handoff::Assertion.
+# 
+# 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'))
+  end
+end
+
+Test::Unit::TestCase.send :include, Handoff

data/test/example_test.rb

@@ -0,0 +1,41 @@
+# 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.
+class Foo
+  require 'forwardable'
+  extend Forwardable
+  def_delegators :bar, :baz, :bat
+  def_delegator :bar, :baq, :bar_baq
+  def_delegator :bar, :ban, :bar_ban
+  def bar
+    @bar ||= BarFactory.create_for(Foo) # gets the delegate ... this is not what we're testing
+  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 'stubba' # ditto
+
+class ExampleTest < Test::Unit::TestCase
+  
+  def test_using_from_and_single_method
+    assert_handoff.from(Foo.new).to(:bar).for_method(:baz)
+  end
+  
+  def test_using_from_any_and_multiple_methods
+    assert_handoff.from_any(Foo).to(:bar).for_methods(:baz, :bat)
+  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)
+  end
+end

data/test/handoff/argument_normalizer_test.rb

@@ -0,0 +1,23 @@
+require 'test/unit'
+require File.dirname(__FILE__) + '/../../lib/handoff/argument_normalizer'
+
+module Handoff
+  class ArgumentNormalizerTest < Test::Unit::TestCase
+  
+    def test_should_return_hash_at_front_of_one_element_array
+      hash = {}
+      assert_same hash, [hash].extend(ArgumentNormalizer).to_method_map
+    end
+    
+    def test_should_return_self_referencing_hash_for_array_of_symbols
+      args = [:bar, :foo].extend(ArgumentNormalizer)
+      assert_equal({:foo => :foo, :bar => :bar}, args.to_method_map)
+    end
+    
+    def test_should_return_self_referencing_hash_for_one_element_array_with_symbol
+      args = [:foo].extend(ArgumentNormalizer)
+      assert_equal({:foo => :foo}, args.to_method_map)
+    end
+  
+  end
+end

data/test/handoff/assertion_test.rb

@@ -0,0 +1,40 @@
+require 'test/unit'
+require File.dirname(__FILE__) + '/../test_helper'
+require File.dirname(__FILE__) + '/../../lib/handoff/assertion'
+require 'rubygems'
+require 'mocha'
+require 'stubba'
+
+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)
+    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)
+        extend Forwardable
+        def_delegator :asdf, :meth
+        attr_reader :asdf
+      EOS
+      mock_delegate = mock
+      object_under_test = cut.new
+      Assertion.new(mock_delegate).from(object_under_test).to(:asdf).for_method(:meth)
+      assert_equal :asdf, object_under_test.mocha.expectations.first.method_name
+      assert_equal :meth, mock_delegate.expectations.last.method_name
+    end
+    
+  end
+end

data/test/handoff_test.rb

@@ -0,0 +1,17 @@
+require File.dirname(__FILE__) + '/test_helper'
+require 'rubygems'
+require 'mocha'
+require 'stubba'
+require File.dirname(__FILE__) + '/../lib/handoff'
+
+class HandoffTest < Test::Unit::TestCase
+  test 'should create a mock named "handoff delegate" and hand it to a new Assertion' do
+    given_name = nil
+    def self.mock name
+      assert_equal 'handoff delegate', name
+      :mock_return
+    end
+    Assertion.expects(:new).with(:mock_return).returns(:new_assertion)
+    assert_equal :new_assertion, assert_handoff
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+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.
+require_paths: 
+- lib
+email: ""
+homepage: http://handoff.rubyforge.org/
+rubyforge_project: 
+description: 
+autorequire: hand_off
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- John Hume
+files: 
+- lib/handoff
+- lib/handoff.rb
+- lib/handoff/argument_normalizer.rb
+- lib/handoff/assertion.rb
+- README
+test_files: 
+- test/example_test.rb
+- test/handoff_test.rb
+- test/handoff/argument_normalizer_test.rb
+- test/handoff/assertion_test.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- README
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+    version: