bourne 1.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Joe Ferris and thoughtbot, inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,59 @@
+= Bourne
+
+Bourne extends mocha to allow detailed tracking and querying of stub and mock
+invocations. It allows test spies using the have_received rspec matcher and
+assert_received for Test::Unit. Bourne was extracted from jferris-mocha, a fork
+of mocha that adds test spies.
+
+== Test Spies
+
+Test spies are a form of test double that preserves the normal four-phase unit
+test order and allows separation of stubbing and verification.
+
+Using a test spy is like using a mocked expectation except that there are two steps:
+
+1. Stub out a method for which you want to verify invocations
+2. Use an assertion or matcher to verify that the stub was invoked correctly
+
+== Examples
+
+  # rspec
+
+  mock.should have_received(:to_s)
+  Radio.should have_received(:new).with(1041)
+  radio.should have_received(:volume).with(11).twice
+  radio.should have_received(:off).never
+
+  # Test::Unit
+
+  assert_received(mock, :to_s)
+  assert_received(Radio, :new) {|expect| expect.with(1041) }
+  assert_received(radio, :volume) {|expect| expect.with(11).twice }
+  assert_received(radio, :off) {|expect| expect.never }
+
+See Mocha::API for more information.
+
+== Download
+
+Rubygems:
+  gem install bourne
+
+Github: http://github.com/thoughtbot/bourne/tree/master
+
+== More Information
+
+* RDoc[http://rdoc.info/projects/thoughtbot/bourne]
+* Mocha mailing list[http://groups.google.com/group/mocha-developer?hl=en]
+* Issues[http://github.com/thoughtbot/bourne/issues]
+* GIANT ROBOTS SMASHING INTO OTHER GIANT ROBOTS[http://giantrobots.thoughtbot.com]
+
+== Author
+
+Bourne was written by Joe Ferris. Mocha was written by James Mead. Several of
+the test examples and helpers used in the Bourne test suite were copied
+directly from Mocha.
+
+Thanks to thoughtbot for inspiration, ideas, and funding. Thanks to James for
+writing mocha.
+
+Copyright 2010 Joe Ferris and thoughtbot[http://www.thoughtbot.com], inc.

data/Rakefile

@@ -0,0 +1,61 @@
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+desc "Run all tests"
+task 'default' => ['test:units', 'test:acceptance', 'test:performance']
+
+namespace 'test' do
+  unit_tests = FileList['test/unit/**/*_test.rb']
+  acceptance_tests = FileList['test/acceptance/*_test.rb']
+
+  desc "Run unit tests"
+  Rake::TestTask.new('units') do |t|
+    t.libs << 'test'
+    t.test_files = unit_tests
+  end
+
+  desc "Run acceptance tests"
+  Rake::TestTask.new('acceptance') do |t|
+    t.libs << 'test'
+    t.test_files = acceptance_tests
+  end
+
+  desc "Run performance tests"
+  task 'performance' do
+    require File.join(File.dirname(__FILE__), 'test', 'acceptance', 'stubba_example_test')
+    require File.join(File.dirname(__FILE__), 'test', 'acceptance', 'mocha_example_test')
+    iterations = 1000
+    puts "\nBenchmarking with #{iterations} iterations..."
+    [MochaExampleTest, StubbaExampleTest].each do |test_case|
+      puts "#{test_case}: #{benchmark_test_case(test_case, iterations)} seconds."
+    end
+  end
+end
+
+def benchmark_test_case(klass, iterations)
+  require 'benchmark'
+  require 'test/unit/ui/console/testrunner'
+  begin
+    require 'test/unit/ui/console/outputlevel'
+    silent_option = { :output_level => Test::Unit::UI::Console::OutputLevel::SILENT }
+  rescue LoadError
+    silent_option = Test::Unit::UI::SILENT
+  end
+  time = Benchmark.realtime { iterations.times { Test::Unit::UI::Console::TestRunner.run(klass, silent_option) } }
+end
+
+eval("$specification = #{IO.read('bourne.gemspec')}")
+Rake::GemPackageTask.new($specification) do |package|
+  package.need_zip = true
+  package.need_tar = true
+end
+
+desc 'Generate documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Bourne'
+  rdoc.options << '--line-numbers' << "--main" << "README"
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/bourne.rb

@@ -0,0 +1,2 @@
+require 'mocha'
+require 'bourne/api'

data/lib/bourne/api.rb

@@ -0,0 +1,82 @@
+require 'mocha/api'
+require 'bourne/mockery'
+
+module Mocha # :nodoc:
+  module API
+    # Asserts that the given mock received the given method.
+    #
+    # Examples:
+    #
+    #   assert_received(mock, :to_s)
+    #   assert_received(Radio, :new) {|expect| expect.with(1041) }
+    #   assert_received(radio, :volume) {|expect| expect.with(11).twice }
+    def assert_received(mock, expected_method_name)
+      matcher = have_received(expected_method_name)
+      yield(matcher) if block_given?
+      assert matcher.matches?(mock), matcher.failure_message
+    end
+
+    class HaveReceived #:nodoc:
+      def initialize(expected_method_name)
+        @expected_method_name = expected_method_name
+        @expectations = []
+      end
+
+      def method_missing(method, *args, &block)
+        @expectations << [method, args, block]
+        self
+      end
+
+      def matches?(mock)
+        if mock.respond_to?(:mocha)
+          @mock = mock.mocha
+        else
+          @mock = mock
+        end
+
+        @expectation = Expectation.new(@mock, @expected_method_name)
+        @expectations.each do |method, args, block|
+          @expectation.send(method, *args, &block)
+        end
+        @expectation.invocation_count = invocation_count
+        @expectation.verified?
+      end
+      
+      def failure_message
+        @expectation.mocha_inspect
+      end
+
+      private
+
+      def invocation_count
+        matching_invocations.size
+      end
+
+      def matching_invocations
+        invocations.select do |invocation|
+          @expectation.match?(invocation.method_name, *invocation.arguments)
+        end
+      end
+
+      def invocations
+        Mockery.instance.invocations.select do |invocation|
+          invocation.mock.equal?(@mock)
+        end
+      end
+    end
+
+    # :call-seq:
+    #   should have_received(method).with(arguments).times(times)
+    #
+    # Ensures that the given mock received the given method.
+    #
+    # Examples:
+    #
+    #   mock.should have_received(:to_s)
+    #   Radio.should have_received(:new).with(1041)
+    #   radio.should have_received(:volume).with(11).twice
+    def have_received(expected_method_name)
+      HaveReceived.new(expected_method_name)
+    end
+  end
+end

data/lib/bourne/expectation.rb

@@ -0,0 +1,23 @@
+require 'mocha/expectation'
+
+module Mocha # :nodoc:
+  # Extends Mocha::Expectation to record the full arguments and count whenver a
+  # stubbed or mocked method is invoked.
+  class Expectation # :nodoc:
+    attr_accessor :invocation_count
+
+    def invoke_with_args(args, &block)
+      Mockery.instance.invocation(@mock, method_name, args)
+      invoke_without_args(&block)
+    end
+
+    alias_method :invoke_without_args, :invoke
+    alias_method :invoke, :invoke_with_args
+
+    private
+
+    def method_name
+      @method_matcher.expected_method_name
+    end
+  end
+end

data/lib/bourne/invocation.rb

@@ -0,0 +1,14 @@
+module Mocha # :nodoc:
+  # Used internally by Bourne extensions to Mocha. Represents a single
+  # invocation of a stubbed or mocked method. The mock, method name, and
+  # arguments are recorded and can be used to determine how a method was
+  # invoked.
+  class Invocation
+    attr_reader :mock, :method_name, :arguments
+    def initialize(mock, method_name, arguments)
+      @mock        = mock
+      @method_name = method_name
+      @arguments   = arguments
+    end
+  end
+end

data/lib/bourne/mock.rb

@@ -0,0 +1,23 @@
+require 'mocha/mock'
+require 'bourne/expectation'
+
+module Mocha # :nodoc:
+  # Overwrites #method_missing on Mocha::Mock so pass arguments to
+  # Mocha::Expectation#invoke so that an Invocation can be created.
+  class Mock # :nodoc:
+    def method_missing(symbol, *arguments, &block)
+      if @responder and not @responder.respond_to?(symbol)
+        raise NoMethodError, "undefined method `#{symbol}' for #{self.mocha_inspect} which responds like #{@responder.mocha_inspect}"
+      end
+      if matching_expectation_allowing_invocation = @expectations.match_allowing_invocation(symbol, *arguments)
+        matching_expectation_allowing_invocation.invoke(arguments, &block)
+      else
+        if (matching_expectation = @expectations.match(symbol, *arguments)) || (!matching_expectation && !@everything_stubbed)
+          message = UnexpectedInvocation.new(self, symbol, *arguments).to_s
+          message << Mockery.instance.mocha_inspect
+          raise ExpectationError.new(message, caller)
+        end
+      end
+    end
+  end
+end

data/lib/bourne/mockery.rb

@@ -0,0 +1,19 @@
+require 'mocha/mockery'
+require 'bourne/mock'
+require 'bourne/invocation'
+
+module Mocha
+  # Used internally by Bourne extensions to Mocha when recording invocations of
+  # stubbed and mocked methods. You shouldn't need to interact with this module
+  # through normal testing, but you can access the full list of invocations
+  # directly if necessary.
+  class Mockery
+    def invocation(mock, method_name, args)
+      invocations << Invocation.new(mock, method_name, args)
+    end
+
+    def invocations
+      @invocations ||= []
+    end
+  end
+end

data/test/acceptance/acceptance_test_helper.rb

@@ -0,0 +1,38 @@
+require File.expand_path('../../test_helper', __FILE__)
+require 'test_runner'
+require 'mocha/configuration'
+
+module AcceptanceTest
+  
+  class FakeLogger
+  
+    attr_reader :warnings
+    
+    def initialize
+      @warnings = []
+    end
+    
+    def warn(message)
+      @warnings << message
+    end
+  
+  end
+  
+  attr_reader :logger
+
+  include TestRunner
+  
+  def setup_acceptance_test
+    Mocha::Configuration.reset_configuration
+    @logger = FakeLogger.new
+    mockery = Mocha::Mockery.instance
+    @original_logger = mockery.logger
+    mockery.logger = @logger
+  end
+  
+  def teardown_acceptance_test
+    Mocha::Configuration.reset_configuration
+    Mocha::Mockery.instance.logger = @original_logger
+  end
+  
+end

data/test/acceptance/mocha_example_test.rb

@@ -0,0 +1,98 @@
+require File.expand_path('../../test_helper', __FILE__)
+require 'mocha'
+
+class MochaExampleTest < Test::Unit::TestCase
+  
+  class Rover
+    
+    def initialize(left_track, right_track, steps_per_metre, steps_per_degree)
+      @left_track, @right_track, @steps_per_metre, @steps_per_degree = left_track, right_track, steps_per_metre, steps_per_degree
+    end
+    
+    def forward(metres)
+      @left_track.step(metres * @steps_per_metre)
+      @right_track.step(metres * @steps_per_metre)
+      wait
+    end
+    
+    def backward(metres)
+      forward(-metres)
+    end
+    
+    def left(degrees)
+      @left_track.step(-degrees * @steps_per_degree)
+      @right_track.step(+degrees * @steps_per_degree)
+      wait
+    end
+    
+    def right(degrees)
+      left(-degrees)
+    end
+    
+    def wait
+      while (@left_track.moving? or @right_track.moving?); end
+    end
+    
+  end
+  
+  def test_should_step_both_tracks_forward_ten_steps
+    left_track = mock('left_track')
+    right_track = mock('right_track')
+    steps_per_metre = 5
+    rover = Rover.new(left_track, right_track, steps_per_metre, nil)
+    
+    left_track.expects(:step).with(10)
+    right_track.expects(:step).with(10)
+    
+    left_track.stubs(:moving?).returns(false)
+    right_track.stubs(:moving?).returns(false)
+    
+    rover.forward(2)
+  end
+  
+  def test_should_step_both_tracks_backward_ten_steps
+    left_track = mock('left_track')
+    right_track = mock('right_track')
+    steps_per_metre = 5
+    rover = Rover.new(left_track, right_track, steps_per_metre, nil)
+    
+    left_track.expects(:step).with(-10)
+    right_track.expects(:step).with(-10)
+    
+    left_track.stubs(:moving?).returns(false)
+    right_track.stubs(:moving?).returns(false)
+    
+    rover.backward(2)
+  end
+  
+  def test_should_step_left_track_forwards_five_steps_and_right_track_backwards_five_steps
+    left_track = mock('left_track')
+    right_track = mock('right_track')
+    steps_per_degree = 5.0 / 90.0
+    rover = Rover.new(left_track, right_track, nil, steps_per_degree)
+    
+    left_track.expects(:step).with(+5)
+    right_track.expects(:step).with(-5)
+    
+    left_track.stubs(:moving?).returns(false)
+    right_track.stubs(:moving?).returns(false)
+    
+    rover.right(90)
+  end
+  
+  def test_should_step_left_track_backwards_five_steps_and_right_track_forwards_five_steps
+    left_track = mock('left_track')
+    right_track = mock('right_track')
+    steps_per_degree = 5.0 / 90.0
+    rover = Rover.new(left_track, right_track, nil, steps_per_degree)
+    
+    left_track.expects(:step).with(-5)
+    right_track.expects(:step).with(+5)
+    
+    left_track.stubs(:moving?).returns(false)
+    right_track.stubs(:moving?).returns(false)
+    
+    rover.left(90)
+  end
+  
+end