rspec-sleeping_king_studios 2.1.1 → 2.2.0.rc.1

data/lib/rspec/sleeping_king_studios/matchers/core/construct.rb

@@ -1,216 +1,9 @@
 # spec/rspec/sleeping_king_studios/matchers/core/construct.rb
 
-require 'rspec/sleeping_king_studios/matchers/base_matcher'
-require 'rspec/sleeping_king_studios/matchers/core'
-require 'rspec/sleeping_king_studios/matchers/shared/match_parameters'
-require 'sleeping_king_studios/tools/enumerable_tools'
-require 'sleeping_king_studios/tools/string_tools'
+require 'rspec/sleeping_king_studios/matchers/core/construct_matcher'
+require 'rspec/sleeping_king_studios/matchers/macros'
 
-module RSpec::SleepingKingStudios::Matchers::Core
-  # Matcher for checking whether an object can be constructed via #new and
-  # #initialize, and the parameters accepted by #initialize.
-  #
-  # @since 1.0.0
-  class ConstructMatcher < RSpec::SleepingKingStudios::Matchers::BaseMatcher
-    include RSpec::SleepingKingStudios::Matchers::Shared::MatchParameters
-    include SleepingKingStudios::Tools::EnumerableTools
-    include SleepingKingStudios::Tools::StringTools
-
-    # (see BaseMatcher#description)
-    def description
-      expected_message = format_expected_arguments
-      "construct#{expected_message.empty? ? '' : " with #{expected_message}"}"
-    end # method description
-
-    # Checks if the object responds to :new. If so, allocates an instance and
-    # checks the parameters expected by #initialize against the expected
-    # parameters, if any.
-    #
-    # @param [Object] actual The object to check.
-    #
-    # @return [Boolean] True if the object responds to :new and accepts the
-    #   specified parameters for #initialize; otherwise false.
-    def matches? actual
-      @actual = actual
-      @failing_method_reasons = {}
-      @actual.respond_to?(:new) &&
-        matches_arity?(actual) &&
-        matches_keywords?(actual)
-    end # method matches?
-
-    # Adds a parameter count expectation and/or one or more keyword
-    # expectations.
-    #
-    # @overload with(count)
-    #   Adds a parameter count expectation and removes any keyword
-    #   expectations.
-    #
-    #   @param [Integer, Range] count The number of expected parameters.
-    #
-    #   @return [ConstructMatcher] self
-    #
-    # @overload with(count, *keywords)
-    #   Adds a parameter count expectation and one or more keyword
-    #   expectations.
-    #
-    #   @param [Integer, Range] count The number of expected parameters.
-    #   @param [Array<String, Symbol>] keywords List of keyword arguments
-    #     accepted by the method.
-    #
-    #   @return [ConstructMatcher] self
-    #
-    # @overload with(*keywords)
-    #   Removes a parameter count expectation (if any) and adds one or more
-    #   keyword expectations.
-    #
-    #   @param [Array<String, Symbol>] keywords List of keyword arguments
-    #     accepted by the method.
-    #
-    #   @return [ConstructMatcher] self
-    def with *keywords
-      @expected_arity    = keywords.shift if Integer === keywords.first || Range === keywords.first
-      @expected_keywords = keywords
-      self
-    end # method with
-
-    # Adds an unlimited parameter count expectation, e.g. that the method
-    # supports splatted array arguments of the form *args.
-    #
-    # @return [RespondToMatcher] self
-    def with_unlimited_arguments
-      @expect_unlimited_arguments = true
-
-      self
-    end # method with_unlimited_arguments
-    alias_method :and_unlimited_arguments, :with_unlimited_arguments
-
-    # Adds one or more keyword expectations.
-    #
-    # @param [Array<String, Symbol>] keywords List of keyword arguments
-    #   accepted by the method.
-    #
-    # @return [RespondToMatcher] self
-    def with_keywords *keywords
-      (@expected_keywords ||= []).concat(keywords)
-
-      self
-    end # method with_keywords
-    alias_method :and_keywords, :with_keywords
-
-    # Adds an arbitrary keyword expectation, e.g. that the method supports
-    # any keywords with splatted hash arguments of the form **kwargs.
-    def with_arbitrary_keywords
-      @expect_arbitrary_keywords = true
-
-      self
-    end # method with_arbitrary_keywords
-    alias_method :and_arbitrary_keywords, :with_arbitrary_keywords
-
-    # Convenience method for more fluent specs. Does nothing and returns self.
-    #
-    # @return [ConstructMatcher] self
-    #
-    # @since 2.0.0
-    def argument
-      self
-    end # method argument
-    alias_method :arguments, :argument
-
-    # (see BaseMatcher#failure_message)
-    def failure_message
-      message = "expected #{@actual.inspect} to be constructible"
-      message << " with arguments:\n#{format_errors}" if @actual.respond_to?(:new)
-      message
-    end # method failure_message
-
-    # (see BaseMatcher#failure_message_when_negated)
-    def failure_message_when_negated
-      message = "expected #{@actual.inspect} not to be constructible"
-      unless (formatted = format_expected_arguments).empty?
-        message << " with #{formatted}"
-      end # unless
-      message
-    end # method failure_message_when_negated
-
-    private
-
-    def matches_arity? actual
-      return true unless @expected_arity || @expect_unlimited_arguments
-
-      if result = check_method_arity(actual.allocate.method(:initialize), @expected_arity, expect_unlimited_arguments: @expect_unlimited_arguments)
-        @failing_method_reasons.update result
-        return false
-      end # if
-
-      true
-    end # method matches_arity?
-
-    def matches_keywords? actual
-      return true unless @expected_keywords ||
-        @expect_arbitrary_keywords ||
-        (@expected_arity && RUBY_VERSION >= "2.1.0")
-
-      if result = check_method_keywords(actual.allocate.method(:initialize), @expected_keywords, expect_arbitrary_keywords: @expect_arbitrary_keywords)
-        @failing_method_reasons.update result
-        return false
-      end # if
-
-      true
-    end # method matches_keywords?
-
-    def format_expected_arguments
-      messages = []
-
-      if !@expected_arity.nil?
-        messages << "#{@expected_arity.inspect} argument#{1 == @expected_arity ? "" : "s"}"
-      end # if
-
-      if @expect_unlimited_arguments
-        messages << 'unlimited arguments'
-      end # if
-
-      if !(@expected_keywords.nil? || @expected_keywords.empty?)
-        messages << "#{pluralize @expected_keywords.count, 'keyword', 'keywords'} #{humanize_list @expected_keywords.map(&:inspect)}"
-      end # if
-
-      if @expect_arbitrary_keywords
-        messages << 'arbitrary keywords'
-      end # if
-
-      humanize_list messages
-    end # method format_expected_arguments
-
-    def format_errors
-      reasons, messages = @failing_method_reasons, []
-
-      if hsh = reasons.fetch(:not_enough_args, false)
-        messages << "  expected at least #{hsh[:count]} arguments, but received #{hsh[:arity]}"
-      elsif hsh = reasons.fetch(:too_many_args, false)
-        messages << "  expected at most #{hsh[:count]} arguments, but received #{hsh[:arity]}"
-      end # if-elsif
-
-      if hsh = reasons.fetch(:expected_unlimited_arguments, false)
-        messages << "  expected at most #{hsh[:count]} arguments, but received unlimited arguments"
-      end # if
-
-      if ary = reasons.fetch(:missing_keywords, false)
-        messages << "  missing #{pluralize ary.count, 'keyword', 'keywords'} #{humanize_list ary.map(&:inspect)}"
-      end # if
-
-      if ary = reasons.fetch(:unexpected_keywords, false)
-        messages << "  unexpected #{pluralize ary.count, 'keyword', 'keywords'} #{humanize_list ary.map(&:inspect)}"
-      end # if
-
-      if reasons.fetch(:expected_arbitrary_keywords, false)
-        messages << "  expected arbitrary keywords"
-      end # if
-
-      messages.join "\n"
-    end # method format_errors
-  end # class
-end # module
-
-module RSpec::SleepingKingStudios::Matchers
+module RSpec::SleepingKingStudios::Matchers::Macros
   # @see RSpec::SleepingKingStudios::Matchers::Core::ConstructMatcher#matches?
   def construct
     RSpec::SleepingKingStudios::Matchers::Core::ConstructMatcher.new

data/lib/rspec/sleeping_king_studios/matchers/core/construct_matcher.rb

@@ -0,0 +1,113 @@
+# lib/rspec/sleeping_king_studios/matchers/core/construct_matcher.rb
+
+require 'rspec/sleeping_king_studios/matchers/base_matcher'
+require 'rspec/sleeping_king_studios/matchers/core'
+require 'rspec/sleeping_king_studios/matchers/shared/match_parameters'
+
+module RSpec::SleepingKingStudios::Matchers::Core
+  # Matcher for checking whether an object can be constructed via #new and
+  # #initialize, and the parameters accepted by #initialize.
+  #
+  # @since 1.0.0
+  class ConstructMatcher < RSpec::SleepingKingStudios::Matchers::BaseMatcher
+    include RSpec::SleepingKingStudios::Matchers::Shared::MatchParameters
+
+    # (see BaseMatcher#description)
+    def description
+      message = 'construct'
+
+      if method_signature_expectation?
+        message << ' ' << method_signature_expectation.description
+      end # if
+
+      message
+    end # method description
+
+    # Checks if the object responds to :new. If so, allocates an instance and
+    # checks the parameters expected by #initialize against the expected
+    # parameters, if any.
+    #
+    # @param [Object] actual The object to check.
+    #
+    # @return [Boolean] True if the object responds to :new and accepts the
+    #   specified parameters for #initialize; otherwise false.
+    def matches? actual
+      @actual = actual
+      @failing_method_reasons = {}
+
+      unless @actual.respond_to?(:new, @include_all)
+        @failing_method_reasons = {
+          :does_not_respond_to_new => true
+        } # end hash
+
+        return false
+      end # unless
+
+      instance =
+        begin; actual.allocate; rescue NoMethodError; nil; end ||
+        begin; actual.new;      rescue StandardError; nil; end
+
+      if instance.nil?
+        @failing_method_reasons = {
+          :unable_to_create_instance => true
+        } # end hash
+
+        return false
+      end # unless
+
+      constructor =
+        begin; instance.method(:initialize); rescue NameError; nil; end
+
+      unless constructor.is_a?(Method)
+        @failing_method_reasons = {
+          :constructor_is_not_a_method => true
+        } # end hash
+
+        return false
+      end # unless
+
+      return true unless method_signature_expectation?
+
+      unless check_method_signature(constructor)
+        @failing_method_reasons = method_signature_expectation.errors
+
+        return false
+      end # unless
+
+      true
+    end # method matches?
+
+    # (see BaseMatcher#failure_message)
+    def failure_message
+      message = "expected #{@actual.inspect} to be constructible"
+
+      if @failing_method_reasons.key?(:does_not_respond_to_new)
+        message << ", but #{@actual.inspect} does not respond to ::new"
+      elsif @failing_method_reasons.key?(:unable_to_create_instance)
+        message << ", but was unable to allocate an instance of #{@actual.inspect} with ::allocate or ::new"
+      elsif @failing_method_reasons.key?(:constructor_is_not_a_method)
+        message <<
+          ", but was unable to reflect on constructor because :initialize is not a method on #{@actual.inspect}"
+      else
+        errors = @failing_method_reasons
+
+        # TODO: Replace this with ", but received arguments did not match "\
+        # " method signature:"
+        message << " with arguments:\n" << format_errors(errors)
+      end # if-elsif-else
+
+      message
+    end # method failure_message
+
+    # (see BaseMatcher#failure_message_when_negated)
+    def failure_message_when_negated
+      message = "expected #{@actual.inspect} not to be constructible"
+
+      if method_signature_expectation?
+        message << ' ' << method_signature_expectation.description
+      end # if
+
+      message
+    end # method failure_message_when_negated
+  end # class
+end # module

data/lib/rspec/sleeping_king_studios/matchers/core/delegate_method.rb

@@ -0,0 +1,11 @@
+# lib/rspec/sleeping_king_studios/matchers/core/delegate_method.rb
+
+require 'rspec/sleeping_king_studios/matchers/core/delegate_method_matcher'
+require 'rspec/sleeping_king_studios/matchers/macros'
+
+module RSpec::SleepingKingStudios::Matchers::Macros
+  # @see RSpec::SleepingKingStudios::Matchers::Core::DelegateMethodMatcher#matches?
+  def delegate_method *method_names
+    RSpec::SleepingKingStudios::Matchers::Core::DelegateMethodMatcher.new *method_names
+  end # method delegate_method
+end # module

data/lib/rspec/sleeping_king_studios/matchers/core/delegate_method_matcher.rb

@@ -0,0 +1,311 @@
+# lib/rspec/sleeping_king_studios/matchers/core/delegate_method_matcher.rb
+
+require 'rspec/sleeping_king_studios/matchers/base_matcher'
+
+require 'sleeping_king_studios/tools/array_tools'
+
+module RSpec::SleepingKingStudios::Matchers::Core
+  # Matcher for testing whether an object delegates a method to the specified
+  # other object.
+  #
+  # @since 2.2.0
+  class DelegateMethodMatcher < RSpec::SleepingKingStudios::Matchers::BaseMatcher
+    include RSpec::Mocks::ExampleMethods
+
+    # @api private
+    DEFAULT_EXPECTED_RETURN = Object.new.freeze
+
+    # @param expected [Array<String, Symbol>] The names of the methods that
+    #   should be delegated to the target.
+    def initialize expected
+      @expected               = expected
+      @expected_arguments     = []
+      @expected_keywords      = {}
+      @expected_block         = false
+      @received_block         = false
+      @expected_return_values = []
+      @received_return_values = []
+      @errors                 = {}
+    end # method initialize
+
+    attr_reader :expected
+    alias_method :method_name, :expected
+
+    # Specifies that the actual method, when called, will return the specified
+    # value. If more than one return value is specified, the method will be
+    # called one time for each return value, and on the Nth call must return
+    # the Nth specified return value.
+    #
+    # @param return_values [Array<Object>] The expected values to be returned
+    # from calling the method on the actual object.
+    #
+    # @return [DelegateMethodMatcher] self
+    def and_return *return_values
+      @expected_return_values = return_values
+
+      self
+    end # method and_return
+
+    # (see BaseMatcher#description)
+    def description
+      str = 'delegate method'
+      str << " :#{@expected}" if @expected
+      str << " to #{@target.inspect}" if @target
+      str
+    end # method description
+
+    # (see BaseMatcher#failure_message)
+    def failure_message
+      message =
+        "expected #{@actual.inspect} to delegate :#{@expected} to "\
+        "#{@target.inspect}"
+
+      if @errors.key?(:actual_does_not_respond_to)
+        message << ", but #{@actual.inspect} does not respond to :#{@expected}"
+
+        return message
+      end # if
+
+      if @errors.key?(:target_does_not_respond_to)
+        message << ", but #{@target.inspect} does not respond to :#{@expected}"
+
+        return message
+      end # if
+
+      if @errors.key?(:raised_exception)
+        exception = @errors[:raised_exception]
+
+        message << format_arguments << format_return_values <<
+          ", but ##{@expected} raised #{exception.class.name}: "\
+          "#{exception.message}"
+
+        return message
+      end # if
+
+      if @errors.key?(:actual_does_not_delegate_to_target)
+        message <<
+          ", but calling ##{@expected} on the object does not call "\
+          "##{@expected} on the delegate"
+
+        return message
+      end # if
+
+      message << format_arguments << format_return_values
+
+      if @errors.key?(:unexpected_arguments)
+        message << ", but #{@errors[:unexpected_arguments]}"
+
+        return message
+      end # if
+
+      if @errors.key?(:block_not_received)
+        message << ', but the block was not passed to the delegate'
+
+        return message
+      end # if
+
+      if @errors.key?(:unexpected_return)
+        values = @errors[:unexpected_return].map &:inspect
+
+        message << ', but returned ' <<
+          SleepingKingStudios::Tools::ArrayTools.humanize_list(values)
+      end # if
+
+      message
+    end # method failure_message
+
+    # (see BaseMatcher#failure_message_when_negated)
+    def failure_message_when_negated
+      message =
+        "expected #{@actual.inspect} not to delegate :#{@expected} to "\
+        "#{@target.inspect}"
+
+      message << format_arguments << format_return_values
+    end # method failure_message_when_negated
+
+    # (see BaseMatcher#matches?)
+    def matches? actual
+      super
+
+      raise ArgumentError.new('must specify a target') if @target.nil?
+
+      responds_to_method? && delegates_method?
+    end # method matches?
+
+    # Specifies the target object. The expected methods should be delegated
+    # from the actual object to the target.
+    #
+    # @param target [Object] The target object.
+    #
+    # @return [DelegateMethodMatcher] self
+    def to target
+      @target = target
+
+      self
+    end # method to
+
+    # Specifies that a block argument must be passed in to the target when
+    # calling the method on the actual object.
+    #
+    # @return [DelegateMethodMatcher] self
+    def with_a_block
+      @expected_block = true
+
+      self
+    end # method with_a_block
+    alias_method :and_a_block, :with_a_block
+
+    # Specifies a list of arguments. The provided arguments are passed in to the
+    # method call when calling the method on the actual object, and must be
+    # passed on to the target.
+    #
+    # @param arguments [Array<Object>] The arguments to be passed in to the
+    #   method and which must be forwarded to the target.
+    #
+    # @return [DelegateMethodMatcher] self
+    def with_arguments *arguments
+      @expected_arguments = arguments
+
+      self
+    end # method with_arguments
+    alias_method :and_arguments, :with_arguments
+
+    # Specifies a hash of keywords and values. The provided keywords are passed
+    # in to the method call when calling the method on the actual object, and
+    # must be passed on to the target.
+    #
+    # @param keywords [Hash] The keywords to be passed in to the
+    #   method and which must be forwarded to the target.
+    #
+    # @return [DelegateMethodMatcher] self
+    def with_keywords **keywords
+      @expected_keywords = keywords
+
+      self
+    end # method with_keywords
+    alias_method :and_keywords, :with_keywords
+
+    private
+
+    def call_method arguments, expected_return = DEFAULT_EXPECTED_RETURN
+      if @expected_block
+        @received_block = false
+        block           = ->(*args, **kwargs, &block) {}
+
+        return_value = @actual.send(@expected, *arguments, &block)
+      else
+        return_value = @actual.send(@expected, *arguments)
+      end
+
+      @received_return_values << return_value
+
+      if @expected_block && !@received_block
+        @errors[:block_not_received] = true
+      end # if
+
+      return if expected_return == DEFAULT_EXPECTED_RETURN
+
+      unless return_value == expected_return
+        @errors[:unexpected_return] = @received_return_values
+      end # unless
+    rescue StandardError => exception
+      @errors[:raised_exception] = exception
+    end # method call_method
+
+    def delegates_method?
+      stub_target!
+
+      args = @expected_arguments.dup
+      args << @expected_keywords unless @expected_keywords.empty?
+
+      if @expected_return_values.empty?
+        call_method(args)
+      else
+        @expected_return_values.each do |return_value|
+          call_method(args, return_value)
+        end # each
+      end # if-else
+
+      matcher = RSpec::Mocks::Matchers::HaveReceived.new(@expected)
+      matcher = matcher.with(*args) unless args.empty?
+
+      unless @expected_return_values.empty?
+        matcher = matcher.exactly(@expected_return_values.count).times
+      end # unless
+
+      unless matcher.matches? @target
+        if matcher.failure_message =~ /with unexpected arguments/
+          @errors[:unexpected_arguments] = matcher.failure_message
+        else
+          @errors[:actual_does_not_delegate_to_target] = true
+        end # if
+      end # unless
+
+      @errors.empty?
+    end # method delegates_method?
+
+    def format_arguments
+      fragments = []
+
+      unless @expected_arguments.empty?
+        args = SleepingKingStudios::Tools::ArrayTools.humanize_list(@expected_arguments.map &:inspect)
+
+        fragments << ('arguments ' << args)
+      end # unless
+
+      unless @expected_keywords.empty?
+        kwargs = @expected_keywords.map { |key, value| "#{key.inspect}=>#{value.inspect}" }
+        kwargs = SleepingKingStudios::Tools::ArrayTools.humanize_list(kwargs)
+
+        fragments << ('keywords ' << kwargs)
+      end # unless
+
+      if fragments.empty?
+        arguments = ' with no arguments'
+      else
+        arguments = ' with ' << fragments.join(' and ')
+      end # if-else
+
+      arguments << ' and yield a block' if @expected_block
+
+      arguments
+    end # method format_arguments
+
+    def format_return_values
+      return '' if @expected_return_values.empty?
+
+      values = @expected_return_values.map &:inspect
+
+      ' and return ' << SleepingKingStudios::Tools::ArrayTools.humanize_list(values)
+    end # method format_return_values
+
+    def responds_to_method?
+      unless @actual.respond_to?(@expected)
+        @errors[:actual_does_not_respond_to] = true
+      end # unless
+
+      unless @target.respond_to?(@expected)
+        @errors[:target_does_not_respond_to] = true
+      end # unless
+
+      @errors.empty?
+    end # method responds_to_methods?
+
+    def stub_target!
+      original_method = @target.method(@expected)
+
+      receive_matcher = receive(@expected)
+      receive_matcher.with(any_args) do |*args, **kwargs, &block|
+        @received_block = !!block
+
+        if kwargs.empty?
+          original_method.call(*args, &block)
+        else
+          original_method.call(*args, **kwargs, &block)
+        end # if-else
+      end # matcher
+
+      allow(@target).to receive_matcher
+    end # metod stub_target!
+  end # class
+end # module

data/lib/rspec/sleeping_king_studios/matchers/core/have_constant.rb

@@ -0,0 +1,16 @@
+# lib/rspec/sleeping_king_studios/matchers/core/have_constant.rb
+
+require 'rspec/sleeping_king_studios/matchers/core/have_constant_matcher'
+require 'rspec/sleeping_king_studios/matchers/macros'
+
+module RSpec::SleepingKingStudios::Matchers::Macros
+  # @see RSpec::SleepingKingStudios::Matchers::Core::HaveConstantMatcher#matches?
+  def have_constant expected
+    RSpec::SleepingKingStudios::Matchers::Core::HaveConstantMatcher.new expected
+  end # method have_reader
+
+  # @see RSpec::SleepingKingStudios::Matchers::Core::HaveConstantMatcher#immutable
+  def have_immutable_constant expected
+    have_constant(expected).immutable
+  end # method have_reader
+end # module