surrogate 0.4.3 → 0.5.0

data/Readme.md

@@ -127,9 +127,6 @@ player.will_move 1, 9, 3
 player.move # => 1
 player.move # => 9
 player.move # => 3
-
-# then back to default behaviour (or error if none provided)
-player.move # => 20
 ```
 
 You can define **initialize**
@@ -260,8 +257,8 @@ After you've implemented the real version of your mock (assuming a [top-down](ht
 how do you prevent your real object from getting out of synch with your mock?
 
 Assert that your mock has the **same interface** as your real class.
-This will fail if the mock inherits methods methods not on the real class. And it will fail
-if the real class has or lacks any methods defined on the mock or inherited by the mock.
+This will fail if the mock inherits methods which are not on the real class. It will also fail
+if the real class has any methods which have not been defined on the mock or inherited by the mock.
 
 Presently, it will ignore methods defined directly in the mock (as it adds quite a few of its own methods,
 and generally considers them to be helpers). In a future version, you will be able to tell it to treat other methods
@@ -325,6 +322,46 @@ MockUser.should_not substitute_for User, subset: true
 ```
 
 
+Blocks
+------
+
+When your method is invoked with a block, you can make assertions about the block.
+
+_Note: Right now, block error messages have not been addressed (which means they are probably confusing as shit)_
+
+Before/after hooks (make assertions here)
+
+```ruby
+class MockService
+  Surrogate.endow self
+  define(:create) {}
+end
+
+describe 'something that creates a user through the service' do
+  let(:old_id) { 12 }
+  let(:new_id) { 123 }
+
+  it 'updates the user_id and returns the old_id' do
+    user_id = old_id
+    service = MockService.new
+
+    service.create do |user|
+      to_return = user_id
+      user_id = user[:id]
+      to_return
+    end
+
+    service.should have_been_told_to(:create).with { |block|
+      block.call_with({id: new_id})              # this will be given to the block
+      block.returns old_id                       # provide a return value, or a block that receives the return value (where you can make assertions)
+      block.before { user_id.should == old_id }  # assertions about state of the world before the block is called
+      block.after  { user_id.should == new_id }  # assertions about the state of the world after the block is called
+    }
+  end
+end
+```
+
+
 How do I introduce my mocks?
 ============================
 
@@ -356,22 +393,27 @@ Special Thanks
 TODO
 ----
 
+* Add proper failure messages for block invocations
+* Add `was told_to` syntax
+* Add support for predicates
 * Add a better explanation for motivations
 * Figure out whether I'm supposed to be using clone or dup for the object -.^ (looks like there may also be an `initialize_copy` method I can take advantage of instead of crazy stupid shit I'm doing now)
 * don't blow up when delegating to the Object#initialize with args
-* queues should not reset when done, they should raise
+* config: rspec_mocks loaded, whether unprepared blocks should raise or just return nil
+* extract surrogate/rspec into its own gem
+* support subset-substitutabilty not being able to touch real methods (e.g. #respond_to?)
+* Add a last_instance option so you don't have to track it explicitly
 
 
 Future Features
 ---------------
 
+* figure out how to talk about callbacks like #on_success
 * have some sort of reinitialization that can hook into setup/teardown steps of test suite
 * Support arity checking as part of substitutability
-* Support for blocks
 * Ability to disassociate the method name from the test (e.g. you shouldn't need to change a test just because you change a name)
-* declare normal methods as being part of the API (e.g. for inheritance)
+* ability to declare normal methods as being part of the API
+* ability to declare a define that uses the overridden method as the body, but can still act like an api method
 * assertions for order of invocations & methods
 * class generator? (supports a top-down style of development for when you write your mocks before you write your implementations)
-* extract surrogate/rspec into its own gem?
 * deal with hard dependency on rspec-mocks
-* support subset-substitutabilty not being able to touch real methods (e.g. #respond_to?)

data/lib/surrogate/hatchling.rb

@@ -1,5 +1,6 @@
 class Surrogate
-  UnknownMethod = Class.new StandardError
+  SurrogateError = Class.new StandardError
+  UnknownMethod  = Class.new SurrogateError
 
 
   # This contains the unique behaviour for each instance
@@ -16,9 +17,10 @@ class Surrogate
     end
 
     def invoke_method(method_name, args, &block)
-      invoked_methods[method_name] << args
-      return get_default method_name, args, &block unless has_ivar? method_name
-      Value.factory(get_ivar method_name).value(self, method_name)
+      invocation = Invocation.new(args, &block)
+      invoked_methods[method_name] << invocation
+      return get_default method_name, invocation, &block unless has_ivar? method_name
+      Value.factory(get_ivar method_name).value(method_name)
     end
 
     def prepare_method(method_name, args, &block)
@@ -29,7 +31,28 @@ class Surrogate
       invoked_methods[method_name]
     end
 
-    # maybe these four should be extracted into their own class
+  private
+
+    def invoked_methods
+      @invoked_methods ||= Hash.new do |hash, method_name|
+        must_know method_name
+        hash[method_name] = []
+      end
+    end
+
+    def get_default(method_name, invocation)
+      api_methods[method_name].default instance, invocation do
+        raise UnpreparedMethodError, "#{method_name} has been invoked without being told how to behave"
+      end
+    end
+
+    def must_know(method_name)
+      return if api_methods.has_key? method_name
+      known_methods = api_methods.keys.map(&:to_s).map(&:inspect).join ', '
+      raise UnknownMethod, "doesn't know \"#{method_name}\", only knows #{known_methods}"
+    end
+
+    # maybe these ivar methods should be extracted into their own class
     def has_ivar?(method_name)
       instance.instance_variable_defined? ivar_for method_name
     end
@@ -55,26 +78,6 @@ class Surrogate
       end
     end
 
-  private
-
-    def invoked_methods
-      @invoked_methods ||= Hash.new do |hash, method_name|
-        must_know method_name
-        hash[method_name] = []
-      end
-    end
-
-    def get_default(method_name, args, &block)
-      api_methods[method_name].default instance, args, block do
-        raise UnpreparedMethodError, "#{method_name} has been invoked without being told how to behave"
-      end
-    end
-
-    def must_know(method_name)
-      return if api_methods.has_key? method_name
-      known_methods = api_methods.keys.map(&:to_s).map(&:inspect).join ', '
-      raise UnknownMethod, "doesn't know \"#{method_name}\", only knows #{known_methods}"
-    end
   end
 end
 

data/lib/surrogate/invocation.rb

@@ -0,0 +1,17 @@
+class Surrogate
+  class Invocation
+    attr_accessor :args, :block
+
+    def initialize(args, &block)
+      self.args, self.block = args, block
+    end
+
+    def has_block?
+      !!block
+    end
+
+    def ==(invocation)
+      args == invocation.args && has_block? == invocation.has_block?
+    end
+  end
+end

data/lib/surrogate/options.rb

@@ -20,7 +20,7 @@ class Surrogate
       options
     end
 
-    def default(instance, args, block, &no_default)
+    def default(instance, invocation, &no_default)
       if options.has_key? :default
         options[:default]
       elsif default_proc
@@ -31,7 +31,7 @@ class Surrogate
         # the options, then we only have to bind it to an instance and invoke
         BindableBlock.new(instance.class, &default_proc)
                      .bind(instance)
-                     .call(*args, &block)
+                     .call(*invocation.args, &invocation.block)
       else
         no_default.call
       end

data/lib/surrogate/rspec/abstract_failure_message.rb

@@ -0,0 +1,59 @@
+class Surrogate
+  module RSpec
+    class AbstractFailureMessage
+      class ArgsInspector
+        def self.inspect(invocation)
+          inspected_arguments = invocation.args.map { |argument| inspect_argument argument }
+          inspected_arguments << 'no args' if inspected_arguments.empty?
+          "`" << inspected_arguments.join(", ") << "'"
+        end
+
+        def self.inspect_argument(to_inspect)
+          if RSpec.rspec_mocks_loaded? && to_inspect.respond_to?(:description)
+            to_inspect.description
+          else
+            to_inspect.inspect
+          end
+        end
+      end
+
+      attr_accessor :method_name, :invocations, :with_filter, :times_predicate
+
+      def initialize(method_name, invocations, with_filter, times_predicate)
+        self.method_name     = method_name
+        self.invocations     = invocations
+        self.with_filter     = with_filter
+        self.times_predicate = times_predicate
+      end
+
+      def get_message
+        raise "I should have been overridden"
+      end
+
+      def times_invoked
+        invocations.size
+      end
+
+      def inspect_arguments(arguments)
+        # can we fix this as soon as an array enters the system instead of catching it here?
+        if arguments.kind_of? Invocation
+          ArgsInspector.inspect arguments
+        else
+          ArgsInspector.inspect Invocation.new arguments
+        end
+      end
+
+      def expected_invocation
+        with_filter.expected_invocation
+      end
+
+      def times_msg(n)
+        "#{n} time#{'s' unless n == 1}"
+      end
+
+      def expected_times_invoked
+        times_predicate.expected_times_invoked
+      end
+    end
+  end
+end

data/lib/surrogate/rspec/have_been_asked_for_its.rb

@@ -0,0 +1,78 @@
+require 'surrogate/rspec/invocation_matcher'
+
+class Surrogate
+  module RSpec
+    class HaveBeenAskedForIts < InvocationMatcher
+
+      class FailureMessageShouldDefault < AbstractFailureMessage
+        def get_message
+          "was never asked for its #{ method_name }"
+        end
+      end
+
+      class FailureMessageShouldWith < AbstractFailureMessage
+        def get_message
+          message = "should have been asked for its #{ method_name } with #{ inspect_arguments expected_invocation }, but "
+          if times_invoked.zero?
+            message << "was never asked"
+          else
+            inspected_invocations = invocations.map { |invocation| inspect_arguments invocation }
+            message << "got #{inspected_invocations.join ', '}"
+          end
+        end
+      end
+
+      class FailureMessageShouldTimes < AbstractFailureMessage
+        def get_message
+          "should have been asked for its #{ method_name } #{ times_msg expected_times_invoked }, but was asked #{ times_msg times_invoked }"
+        end
+      end
+
+      class FailureMessageWithTimes < AbstractFailureMessage
+        def get_message
+          message = "should have been asked for its #{ method_name } #{ times_msg expected_times_invoked } with #{ inspect_arguments expected_invocation }, but "
+          if times_invoked.zero?
+            message << "was never asked"
+          else
+            message << "was asked #{times_msg times_invoked}"
+          end
+        end
+      end
+
+      class FailureMessageShouldNotDefault < AbstractFailureMessage
+        def get_message
+          "shouldn't have been asked for its #{ method_name }, but was asked #{ times_msg times_invoked }"
+        end
+      end
+
+      class FailureMessageShouldNotWith < AbstractFailureMessage
+        def get_message
+          message = "should not have been asked for its #{ method_name } with #{ inspect_arguments expected_invocation }, but "
+          if times_invoked.zero?
+            message << "was never asked"
+          else
+            inspected_invocations = invocations.map { |invocation| inspect_arguments invocation }
+            message << "got #{inspected_invocations.join ', '}"
+          end
+        end
+      end
+
+      class FailureMessageShouldNotTimes < AbstractFailureMessage
+        def get_message
+          "shouldn't have been asked for its #{ method_name } #{ times_msg expected_times_invoked }, but was"
+        end
+      end
+
+      class FailureMessageShouldNotWithTimes < AbstractFailureMessage
+        def get_message
+          message = "should not have been asked for its #{ method_name } #{ times_msg expected_times_invoked } with #{ inspect_arguments expected_invocation }, "
+          if times_invoked.zero?
+             message << "was never asked"
+          else
+            message << "was asked #{times_msg times_invoked}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/surrogate/rspec/have_been_initialized_with.rb

@@ -0,0 +1,12 @@
+require 'surrogate/rspec/have_been_told_to'
+
+class Surrogate
+  module RSpec
+    class HaveBeenInitializedWith < HaveBeenToldTo
+      def initialize(*initialization_args, &block)
+        super :initialize
+        with *initialization_args, &block
+      end
+    end
+  end
+end

data/lib/surrogate/rspec/have_been_told_to.rb

@@ -0,0 +1,77 @@
+require 'surrogate/rspec/invocation_matcher'
+
+class Surrogate
+  module RSpec
+    class HaveBeenToldTo < InvocationMatcher
+      class FailureMessageShouldDefault < AbstractFailureMessage
+        def get_message
+          "was never told to #{ method_name }"
+        end
+      end
+
+      class FailureMessageShouldWith < AbstractFailureMessage
+        def get_message
+          message = "should have been told to #{ method_name } with #{ inspect_arguments expected_invocation }, but "
+          if times_invoked.zero?
+            message << "was never told to"
+          else
+            inspected_invocations = invocations.map { |invocation| inspect_arguments invocation }
+            message << "got #{inspected_invocations.join ', '}"
+          end
+        end
+      end
+
+      class FailureMessageShouldTimes < AbstractFailureMessage
+        def get_message
+          "should have been told to #{ method_name } #{ times_msg expected_times_invoked } but was told to #{ method_name } #{ times_msg times_invoked }"
+        end
+      end
+
+      class FailureMessageWithTimes < AbstractFailureMessage
+        def get_message
+          message = "should have been told to #{ method_name } #{ times_msg expected_times_invoked } with #{ inspect_arguments expected_invocation }, but "
+          if times_invoked.zero?
+            message << "was never told to"
+          else
+            message << "got it #{times_msg times_invoked}"
+          end
+        end
+      end
+
+      class FailureMessageShouldNotDefault < AbstractFailureMessage
+        def get_message
+          "shouldn't have been told to #{ method_name }, but was told to #{ method_name } #{ times_msg times_invoked }"
+        end
+      end
+
+      class FailureMessageShouldNotWith < AbstractFailureMessage
+        def get_message
+          message = "should not have been told to #{ method_name } with #{ inspect_arguments expected_invocation }, but "
+          if times_invoked.zero?
+            message << "was never told to"
+          else
+            inspected_invocations = invocations.map { |invocation| inspect_arguments invocation }
+            message << "got #{inspected_invocations.join ', '}"
+          end
+        end
+      end
+
+      class FailureMessageShouldNotTimes < AbstractFailureMessage
+        def get_message
+          "shouldn't have been told to #{ method_name } #{ times_msg expected_times_invoked }, but was"
+        end
+      end
+
+      class FailureMessageShouldNotWithTimes < AbstractFailureMessage
+        def get_message
+          message = "should not have been told to #{ method_name } #{ times_msg expected_times_invoked } with #{ inspect_arguments expected_invocation }, but "
+          if times_invoked.zero?
+             message << "was never told to"
+          else
+            message << "got it #{times_msg times_invoked}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/surrogate/rspec/invocation_matcher.rb

@@ -0,0 +1,81 @@
+require 'surrogate/rspec/abstract_failure_message'
+require 'surrogate/rspec/times_predicate'
+require 'surrogate/rspec/with_filter'
+
+class Surrogate
+  module RSpec
+    class InvocationMatcher
+      attr_accessor :times_predicate, :with_filter, :surrogate, :method_name
+
+      def initialize(method_name)
+        self.method_name     = method_name
+        self.times_predicate = TimesPredicate.new
+        self.with_filter     = WithFilter.new
+      end
+
+      def matches?(surrogate)
+        self.surrogate = surrogate
+        times_predicate.matches? filtered_args
+      end
+
+      def filtered_args
+        @filtered_args ||= with_filter.filter invocations
+      end
+
+      def invocations
+        surrogate.invocations(method_name)
+      end
+
+      def failure_message_for_should
+        raise "THIS METHOD SHOULD HAVE BEEN OVERRIDDEN"
+      end
+
+      def failure_message_for_should_not
+        raise "THIS METHOD SHOULD HAVE BEEN OVERRIDDEN"
+      end
+
+      def times(times_invoked)
+        @times_predicate = TimesPredicate.new(times_invoked, :==)
+        self
+      end
+
+      def with(*arguments, &expectation_block)
+        self.with_filter = WithFilter.new arguments, :args_must_match,  &expectation_block
+        arguments << expectation_block if expectation_block
+        self
+      end
+
+      def failure_message_for_should
+        message_for(
+          if times_predicate.default? && with_filter.default?
+            :FailureMessageShouldDefault
+          elsif times_predicate.default?
+            :FailureMessageShouldWith
+          elsif with_filter.default?
+            :FailureMessageShouldTimes
+          else
+            :FailureMessageWithTimes
+          end
+        )
+      end
+
+      def failure_message_for_should_not
+        message_for(
+          if times_predicate.default? && with_filter.default?
+            :FailureMessageShouldNotDefault
+          elsif times_predicate.default?
+            :FailureMessageShouldNotWith
+          elsif with_filter.default?
+            :FailureMessageShouldNotTimes
+          else
+            :FailureMessageShouldNotWithTimes
+          end
+        )
+      end
+
+      def message_for(failure_class_name)
+        self.class.const_get(failure_class_name).new(method_name, invocations, with_filter, times_predicate).get_message
+      end
+    end
+  end
+end

data/lib/surrogate/rspec/times_predicate.rb

@@ -0,0 +1,19 @@
+class Surrogate
+  module RSpec
+    class TimesPredicate
+      attr_accessor :expected_times_invoked, :comparer
+      def initialize(expected_times_invoked=0, comparer=:<)
+        self.expected_times_invoked = expected_times_invoked
+        self.comparer = comparer
+      end
+
+      def matches?(invocations)
+        expected_times_invoked.send comparer, invocations.size
+      end
+
+      def default?
+        expected_times_invoked == 0 && comparer == :<
+      end
+    end
+  end
+end

data/lib/surrogate/rspec/with_filter.rb

@@ -0,0 +1,123 @@
+class Surrogate
+  module RSpec
+    class WithFilter
+
+      class BlockAsserter
+        def initialize(definition_block)
+          @call_with = Invocation.new []
+          definition_block.call self
+        end
+
+        def call_with(*args, &block)
+          @call_with = Invocation.new args, &block
+        end
+
+        def returns(value=nil, &block)
+          @returns = block || lambda { |returned| returned.should == value }
+        end
+
+        def before(&block)
+          @before = block
+        end
+
+        def after(&block)
+          @after = block
+        end
+
+        def arity(n)
+          @arity = n
+        end
+
+        def matches?(block_to_test)
+          matches   = before_matches? block_to_test
+          matches &&= return_value_matches? block_to_test
+          matches &&= arity_matches? block_to_test
+          matches &&= after_matches? block_to_test
+          matches
+        end
+
+        private
+
+        # matches if no return specified, or returned value == specified value
+        def return_value_matches?(block_to_test)
+          returned_value = block_to_test.call(*@call_with.args, &@call_with.block)
+          @returns.call returned_value if @returns
+          true
+        rescue ::RSpec::Expectations::ExpectationNotMetError
+          false
+        end
+
+        # matches if the first time it is called, it raises nothing
+        def before_matches?(*)
+          @before_has_been_invoked || (@before && @before.call)
+        ensure
+          return @before_has_been_invoked = true unless $!
+        end
+
+        # matches if nothing is raised
+        def after_matches?(block_to_test)
+          @after && @after.call
+          true
+        end
+
+        def arity_matches?(block_to_test)
+          return true unless @arity
+          block_to_test.arity == @arity
+        end
+
+        attr_accessor :block_to_test
+      end
+
+
+
+
+      # rename args to invocation
+      attr_accessor :expected_invocation, :block, :pass, :filter_name
+
+      def initialize(args=[], filter_name=:default_filter, &block)
+        self.expected_invocation = Invocation.new args.dup, &block
+        self.block = block
+        self.pass = send filter_name
+        self.filter_name = filter_name
+      end
+
+      def filter(invocations)
+        invocations.select &pass
+      end
+
+      def default?
+        filter_name == :default_filter
+      end
+
+      private
+
+      def default_filter
+        Proc.new { true }
+      end
+
+      def args_must_match
+        lambda { |invocation| args_match?(invocation) && blocks_match?(invocation) }
+      end
+
+      def blocks_match?(actual_invocation)
+        # surely this is wrong
+        return true unless expected_invocation.has_block?
+        return unless actual_invocation.has_block?
+        block_asserter.matches? actual_invocation.block
+      end
+
+      def block_asserter
+        @block_asserter ||= BlockAsserter.new expected_invocation.block
+      end
+
+      def args_match?(actual_invocation)
+        if RSpec.rspec_mocks_loaded?
+          rspec_arg_expectation = ::RSpec::Mocks::ArgumentExpectation.new *expected_invocation.args
+          rspec_arg_expectation.args_match? *actual_invocation.args
+        else
+          expected_arguments == actual_arguments
+        end
+      end
+    end
+  end
+end