mcmire-shoulda-matchers 2.5.0 → 2.6.1.docs.1

data/lib/shoulda/matchers/doublespeak/double.rb

@@ -0,0 +1,75 @@
+module Shoulda
+  module Matchers
+    module Doublespeak
+      # @private
+      class Double
+        attr_reader :calls
+
+        def initialize(klass, method_name, implementation)
+          @klass = klass
+          @method_name = method_name
+          @implementation = implementation
+          @activated = false
+          @calls = []
+        end
+
+        def to_return(value = nil, &block)
+          if block
+            implementation.returns(&block)
+          else
+            implementation.returns(value)
+          end
+        end
+
+        def activate
+          unless @activated
+            store_original_method
+            replace_method_with_double
+            @activated = true
+          end
+        end
+
+        def deactivate
+          if @activated
+            restore_original_method
+            @activated = false
+          end
+        end
+
+        def record_call(args, block)
+          calls << MethodCall.new(args, block)
+        end
+
+        def call_original_method(object, args, block)
+          if original_method
+            original_method.bind(object).call(*args, &block)
+          end
+        end
+
+        private
+
+        attr_reader :klass, :method_name, :implementation, :original_method
+
+        def store_original_method
+          @original_method = klass.instance_method(method_name)
+        end
+
+        def replace_method_with_double
+          implementation = @implementation
+          double = self
+
+          klass.__send__(:define_method, method_name) do |*args, &block|
+            implementation.call(double, self, args, block)
+          end
+        end
+
+        def restore_original_method
+          original_method = @original_method
+          klass.__send__(:define_method, method_name) do |*args, &block|
+            original_method.bind(self).call(*args, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoulda/matchers/doublespeak/double_collection.rb

@@ -0,0 +1,55 @@
+module Shoulda
+  module Matchers
+    module Doublespeak
+      # @private
+      class DoubleCollection
+        def initialize(klass)
+          @klass = klass
+          @doubles_by_method_name = {}
+        end
+
+        def register_stub(method_name)
+          register_double(method_name, :stub)
+        end
+
+        def register_proxy(method_name)
+          register_double(method_name, :proxy)
+        end
+
+        def activate
+          doubles_by_method_name.each do |method_name, double|
+            double.activate
+          end
+        end
+
+        def deactivate
+          doubles_by_method_name.each do |method_name, double|
+            double.deactivate
+          end
+        end
+
+        def calls_to(method_name)
+          double = doubles_by_method_name[method_name]
+
+          if double
+            double.calls
+          else
+            []
+          end
+        end
+
+        private
+
+        attr_reader :klass, :doubles_by_method_name
+
+        def register_double(method_name, implementation_type)
+          implementation =
+            DoubleImplementationRegistry.find(implementation_type)
+          double = Double.new(klass, method_name, implementation)
+          doubles_by_method_name[method_name] = double
+          double
+        end
+      end
+    end
+  end
+end

data/lib/shoulda/matchers/doublespeak/double_implementation_registry.rb

@@ -0,0 +1,28 @@
+module Shoulda
+  module Matchers
+    module Doublespeak
+      # @private
+      module DoubleImplementationRegistry
+        class << self
+          REGISTRY = {}
+
+          def find(type)
+            find_class!(type).create
+          end
+
+          def register(klass, type)
+            REGISTRY[type] = klass
+          end
+
+          private
+
+          def find_class!(type)
+            REGISTRY.fetch(type) do
+              raise ArgumentError, "No double implementation class found for '#{type}'"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoulda/matchers/doublespeak/object_double.rb

@@ -0,0 +1,33 @@
+module Shoulda
+  module Matchers
+    module Doublespeak
+      # @private
+      class ObjectDouble < BasicObject
+        attr_reader :calls
+
+        def initialize
+          @calls = []
+          @calls_by_method_name = {}
+        end
+
+        def calls_to(method_name)
+          @calls_by_method_name[method_name] || []
+        end
+
+        def respond_to?(name, include_private = nil)
+          true
+        end
+
+        def method_missing(method_name, *args, &block)
+          calls << MethodCallWithName.new(method_name, args, block)
+          (calls_by_method_name[method_name] ||= []) << MethodCall.new(args, block)
+          nil
+        end
+
+        private
+
+        attr_reader :calls_by_method_name
+      end
+    end
+  end
+end

data/lib/shoulda/matchers/doublespeak/proxy_implementation.rb

@@ -0,0 +1,31 @@
+module Shoulda
+  module Matchers
+    module Doublespeak
+      # @private
+      class ProxyImplementation
+        extend Forwardable
+
+        DoubleImplementationRegistry.register(self, :proxy)
+
+        def_delegators :stub_implementation, :returns
+
+        def self.create
+          new(StubImplementation.new)
+        end
+
+        def initialize(stub_implementation)
+          @stub_implementation = stub_implementation
+        end
+
+        def call(double, object, args, block)
+          stub_implementation.call(double, object, args, block)
+          double.call_original_method(object, args, block)
+        end
+
+        private
+
+        attr_reader :stub_implementation
+      end
+    end
+  end
+end

data/lib/shoulda/matchers/doublespeak/structs.rb

@@ -0,0 +1,10 @@
+module Shoulda
+  module Matchers
+    module Doublespeak
+      # @private
+      MethodCall = Struct.new(:args, :block)
+      # @private
+      MethodCallWithName = Struct.new(:method_name, :args, :block)
+    end
+  end
+end

data/lib/shoulda/matchers/doublespeak/stub_implementation.rb

@@ -0,0 +1,35 @@
+module Shoulda
+  module Matchers
+    module Doublespeak
+      # @private
+      class StubImplementation
+        DoubleImplementationRegistry.register(self, :stub)
+
+        def self.create
+          new
+        end
+
+        def initialize
+          @implementation = proc { nil }
+        end
+
+        def returns(value = nil, &block)
+          if block
+            @implementation = block
+          else
+            @implementation = proc { value }
+          end
+        end
+
+        def call(double, object, args, block)
+          double.record_call(args, block)
+          implementation.call(object, args, block)
+        end
+
+        private
+
+        attr_reader :implementation
+      end
+    end
+  end
+end

data/lib/shoulda/matchers/doublespeak/world.rb

@@ -0,0 +1,39 @@
+module Shoulda
+  module Matchers
+    module Doublespeak
+      # @private
+      class World
+        def register_double_collection(klass)
+          double_collection = DoubleCollection.new(klass)
+          double_collections_by_class[klass] = double_collection
+          double_collection
+        end
+
+        def with_doubles_activated
+          activate
+          yield
+        ensure
+          deactivate
+        end
+
+        private
+
+        def activate
+          double_collections_by_class.each do |klass, double_collection|
+            double_collection.activate
+          end
+        end
+
+        def deactivate
+          double_collections_by_class.each do |klass, double_collection|
+            double_collection.deactivate
+          end
+        end
+
+        def double_collections_by_class
+          @_double_collections_by_class ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/shoulda/matchers/doublespeak.rb

@@ -0,0 +1,28 @@
+require 'forwardable'
+
+module Shoulda
+  module Matchers
+    # @private
+    module Doublespeak
+      class << self
+        extend Forwardable
+
+        def_delegators :world, :register_double_collection,
+          :with_doubles_activated
+
+        def world
+          @_world ||= World.new
+        end
+      end
+    end
+  end
+end
+
+require 'shoulda/matchers/doublespeak/double'
+require 'shoulda/matchers/doublespeak/double_collection'
+require 'shoulda/matchers/doublespeak/double_implementation_registry'
+require 'shoulda/matchers/doublespeak/object_double'
+require 'shoulda/matchers/doublespeak/proxy_implementation'
+require 'shoulda/matchers/doublespeak/structs'
+require 'shoulda/matchers/doublespeak/stub_implementation'
+require 'shoulda/matchers/doublespeak/world'

data/lib/shoulda/matchers/error.rb

@@ -1,6 +1,25 @@
 module Shoulda
   module Matchers
     # @private
-    class Error < StandardError; end
+    class Error < StandardError
+      def self.create(attributes)
+        allocate.tap do |error|
+          attributes.each do |name, value|
+            error.__send__("#{name}=", value)
+          end
+
+          error.__send__(:initialize)
+        end
+      end
+
+      def initialize(*args)
+        super
+        @message = message
+      end
+
+      def message
+        ""
+      end
+    end
   end
 end

data/lib/shoulda/matchers/independent/delegate_matcher/stubbed_target.rb

@@ -0,0 +1,35 @@
+module Shoulda
+  module Matchers
+    module Independent
+      # @private
+      class DelegateMatcher::StubbedTarget
+        def initialize(method)
+          @received_method = false
+          @received_arguments = []
+          stub_method(method)
+        end
+
+        def has_received_method?
+          received_method
+        end
+
+        def has_received_arguments?(*args)
+          args == received_arguments
+        end
+
+        private
+
+        def stub_method(method)
+          class_eval do
+            define_method method do |*args|
+              @received_method = true
+              @received_arguments = args
+            end
+          end
+        end
+
+        attr_reader :received_method, :received_arguments
+      end
+    end
+  end
+end

data/lib/shoulda/matchers/independent/delegate_matcher.rb

@@ -0,0 +1,293 @@
+module Shoulda
+  module Matchers
+    module Independent
+      # The `delegate_method` matcher is used for testing that methods are
+      # delegated properly.
+      #
+      #     class TestRunner
+      #       extend Forwardable
+      #
+      #       def_delegators :suite_runner, :configuration
+      #
+      #       def initialize(suite_runner)
+      #         @suite_runner = suite_runner
+      #       end
+      #
+      #       private
+      #
+      #       attr_reader :suite_runner
+      #     end
+      #
+      #     # RSpec
+      #     describe TestRunner do
+      #       it { should delegate_method(:configuration).to(:suite_runner) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class TestRunnerTest < ActiveSupport::TestCase
+      #       should delegate_method(:configuration).to(:suite_runner)
+      #     end
+      #
+      # #### Qualifiers
+      #
+      # ##### as
+      #
+      # Use `as` to specify the name of the method on the delegate object.
+      #
+      #     class User
+      #       def initialize(company)
+      #         @company = company
+      #       end
+      #
+      #       def company_name
+      #         company.name
+      #       end
+      #
+      #       private
+      #
+      #       attr_reader :company
+      #     end
+      #
+      #     # RSpec
+      #     describe User do
+      #       it { should delegate(:company_name).to(:company).as(:name) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class UserTest < ActiveSupport::TestCase
+      #       should delegate(:company_name).to(:company).as(:name)
+      #     end
+      #
+      # ##### with_arguments
+      #
+      # Use `with_arguments` to specify that the target method should be called
+      # with the given arguments.
+      #
+      #     class Address
+      #       def initialize(geocoding_service)
+      #         @geocoding_service = geocoding_service
+      #       end
+      #
+      #       def geocode
+      #         geocoding_service.geocode(to_s)
+      #       end
+      #
+      #       def to_s
+      #         [street, city, state, zip].join(' ')
+      #       end
+      #
+      #       private
+      #
+      #       attr_reader :geocoding_service
+      #     end
+      #
+      #     # RSpec
+      #     describe Address do
+      #       it 'delegates #geocode to the GeocodingService' do
+      #         address = Address.new(:geocoding_service)
+      #         address.stubs(:to_s).returns('the address')
+      #         expect(address).to delegate(:geocode).
+      #           to(:geocoding_service).
+      #           with_arguments('the address')
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class AddressTest < ActiveSupport::TestCase
+      #       should 'delegate #geocode to the GeocodingService' do
+      #         address = Address.new(:geocoding_service)
+      #         address.stubs(:to_s).returns('the address')
+      #         matcher = delegate(:geocode).
+      #           to(:geocoding_service).
+      #           with_arguments('the address')
+      #         assert_accepts matcher, address
+      #       end
+      #     end
+      #
+      def delegate_method(delegating_method)
+        DelegateMatcher.new(delegating_method)
+      end
+
+      # @private
+      class DelegateMatcher
+        def initialize(delegating_method)
+          @delegating_method = delegating_method
+          @method_on_target = @delegating_method
+          @target_double = Doublespeak::ObjectDouble.new
+
+          @delegated_arguments = []
+          @target_method = nil
+          @subject = nil
+          @subject_double_collection = nil
+        end
+
+        def matches?(subject)
+          @subject = subject
+
+          ensure_target_method_is_present!
+
+          subject_has_delegating_method? &&
+            subject_has_target_method? &&
+            subject_delegates_to_target_correctly?
+        end
+
+        def description
+          add_clarifications_to(
+            "delegate method ##{delegating_method} to :#{target_method}"
+          )
+        end
+
+        def to(target_method)
+          @target_method = target_method
+          self
+        end
+
+        def as(method_on_target)
+          @method_on_target = method_on_target
+          self
+        end
+
+        def with_arguments(*arguments)
+          @delegated_arguments = arguments
+          self
+        end
+
+        def failure_message
+          base = "Expected #{formatted_delegating_method_name} to delegate to #{formatted_target_method_name}"
+          add_clarifications_to(base)
+          base << "\nCalls on #{formatted_target_method_name}:"
+          base << formatted_calls_on_target
+          base.strip
+        end
+        alias failure_message_for_should failure_message
+
+        def failure_message_when_negated
+          base = "Expected #{formatted_delegating_method_name} not to delegate to #{formatted_target_method_name}"
+          add_clarifications_to(base)
+          base << ', but it did'
+        end
+        alias failure_message_for_should_not failure_message_when_negated
+
+        private
+
+        attr_reader \
+          :delegated_arguments,
+          :delegating_method,
+          :method,
+          :method_on_target,
+          :subject,
+          :subject_double_collection,
+          :target_double,
+          :target_method
+
+        def add_clarifications_to(message)
+          if delegated_arguments.any?
+            message << " with arguments: #{delegated_arguments.inspect}"
+          end
+
+          if method_on_target != delegating_method
+            message << " as ##{method_on_target}"
+          end
+
+          message
+        end
+
+        def formatted_delegating_method_name
+          formatted_method_name_for(delegating_method)
+        end
+
+        def formatted_target_method_name
+          formatted_method_name_for(target_method)
+        end
+
+        def formatted_method_name_for(method_name)
+          if subject.is_a?(Class)
+            subject.name + '.' + method_name.to_s
+          else
+            subject.class.name + '#' + method_name.to_s
+          end
+        end
+
+        def target_received_method?
+          calls_to_method_on_target.any?
+        end
+
+        def target_received_method_with_delegated_arguments?
+          calls_to_method_on_target.any? do |call|
+            call.args == delegated_arguments
+          end
+        end
+
+        def subject_has_delegating_method?
+          subject.respond_to?(delegating_method)
+        end
+
+        def subject_has_target_method?
+          subject.respond_to?(target_method)
+        end
+
+        def ensure_target_method_is_present!
+          if target_method.blank?
+            raise TargetNotDefinedError
+          end
+        end
+
+        def subject_delegates_to_target_correctly?
+          register_subject_double_collection
+
+          Doublespeak.with_doubles_activated do
+            subject.public_send(delegating_method, *delegated_arguments)
+          end
+
+          if delegated_arguments.any?
+            target_received_method_with_delegated_arguments?
+          else
+            target_received_method?
+          end
+        end
+
+        def register_subject_double_collection
+          double_collection =
+            Doublespeak.register_double_collection(subject.singleton_class)
+          double_collection.register_stub(target_method).
+            to_return(target_double)
+
+          @subject_double_collection = double_collection
+        end
+
+        def calls_to_method_on_target
+          target_double.calls_to(method_on_target)
+        end
+
+        def calls_on_target
+          target_double.calls
+        end
+
+        def formatted_calls_on_target
+          string = ""
+
+          if calls_on_target.any?
+            string << "\n"
+            calls_on_target.each_with_index do |call, i|
+              name = call.method_name
+              args = call.args.map { |arg| arg.inspect }.join(', ')
+              string << "#{i+1}) #{name}(#{args})\n"
+            end
+          else
+            string << " (none)"
+          end
+
+          string
+        end
+
+        # @private
+        class TargetNotDefinedError < StandardError
+          def message
+            'Delegation needs a target. Use the #to method to define one, e.g.
+            `post_office.should delegate(:deliver_mail).to(:mailman)`'.squish
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoulda/matchers/independent.rb

@@ -0,0 +1,10 @@
+require 'shoulda/matchers/independent/delegate_matcher'
+require 'shoulda/matchers/independent/delegate_matcher/stubbed_target'
+
+module Shoulda
+  module Matchers
+    # Matchers for non-Rails-dependent code.
+    module Independent
+    end
+  end
+end