surrogate 0.2.0 → 0.3.0

data/Readme.md

@@ -1,4 +1,43 @@
-Explanation and examples coming soon.
+Explanation and examples coming soon, but here is a simple example I wrote up for a lightning talk:
+
+```ruby
+require 'surrogate'
+require 'surrogate/rspec'
+
+module Mock
+  class User
+    Surrogate.endow self
+    define(:name) { 'Josh' }
+    define :phone_numbers
+    define :add_phone_number do |area_code, number|
+      @phone_numbers << [area_code, number]
+    end
+  end
+end
+
+class User
+  def name()end
+  def phone_numbers()end
+  def add_phone_number()end
+end
+
+describe do
+  it 'ensures the mock lib looks like real lib' do
+    Mock::User.should substitute_for User
+  end
+
+  let(:user) { Mock::User.new }
+
+  example 'you can tell it how to behave and ask what happened with it' do
+    user.will_have_name "Sally"
+
+    user.should_not have_been_asked_for_its :name
+    user.name.should == "Sally"
+    user.should have_been_asked_for_its :name
+  end
+end
+```
+
 
 TODO
 ----

data/lib/surrogate/endower.rb

@@ -1,6 +1,6 @@
 class Surrogate
 
-  # adds surrogate behaviour to your class / singleton class / instances
+  # Adds surrogate behaviour to your class / singleton class / instances
   #
   # please refactor me!
   class Endower
@@ -22,29 +22,31 @@ class Surrogate
   private
 
     def endow_klass
-      a_hatchery_for                         klass
+      add_hatchery_to                        klass
+      klass.extend ClassMethods
       enable_defining_methods                klass
       record_initialization_for_instances_of klass
       remember_invocations_for_instances_of  klass
       remember_invocations_for_instances_of  klass.singleton_class
-      hijack_instantiation_of                klass
-      can_get_a_new                          klass
     end
 
     def endow_singleton_class
-      hatchery = a_hatchery_for singleton
+      hatchery = add_hatchery_to singleton
       enable_defining_methods singleton
       singleton.module_eval &playlist if playlist
-      klass.instance_variable_set :@surrogate, Hatchling.new(klass, hatchery)
+      klass.instance_variable_set :@hatchling, Hatchling.new(klass, hatchery)
       klass
     end
 
-    # yeesh :( try to find a better way to do this
+    # yeesh :( pretty sure there isn't a better way to do this
     def record_initialization_for_instances_of(klass)
       def klass.method_added(meth)
-        return unless meth == :initialize && !@hijacking_initialize
+        return if meth != :initialize || @hijacking_initialize
         @hijacking_initialize = true
         current_initialize = instance_method :initialize
+
+        # `define' records the args while maintaining the old behaviour
+        # we have to do it stupidly like this because there is no to_proc on an unbound method
         define :initialize do |*args, &block|
           current_initialize.bind(self).call(*args, &block)
         end
@@ -61,48 +63,16 @@ class Surrogate
       klass.singleton_class
     end
 
-    def can_get_a_new(klass)
-      klass.extend Module.new {
-        # use a module so that the method is inherited (important for substitutability)
-        def clone
-          new_klass = Class.new self
-          surrogate = @surrogate
-          Surrogate.endow new_klass do
-            surrogate.api_methods.each do |method_name, options|
-              define method_name, options.to_hash, &options.default_proc
-            end
-          end
-          @hatchery.api_methods.each do |method_name, options|
-            new_klass.define method_name, options.to_hash, &options.default_proc
-          end
-          new_klass
-        end
-      }
-    end
-
     def remember_invocations_for_instances_of(klass)
       klass.send :define_method, :invocations do |method_name|
-        @surrogate.invocations method_name
+        @hatchling.invocations method_name
       end
     end
 
-    def a_hatchery_for(klass)
+    def add_hatchery_to(klass)
       klass.instance_variable_set :@hatchery, Surrogate::Hatchery.new(klass)
     end
 
-    def hijack_instantiation_of(klass)
-      # use a module so that the method is inherited (important for substitutability)
-      klass.extend Module.new {
-        def new(*args)
-          instance = allocate
-          hatchery = @hatchery
-          instance.instance_eval { @surrogate = Hatchling.new instance, hatchery }
-          instance.send :initialize, *args
-          instance
-        end
-      }
-    end
-
     def enable_defining_methods(klass)
       def klass.define(method_name, options={}, &block)
         @hatchery.define method_name, options, block
@@ -113,4 +83,26 @@ class Surrogate
       end
     end
   end
+
+
+  # use a module so that the method is inherited (important for substitutability)
+  module ClassMethods
+    def clone
+      hatchling, hatchery = @hatchling, @hatchery
+      Class.new self do
+        Surrogate.endow self do
+          hatchling.api_methods.each { |name, options| define name, options.to_hash, &options.default_proc }
+        end
+        hatchery.api_methods.each { |name, options| define name, options.to_hash, &options.default_proc }
+      end
+    end
+
+    # Custom new, because user can define initialize, and ivars should be set before it
+    def new(*args)
+      instance = allocate
+      instance.instance_variable_set :@hatchling, Hatchling.new(instance, @hatchery)
+      instance.send :initialize, *args
+      instance
+    end
+  end
 end

data/lib/surrogate/hatchery.rb

@@ -1,19 +1,22 @@
 class Surrogate
+
+  # This manages the definitions that were given to the class
+  # The hatchlings are added to the instances, and they look here
+  # to find out about how their methods are implemented.
   class Hatchery
     attr_accessor :klass
 
     def initialize(klass)
       self.klass = klass
-      defines_methods
-    end
-
-    def defines_methods
-      klass.singleton_class.send :define_method, :define, &method(:define)
+      klass_can_define_api_methods
     end
 
     def define(method_name, options={}, block)
-      add_api_methods_for method_name
+      add_api_method_for method_name
+      add_verb_helpers_for method_name
+      add_noun_helpers_for method_name
       api_methods[method_name] = Options.new options, block
+      klass
     end
 
     def api_methods
@@ -24,24 +27,35 @@ class Surrogate
       api_methods.keys - [:initialize]
     end
 
-    # here we need to find better domain terminology
-    def add_api_methods_for(method_name)
+    private
+
+    def klass_can_define_api_methods
+      klass.singleton_class.send :define_method, :define, &method(:define)
+    end
+
+    def add_api_method_for(method_name)
       klass.send :define_method, method_name do |*args, &block|
-        @surrogate.invoke_method method_name, args, &block
+        @hatchling.invoke_method method_name, args, &block
       end
+    end
+
+    def add_verb_helpers_for(method_name)
+      add_helpers_for method_name, "will_#{method_name}"
+    end
 
-      # verbs
-      klass.send :define_method, "will_#{method_name}" do |*args, &block|
+    def add_noun_helpers_for(method_name)
+      add_helpers_for method_name, "will_have_#{method_name}"
+    end
+
+    def add_helpers_for(method_name, helper_name)
+      klass.send :define_method, helper_name do |*args, &block|
         if args.size == 1
-          @surrogate.prepare_method method_name, args, &block
+          @hatchling.prepare_method method_name, args, &block
         else
-          @surrogate.prepare_method_queue method_name, args, &block
+          @hatchling.prepare_method_queue method_name, args, &block
         end
         self
       end
-
-      # nouns
-      klass.send :alias_method, "will_have_#{method_name}", "will_#{method_name}"
     end
   end
 end

data/lib/surrogate/hatchling.rb

@@ -1,5 +1,8 @@
 class Surrogate
   UnknownMethod = Class.new StandardError
+
+  # This contains the unique behaviour for each instance
+  # It handles method invocation and records the appropriate information
   class Hatchling
     attr_accessor :instance, :hatchery
 
@@ -15,6 +18,8 @@ class Surrogate
       invoked_methods[method_name] << args
       return get_default method_name, args unless has_ivar? method_name
       ivar = get_ivar method_name
+
+      # This may soon need classes for each type which know how to invoke themselves
       case ivar
       when MethodQueue
         play_from_queue ivar, method_name

data/lib/surrogate/rspec/api_method_matchers.rb

@@ -228,10 +228,6 @@ class Surrogate
         use_case.match?
       end
 
-      chain :nothing do
-        use_case.expected_arguments = nothing
-      end
-
       failure_message_for_should do
         use_case.failure_message_for_should
       end

data/lib/surrogate/rspec/substitutability_matchers.rb

@@ -1,24 +1,34 @@
 class Surrogate
-  module RSpec
-    module MessagesFor
-      ::RSpec::Matchers.define :substitute_for do |original_class|
+  ::RSpec::Matchers.define :substitute_for do |original_class, options={}|
 
-        comparison = nil
+    comparison = nil
+    subset_only = options[:subset]
 
-        match do |mocked_class|
-          comparison = ApiComparer.new(mocked_class, original_class).compare
-          (comparison[:instance].values + comparison[:class].values).inject(:+).empty?
-        end
+    match do |mocked_class|
+      comparison = ApiComparer.new(mocked_class, original_class).compare
+      if subset_only
+        (comparison[:instance][:not_on_actual] + comparison[:class][:not_on_actual]).empty?
+      else
+        (comparison[:instance].values + comparison[:class].values).inject(:+).empty?
+      end
+    end
 
-        failure_message_for_should do
-          "Should have been substitute, but found these differences #{comparison.inspect}"
-        end
+    failure_message_for_should do
+      extra_instance_methods   = comparison[:instance][:not_on_actual   ].to_a
+      extra_class_methods      = comparison[:class   ][:not_on_actual   ].to_a
+      missing_instance_methods = comparison[:instance][:not_on_surrogate].to_a
+      missing_class_methods    = comparison[:class   ][:not_on_surrogate].to_a
 
-        failure_message_for_should_not do
-          "Should not have been substitute, but was"
-        end
-      end
+      differences = []
+      differences << "has extra instance methods: #{extra_instance_methods.inspect}" if extra_instance_methods.any?
+      differences << "has extra class methods: #{extra_class_methods.inspect}"       if extra_class_methods.any?
+      differences << "is missing instance methods: #{missing_instance_methods}"      if !subset_only && missing_instance_methods.any?
+      differences << "is missing class methods: #{missing_class_methods}"            if !subset_only && missing_class_methods.any?
+      "Was not substitutable because surrogate " << differences.join(', ')
+    end
+
+    failure_message_for_should_not do
+      "Should not have been substitute, but was"
     end
   end
 end
-

data/lib/surrogate/version.rb

@@ -1,3 +1,3 @@
 class Surrogate
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/spec/defining_api_methods_spec.rb

@@ -193,35 +193,34 @@ describe 'define' do
         specify 'even works with inheritance' do
           superclass = Class.new
           superclass.send(:define_method, :initialize) { @a = 1 }
-          subclass = Class.new superclass
-          mocked_subclass = Surrogate.endow Class.new subclass
-          mocked_subclass.define :abc
-          mocked_subclass.new.instance_variable_get(:@a).should == 1
+          subclass = Surrogate.endow Class.new superclass
+          subclass.define :abc
+          subclass.new.instance_variable_get(:@a).should == 1
         end
 
         context 'when not an api method' do
           it 'respects arity (this is probably 1.9.3 only)' do
-            expect { mocked_class.new(1) }.to raise_error ArgumentError, 'wrong number of arguments(1 for 0)'
+            expect { mocked_class.new 1 }.to raise_error ArgumentError, 'wrong number of arguments(1 for 0)'
           end
 
-          specify 'recorded regardless of when initialize is defined in relation to mock' do
-            klass = Class.new do
-              Surrogate.endow self
-              def initialize(a)
-                @a = a
+          describe 'invocations are recorded anyway' do
+            specify 'even when initialize is defined after surrogate block' do
+              klass = Class.new do
+                Surrogate.endow self
+                def initialize(a) @a = a end
               end
+              klass.new(1).should have_been_initialized_with 1
+              klass.new(1).instance_variable_get(:@a).should == 1
             end
-            klass.new(1).should have_been_initialized_with 1
-            klass.new(1).instance_variable_get(:@a).should == 1
 
-            klass = Class.new do
-              def initialize(a)
-                @a = a
+            specify 'even when initialize is defined before surrogate block' do
+              klass = Class.new do
+                def initialize(a) @a = a end
+                Surrogate.endow self
               end
-              Surrogate.endow self
+              klass.new(1).should have_been_initialized_with 1
+              klass.new(1).instance_variable_get(:@a).should == 1
             end
-            klass.new(1).should have_been_initialized_with 1
-            klass.new(1).instance_variable_get(:@a).should == 1
           end
         end
       end

data/spec/rspec/substitute_for_spec.rb

@@ -1,72 +1,151 @@
 require 'spec_helper'
 
 describe 'substitute_for' do
+  context 'exact substitutability' do
+    context "returns true iff api methods and inherited methods match exactly to the other object's methods. Examples:" do
+      context "a surrogate with no api methods" do
+        let(:surrogate) { Surrogate.endow Class.new }
+
+        example "is substitutable for a class with no methods" do
+          surrogate.should substitute_for Class.new
+        end
+
+        example "is not substitutable for a class with instance methods" do
+          surrogate.should_not substitute_for Class.new { def foo()end }
+        end
+
+        example "is not substitutable for a class with class methods" do
+          surrogate.should_not substitute_for Class.new { def self.foo()end }
+        end
+
+        example "is not substitutable for a class with inherited instance methods" do
+          parent = Class.new { def foo()end }
+          surrogate.should_not substitute_for Class.new(parent)
+        end
+
+        example "is not substitutable for a class with inherited class methods" do
+          parent = Class.new { def self.foo()end }
+          surrogate.should_not substitute_for Class.new(parent)
+        end
+      end
 
-  context "returns true iff api methods and inherited methods match exactly to the other object's methods. Examples:" do
-    context "a surrogate with no api methods" do
-      let(:surrogate) { Surrogate.endow Class.new }
 
-      example "is substitutable for a class with no methods" do
-        surrogate.should substitute_for Class.new
-      end
+      context "a surrogate with an instance level api method" do
+        let(:surrogate) { Class.new { Surrogate.endow self; define :foo } }
 
-      example "is not substitutable for a class with instance methods" do
-        surrogate.should_not substitute_for Class.new { def foo()end }
-      end
+        example "is substitutable for a class with the same method" do
+          surrogate.should substitute_for Class.new { def foo()end }
+        end
 
-      example "is not substitutable for a class with class methods" do
-        surrogate.should_not substitute_for Class.new { def self.foo()end }
-      end
+        example "is substitutable for a class that inherits the method" do
+          parent = Class.new { def foo()end }
+          surrogate.should substitute_for Class.new(parent)
+        end
 
-      example "is not substitutable for a class with inherited instance methods" do
-        parent = Class.new { def foo()end }
-        surrogate.should_not substitute_for Class.new(parent)
-      end
+        example "is not substitutable for a class without the method" do
+          surrogate.should_not substitute_for Class.new
+        end
 
-      example "is not substitutable for a class with inherited class methods" do
-        parent = Class.new { def self.foo()end }
-        surrogate.should_not substitute_for Class.new(parent)
-      end
-    end
+        example "is not substitutable for a class with a different method" do
+          surrogate.should_not substitute_for Class.new { def bar()end }
+        end
 
+        example "is not substitutable for a class with additional methods" do
+          other = Class.new { def foo()end; def bar()end }
+          surrogate.should_not substitute_for other
+        end
 
-    context "a surrogate with an instance level api method" do
-      let(:surrogate) { Class.new { Surrogate.endow self; define :foo } }
+        example "is not substitutable for a class with the method and inerited additional methods" do
+          parent = Class.new { def bar()end }
+          surrogate.should_not substitute_for Class.new(parent) { def foo()end }
+        end
 
-      example "is substitutable for a class with the same method" do
-        surrogate.should substitute_for Class.new { def foo()end }
-      end
+        example "is not substitutable for a class with the method and additional class methods" do
+          surrogate.should_not substitute_for Class.new { def foo()end; def self.bar()end }
+        end
 
-      example "is substitutable for a class that inherits the method" do
-        parent = Class.new { def foo()end }
-        surrogate.should substitute_for Class.new(parent)
+        example "is not substitutable for a class with the method and inherited additional class methods" do
+          parent = Class.new { def self.bar()end }
+          surrogate.should_not substitute_for Class.new(parent) { def foo()end }
+        end
       end
 
-      example "is not substitutable for a class without the method" do
-        surrogate.should_not substitute_for Class.new
+
+      describe "it has helpful error messages" do
+        let(:surrogate) { Surrogate.endow Class.new }
+
+        specify 'when klass is missing an instance method' do
+          surrogate.define :meth
+          expect { surrogate.should substitute_for Class.new }.to \
+            raise_error(RSpec::Expectations::ExpectationNotMetError, "Was not substitutable because surrogate has extra instance methods: [:meth]")
+        end
+
+        specify 'when klass is missing a class method' do
+          surrogate = Surrogate.endow(Class.new) { define :meth }
+          expect { surrogate.should substitute_for Class.new }.to \
+            raise_error(RSpec::Expectations::ExpectationNotMetError, "Was not substitutable because surrogate has extra class methods: [:meth]")
+        end
+
+        specify 'when surrogate is missing an instance method' do
+          klass = Class.new { def meth() end }
+          expect { surrogate.should substitute_for klass }.to \
+            raise_error(RSpec::Expectations::ExpectationNotMetError, "Was not substitutable because surrogate is missing instance methods: [:meth]")
+        end
+
+        specify 'when surrogate is missing a class method' do
+          klass = Class.new { def self.meth() end }
+          expect { surrogate.should substitute_for klass }.to \
+            raise_error(RSpec::Expectations::ExpectationNotMetError, "Was not substitutable because surrogate is missing class methods: [:meth]")
+        end
+
+        specify 'when combined' do
+          surrogate = Surrogate.endow(Class.new) { define :surrogate_class_meth }.define :surrogate_instance_meth
+          klass = Class.new { def self.api_class_meth()end; def api_instance_meth() end }
+          expect { surrogate.should substitute_for klass }.to \
+            raise_error(RSpec::Expectations::ExpectationNotMetError, "Was not substitutable because surrogate has extra instance methods: [:surrogate_instance_meth], "\
+                                                                                                             "has extra class methods: [:surrogate_class_meth], "\
+                                                                                                             "is missing instance methods: [:api_instance_meth], "\
+                                                                                                             "is missing class methods: [:api_class_meth]")
+        end
+
+        specify "when negated (idk why you'd ever want this, though)" do
+          expect { surrogate.should_not substitute_for Class.new }.to \
+            raise_error(RSpec::Expectations::ExpectationNotMetError, "Should not have been substitute, but was")
+        end
       end
+    end
+  end
+
+
 
-      example "is not substitutable for a class with a different method" do
-        surrogate.should_not substitute_for Class.new { def bar()end }
+  context 'subset substitutability -- specified with subset: true option' do
+    context "returns true if api methods and inherited methods match are all implemented by other class. Examples:" do
+      example 'true when exact match' do
+        Surrogate.endow(Class.new).should substitute_for Class.new, subset: true
       end
 
-      example "is not substitutable for a class with additional methods" do
-        other = Class.new { def foo()end; def bar()end }
-        surrogate.should_not substitute_for other
+      example 'true when other has additional instance methods and class methods' do
+        klass = Class.new { def self.class_meth()end; def instance_meth()end }
+        Surrogate.endow(Class.new).should substitute_for klass, subset: true
       end
 
-      example "is not substitutable for a class with the method and inerited additional methods" do
-        parent = Class.new { def bar()end }
-        surrogate.should_not substitute_for Class.new(parent) { def foo()end }
+      example 'false when other is missing instance methods' do
+        klass = Class.new { def self.extra_method()end; def extra_method()end }
+        expect { Surrogate.endow(Class.new).define(:meth).should substitute_for klass, subset:true }.to \
+          raise_error(RSpec::Expectations::ExpectationNotMetError, "Was not substitutable because surrogate has extra instance methods: [:meth]")
       end
 
-      example "is not substitutable for a class with the method and additional class methods" do
-        surrogate.should_not substitute_for Class.new { def foo()end; def self.bar()end }
+      example 'false when other is missing class methods' do
+        klass = Class.new { def self.extra_method()end; def extra_method()end }
+        expect { Surrogate.endow(Class.new) { define :meth }.should substitute_for klass, subset:true }.to \
+          raise_error(RSpec::Expectations::ExpectationNotMetError, "Was not substitutable because surrogate has extra class methods: [:meth]")
       end
 
-      example "is not substitutable for a class with the method and inherited additional class methods" do
-        parent = Class.new { def self.bar()end }
-        surrogate.should_not substitute_for Class.new(parent) { def foo()end }
+      example 'false when other is missing instance and class methods' do
+        klass = Class.new { def self.extra_method()end; def extra_method()end }
+        expect { Surrogate.endow(Class.new) { define :class_meth }.define(:instance_meth).should substitute_for klass, subset: true }.to \
+          raise_error(RSpec::Expectations::ExpectationNotMetError,
+                      "Was not substitutable because surrogate has extra instance methods: [:instance_meth], has extra class methods: [:class_meth]")
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: surrogate
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-20 00:00:00.000000000 Z
+date: 2012-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70270582700600 !ruby/object:Gem::Requirement
+  requirement: &70298496271040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,7 +21,7 @@ dependencies:
         version: 2.8.0
   type: :development
   prerelease: false
-  version_requirements: *70270582700600
+  version_requirements: *70298496271040
 description: Framework to aid in handrolling mock/spy objects.
 email:
 - josh.cheek@gmail.com