surrogate 0.1.0

data/lib/surrogate/rspec/api_method_matchers.rb

@@ -0,0 +1,246 @@
+require 'erb'
+
+
+class Surrogate
+  module RSpec
+    module MessagesFor
+
+      MESSAGES = {
+        verb: {
+          should: {
+            default:    "was never told to <%= subject %>",
+            with:       "should have been told to <%= subject %> with <%= inspect_arguments expected_arguments %>, but <%= actual_invocation %>",
+            times:      "should have been told to <%= subject %> <%= times_msg expected_times_invoked %> but was told to <%= subject %> <%= times_msg times_invoked %>",
+            with_times: "should have been told to <%= subject %> <%= times_msg expected_times_invoked %> with <%= inspect_arguments expected_arguments %>, but <%= actual_invocation %>",
+          },
+          should_not: {
+            default:    "shouldn't have been told to <%= subject %>, but was told to <%= subject %> <%= times_msg times_invoked %>",
+            with:       "should not have been told to <%= subject %> with <%= inspect_arguments expected_arguments %>, but <%= actual_invocation %>",
+            times:      "shouldn't have been told to <%= subject %> <%= times_msg expected_times_invoked %>, but was",
+            with_times: "should not have been told to <%= subject %> <%= times_msg expected_times_invoked %> with <%= inspect_arguments expected_arguments %>, but <%= actual_invocation %>",
+          },
+          other: {
+            not_invoked: "was never told to",
+            invoked_description: "got it",
+          },
+        },
+        noun: {
+          should: {
+            default:    "was never asked for its <%= subject %>",
+            with:       "should have been asked for its <%= subject %> with <%= inspect_arguments expected_arguments %>, but <%= actual_invocation %>",
+            times:      "should have been asked for its <%= subject %> <%= times_msg expected_times_invoked %>, but was asked <%= times_msg times_invoked %>",
+            with_times: "should have been asked for its <%= subject %> <%= times_msg expected_times_invoked %> with <%= inspect_arguments expected_arguments %>, but <%= actual_invocation %>",
+          },
+          should_not: {
+            default:    "shouldn't have been asked for its <%= subject %>, but was asked <%= times_msg times_invoked %>",
+            with:       "should not have been asked for its <%= subject %> with <%= inspect_arguments expected_arguments %>, but <%= actual_invocation %>",
+            times:      "shouldn't have been asked for its <%= subject %> <%= times_msg expected_times_invoked %>, but was",
+            with_times: "should not have been asked for its <%= subject %> <%= times_msg expected_times_invoked %> with <%= inspect_arguments expected_arguments %>, but <%= actual_invocation %>",
+          },
+          other: {
+            not_invoked: "was never asked",
+            invoked_description: "was asked",
+          },
+        },
+      }
+
+      def message_for(language_type, message_category, message_type, binding)
+        message = MESSAGES[language_type][message_category].fetch(message_type)
+        ERB.new(message).result(binding)
+      end
+
+      def inspect_arguments(arguments)
+        inspected_arguments = arguments.map { |argument| MessagesFor.inspect_argument argument }
+        inspected_arguments << 'no_args' if inspected_arguments.empty?
+        %Q(`#{inspected_arguments.join ", "}')
+      end
+
+      def inspect_argument(to_inspect)
+        if to_inspect.kind_of? ::RSpec::Mocks::ArgumentMatchers::NoArgsMatcher
+          "no_args"
+        else
+          to_inspect.inspect
+        end
+      end
+
+      extend self
+    end
+
+
+    class Handler < Struct.new(:subject, :language_type)
+      attr_accessor :instance, :message_type
+
+      def message_for(message_category, message_type)
+        MessagesFor.message_for(language_type, message_category, message_type, binding)
+      end
+
+      def inspect_arguments(args)
+        MessagesFor.inspect_arguments args
+      end
+
+      def message_type
+        @message_type || :default
+      end
+
+      def invocations
+        instance.invocations(subject)
+      end
+
+      def times_invoked
+        invocations.size
+      end
+
+      def match?
+        times_invoked > 0
+      end
+
+      def times_msg(n)
+        "#{n} time#{'s' unless n == 1}"
+      end
+
+      def failure_message_for_should
+        message_for :should, message_type
+      end
+
+      def failure_message_for_should_not
+        message_for :should_not, message_type
+      end
+    end
+
+
+    module MatchWithArguments
+      def self.extended(klass)
+        klass.message_type = :with
+      end
+
+      attr_accessor :expected_arguments
+
+      def match? # eventually this will need to get a lot smarter
+        if expected_arguments.size == 1 && expected_arguments.first.kind_of?(::RSpec::Mocks::ArgumentMatchers::NoArgsMatcher)
+          invocations.include? []
+        else
+          invocations.include? expected_arguments
+        end
+      end
+
+      def actual_invocation
+        return message_for :other, :not_invoked if times_invoked.zero?
+        inspected_invocations = invocations.map { |invocation| inspect_arguments invocation }
+        "got #{inspected_invocations.join ', '}"
+      end
+    end
+
+
+    module MatchNumTimes
+      def self.extended(klass)
+        klass.message_type = :times
+      end
+
+      attr_accessor :expected_times_invoked
+
+      def match?
+        expected_times_invoked == times_invoked
+      end
+    end
+
+
+    module MatchNumTimesWith
+      def self.extended(klass)
+        klass.message_type = :with_times
+      end
+
+      attr_accessor :expected_times_invoked, :expected_arguments
+
+      def times_invoked_with_expected_args
+        invocations.select { |invocation| invocation == expected_arguments }.size
+      end
+
+      def match?
+        times_invoked_with_expected_args == expected_times_invoked
+      end
+
+      def actual_invocation
+        return message_for :other, :not_invoked if times_invoked.zero?
+        "#{message_for :other, :invoked_description} #{times_msg times_invoked_with_expected_args}"
+      end
+    end
+
+
+
+
+
+    # have_been_told_to
+    ::RSpec::Matchers.define :have_been_told_to do |verb|
+      use_case = Handler.new verb, :verb
+
+      match do |mocked_instance|
+        use_case.instance = mocked_instance
+        use_case.match?
+      end
+
+      chain :times do |number|
+        use_case.extend (use_case.kind_of?(MatchWithArguments) ? MatchNumTimesWith : MatchNumTimes)
+        use_case.expected_times_invoked = number
+      end
+
+      chain :with do |*arguments|
+        use_case.extend (use_case.kind_of?(MatchNumTimes) ? MatchNumTimesWith : MatchWithArguments)
+        use_case.expected_arguments = arguments
+      end
+
+      failure_message_for_should     { use_case.failure_message_for_should }
+      failure_message_for_should_not { use_case.failure_message_for_should_not }
+    end
+
+
+    # have_been_asked_for_its
+    ::RSpec::Matchers.define :have_been_asked_for_its do |noun|
+      use_case = Handler.new noun, :noun
+
+      match do |mocked_instance|
+        use_case.instance = mocked_instance
+        use_case.match?
+      end
+
+      chain :times do |number|
+        use_case.extend (use_case.kind_of?(MatchWithArguments) ? MatchNumTimesWith : MatchNumTimes)
+        use_case.expected_times_invoked = number
+      end
+
+      chain :with do |*arguments|
+        use_case.extend (use_case.kind_of?(MatchNumTimes) ? MatchNumTimesWith : MatchWithArguments)
+        use_case.expected_arguments = arguments
+      end
+
+      failure_message_for_should     { use_case.failure_message_for_should }
+      failure_message_for_should_not { use_case.failure_message_for_should_not }
+    end
+
+
+    # have_been_initialized_with
+    ::RSpec::Matchers.define :have_been_initialized_with do |*init_args|
+      use_case = Handler.new :initialize, :verb
+      use_case.extend MatchWithArguments
+      use_case.expected_arguments = init_args
+
+      match do |mocked_instance|
+        use_case.instance = mocked_instance
+        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
+
+      failure_message_for_should_not do
+        use_case.failure_message_for_should_not
+      end
+    end
+  end
+end
+
+

data/lib/surrogate/rspec/substitutability_matchers.rb

@@ -0,0 +1,24 @@
+class Surrogate
+  module RSpec
+    module MessagesFor
+      ::RSpec::Matchers.define :substitute_for do |original_class|
+
+        comparison = nil
+
+        match do |mocked_class|
+          comparison = ApiComparer.new(mocked_class, original_class).compare
+          (comparison[:instance].values + comparison[:class].values).inject(:+).empty?
+        end
+
+        failure_message_for_should do
+          "Should have been substitute, but found these differences #{comparison.inspect}"
+        end
+
+        failure_message_for_should_not do
+          "Should not have been substitute, but was"
+        end
+      end
+    end
+  end
+end
+

data/lib/surrogate/rspec.rb

@@ -0,0 +1,2 @@
+require 'surrogate/rspec/api_method_matchers'
+require 'surrogate/rspec/substitutability_matchers'

data/lib/surrogate/version.rb

@@ -0,0 +1,3 @@
+class Surrogate
+  VERSION = "0.1.0"
+end

data/lib/surrogate.rb

@@ -0,0 +1,17 @@
+require 'surrogate/version'
+require 'surrogate/hatchling'
+require 'surrogate/hatchery'
+require 'surrogate/options'
+require 'surrogate/method_queue'
+require 'surrogate/endower'
+require 'surrogate/api_comparer'
+
+class Surrogate
+  UnpreparedMethodError = Class.new StandardError
+
+  # TODO: Find a new name that isn't "playlist"
+  def self.endow(klass, &playlist)
+    Endower.endow klass, &playlist
+    klass
+  end
+end

data/spec/acceptance_spec.rb

@@ -0,0 +1,131 @@
+require 'spec_helper'
+
+describe Surrogate do
+  it 'passes this acceptance spec' do
+    module Mock
+      class User
+
+        # things sung inside the block are sungd to User's singleton class (ie User.find)
+        Surrogate.endow self do
+
+          # the block is used as a default value unless overridden by the spec
+          define :find do |id|
+            new id
+          end
+
+        end
+
+        # things sung outside the block are sung at User (ie user.id)
+
+        define :initialize do |id|
+          @id = id # can set the @id ivar to give the #id method a default
+          @phone_numbers = []
+        end
+
+        define :id
+        define(:name) { 'Josh' }
+        define :address
+
+        define :phone_numbers
+
+        define :add_phone_number do |area_code, number|
+          @phone_numbers << [area_code, number]
+        end
+      end
+    end
+
+
+    # don't affect the real user class
+    user_class = Mock::User.reprise
+
+
+    # =====  set a default  =====
+    user_class.will_find :user1
+    user_class.find(1).should == :user1
+    user_class.find(2).should == :user1
+
+    # set a queue of default values
+    user_class.will_find :user1, :user2, :user3          # set three overrides
+    user_class.find(11).should == :user1                 # first override
+    user_class.find(22).should == :user2                 # second override
+    user_class.find(33).should == :user3                 # third override
+    user_class.find(44).should be_a_kind_of Mock::User   # back to default block
+    # might also be nice to provide a way to raise an error
+
+    # tracking invocations
+    user_class = Mock::User.reprise
+    user_class.should_not have_been_told_to :find
+    user_class.find 12
+    user_class.find 12
+    user_class.find 23
+    user_class.should have_been_told_to(:find).times(3)
+    user_class.should have_been_told_to(:find).with(12)
+    user_class.should have_been_told_to(:find).with(12).times(2)
+    # user_class.should have_been_told_to(:find).with(22).and_with(33)  # not sure if we really care about this (i.e. probably this will come in a later release if we like the lib)
+    # user_class.should have_been_told_to(:find).with(11).before(22)    # not sure if we really care about this
+
+    expect { user_class.should have_been_told_to(:find).with(123123123) }.to raise_error RSpec::Expectations::ExpectationNotMetError
+
+
+    # =====  on the instances  =====
+    user = user_class.find 123
+
+    # tracking initialization args
+    user.should have_been_initialized_with 123
+
+    # tracking invocations (these are just synonyms to try and fit the language you would want to use in a spec)
+    # user.should_not have_been_asked_for :id
+    user.should_not have_been_asked_for_its :id
+    # user.should_not have_invoked :id
+    user.id.should == 123
+    # user.should have_been_asked_for :id
+    user.should have_been_asked_for_its :id
+    # user.should have_invoked :id
+    # maybe someday also support assertions about order of method invocation
+
+    # set a default
+    user.will_have_name 'Bill'
+    user.name.should == 'Bill'
+    user.should have_been_asked_for_its :name
+
+    # defaults are used if provided
+    Mock::User.new(1).name.should == 'Josh'
+
+    # error is raised if you try to access an attribute that hasn't been set and has no default
+    expect { Mock::User.new(1).address }.to raise_error Surrogate::UnpreparedMethodError
+    Mock::User.new(1).will_have_address('123 Fake St.').address.should == '123 Fake St.'
+
+    # methods with multiple args
+    user.phone_numbers.should be_empty
+    user.add_phone_number '123', '456-7890'
+    user.should have_been_told_to(:add_phone_number).with('123', '456-7890')
+    # user.phone_numbers.should == [['123', '456-7890']] # <-- should we use a hook, or default block to make this happen?
+
+
+    # =====  Substitutability  =====
+
+    # real user is not a suitable substitute if missing methods that mock user has
+    user_class.should_not substitute_for Class.new
+
+    # real user must have all of mock user's methods to be substitutable
+    substitutable_real_user_class = Class.new do
+      def self.find() end
+      def initialize(id) end
+      def id() end
+      def name() end
+      def address() end
+      def phone_numbers() end
+      def add_phone_number(area_code, number) end
+    end
+    user_class.should substitute_for substitutable_real_user_class
+
+    # real user class is not a suitable substitutable if has extra methods
+    real_user_class = substitutable_real_user_class.clone
+    def real_user_class.some_class_meth() end
+    user_class.should_not substitute_for real_user_class
+
+    real_user_class = substitutable_real_user_class.clone
+    real_user_class.send(:define_method, :some_instance_method) {}
+    user_class.should_not substitute_for real_user_class
+  end
+end