rspec-sleeping_king_studios 2.1.1 → 2.2.0.rc.1

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

@@ -0,0 +1,96 @@
+# subl lib/rspec/sleeping_king_studios/matchers/core/have_reader_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_property'
+
+module RSpec::SleepingKingStudios::Matchers::Core
+  # Matcher for testing whether an object has a specific property reader, e.g.
+  # responds to :property.
+  #
+  # @since 1.0.0
+  class HaveReaderMatcher < RSpec::SleepingKingStudios::Matchers::BaseMatcher
+    include RSpec::SleepingKingStudios::Matchers::Shared::MatchProperty
+
+    # (see BaseMatcher#description)
+    def description
+      value_message = value_to_string
+      "have reader :#{@expected}#{@value_set ? " with value #{value_message}" : ''}"
+    end # method description
+
+    # @param [String, Symbol] expected The property to check for on the actual
+    #   object.
+    def initialize expected
+      @expected = expected.intern
+    end # method initialize
+
+    # (see BaseMatcher#does_not_match?)
+    def does_not_match? actual
+      super
+
+      matches_reader?(:none?)
+    end # method does_not_match?
+
+    # Checks if the object responds to #expected. Additionally, if a value
+    # expectation is set, compares the value of #expected to the specified
+    # value.
+    #
+    # @param [Object] actual The object to check.
+    #
+    # @return [Boolean] true If the object responds to #expected and matches
+    #    the value expectation (if any); otherwise false.
+    def matches? actual
+      super
+
+      matches_reader?(:all?)
+    end # method matches?
+
+    # Sets a value expectation. The matcher will compare the value from
+    # #property with the specified value.
+    #
+    # @param [Object] value The value to compare.
+    #
+    # @return [HaveReaderMatcher] self
+    def with value
+      @value = value
+      @value_set = true
+      self
+    end # method with
+    alias_method :with_value, :with
+
+    # (see BaseMatcher#failure_message)
+    def failure_message
+      message = "expected #{@actual.inspect} to respond to :#{@expected}"
+      message << " and return #{value_to_string}" if @value_set
+
+      if !@matches_reader
+        message << ", but did not respond to :#{@expected}"
+      elsif !@matches_reader_value
+        message << ", but returned #{@actual.send(@expected).inspect}"
+      end # if
+
+      message
+    end # method failure_message
+
+    # (see BaseMatcher#failure_message_when_negated)
+    def failure_message_when_negated
+      message = "expected #{@actual.inspect} not to respond to :#{@expected}"
+      message << " and return #{value_to_string}" if @value_set
+
+      errors = []
+      errors << "responded to :#{@expected}" if @matches_reader
+      errors << "returned #{@actual.send(@expected).inspect}" if @matches_reader_value
+
+      message << ", but #{errors.join(" and ")}"
+      message
+    end # method failure_message
+
+    private
+
+    def matches_reader? filter
+      [ responds_to_reader?,
+        matches_reader_value?
+      ].send(filter) { |bool| bool }
+    end # method matches_property?
+  end # class
+end # module

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

@@ -1,64 +1,9 @@
-# lib/rspec/sleeping_king_studios/matchers/core/have_mutator.rb
+# lib/rspec/sleeping_king_studios/matchers/core/have_writer.rb
 
-require 'rspec/sleeping_king_studios/matchers/base_matcher'
-require 'rspec/sleeping_king_studios/matchers/core'
-require 'rspec/sleeping_king_studios/matchers/shared/match_property'
+require 'rspec/sleeping_king_studios/matchers/core/have_writer_matcher'
+require 'rspec/sleeping_king_studios/matchers/macros'
 
-module RSpec::SleepingKingStudios::Matchers::Core
-  # Matcher for testing whether an object has a specific property writer, e.g.
-  # responds to :property= and updates the state.
-  #
-  # @since 1.0.0
-  class HaveWriterMatcher < RSpec::SleepingKingStudios::Matchers::BaseMatcher
-    include RSpec::SleepingKingStudios::Matchers::Shared::MatchProperty
-
-    # Generates a description of the matcher expectation.
-    #
-    # @return [String] The matcher description.
-    def description
-      "have writer :#{@expected}"
-    end # method description
-
-    # @param [String, Symbol] expected the property to check for on the actual
-    #   object
-    def initialize expected
-      @expected = expected.to_s.gsub(/=$/,'').intern
-    end # method initialize
-
-    # Checks if the object responds to :expected=. Additionally, if a value
-    # expectation is set, assigns the value via :expected= and compares the
-    # subsequent value to the specified value using :expected or the block
-    # provided to #with.
-    #
-    # @param [Object] actual the object to check
-    #
-    # @return [Boolean] true if the object responds to :expected= and matches
-    #    the value expectation (if any); otherwise false
-    def matches? actual
-      super
-
-      responds_to_writer?
-    end # method matches?
-
-    # @see BaseMatcher#failure_message
-    def failure_message
-      message = "expected #{@actual.inspect} to respond to :#{@expected}="
-
-      if !@matches_writer
-        message << ", but did not respond to :#{@expected}="
-      end # if
-
-      message
-    end # method failure_message
-
-    # @see BaseMatcher#failure_message_when_negated
-    def failure_message_when_negated
-      "expected #{@actual.inspect} not to respond to :#{@expected}="
-    end # method failure_message
-  end # class
-end # module
-
-module RSpec::SleepingKingStudios::Matchers
+module RSpec::SleepingKingStudios::Matchers::Macros
   # @see RSpec::SleepingKingStudios::Matchers::Core::HaveWriterMatcher#matches?
   def have_writer expected
     RSpec::SleepingKingStudios::Matchers::Core::HaveWriterMatcher.new expected

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

@@ -0,0 +1,55 @@
+# lib/rspec/sleeping_king_studios/matchers/core/have_writer_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_property'
+
+module RSpec::SleepingKingStudios::Matchers::Core
+  # Matcher for testing whether an object has a specific property writer, e.g.
+  # responds to :property= and updates the state.
+  #
+  # @since 1.0.0
+  class HaveWriterMatcher < RSpec::SleepingKingStudios::Matchers::BaseMatcher
+    include RSpec::SleepingKingStudios::Matchers::Shared::MatchProperty
+
+    # Generates a description of the matcher expectation.
+    #
+    # @return [String] The matcher description.
+    def description
+      "have writer :#{@expected}"
+    end # method description
+
+    # @param [String, Symbol] expected the property to check for on the actual
+    #   object
+    def initialize expected
+      @expected = expected.to_s.gsub(/=$/,'').intern
+    end # method initialize
+
+    # Checks if the object responds to :expected=. Additionally, if a value
+    # expectation is set, assigns the value via :expected= and compares the
+    # subsequent value to the specified value using :expected or the block
+    # provided to #with.
+    #
+    # @param [Object] actual the object to check
+    #
+    # @return [Boolean] true if the object responds to :expected= and matches
+    #    the value expectation (if any); otherwise false
+    def matches? actual
+      super
+
+      responds_to_writer?
+    end # method matches?
+
+    # @see BaseMatcher#failure_message
+    def failure_message
+      "expected #{@actual.inspect} to respond to :#{@expected}="\
+      ", but did not respond to :#{@expected}="
+    end # method failure_message
+
+    # @see BaseMatcher#failure_message_when_negated
+    def failure_message_when_negated
+      "expected #{@actual.inspect} not to respond to :#{@expected}="\
+      ", but responded to :#{@expected}="
+    end # method failure_message
+  end # class
+end # module

data/lib/rspec/sleeping_king_studios/matchers/description.rb

@@ -0,0 +1,62 @@
+# lib/rspec/sleeping_king_studios/matchers/description.rb
+
+require 'rspec/sleeping_king_studios/matchers'
+
+require 'sleeping_king_studios/tools/array_tools'
+require 'sleeping_king_studios/tools/string_tools'
+
+module RSpec::SleepingKingStudios::Matchers
+  # Reusable logic for building a matcher description across different versions
+  # of the base RSpec library.
+  #
+  # @since 2.2.0
+  module Description
+    # @api private
+    DEFAULT_EXPECTED_ITEMS = Object.new
+
+    # A short string that describes the purpose of the matcher.
+    #
+    # @return [String] the matcher description
+    def description
+      desc = matcher_name
+
+      desc << format_expected_items
+
+      desc
+    end # method description
+
+    private
+
+    def expected_items_for_description
+      defined?(@expected) ? @expected : DEFAULT_EXPECTED_ITEMS
+    end # method expected_items_for_description
+
+    def format_expected_items
+      expected_items = expected_items_for_description
+
+      return '' if expected_items == DEFAULT_EXPECTED_ITEMS
+
+      if defined?(RSpec::Matchers::EnglishPhrasing)
+        # RSpec 3.4+
+        RSpec::Matchers::EnglishPhrasing.list(expected_items)
+      elsif defined?(to_sentence)
+        # RSpec 3.0-3.3
+        to_sentence(expected_items)
+      else
+        array_tools = ::SleepingKingStudios::Tools::ArrayTools
+        processed   = [expected_items].flatten.map(&:inspect)
+
+        ' ' << array_tools.humanize_list(processed)
+      end # if-elsif-else
+    end # method format_expected_items
+
+    def matcher_name
+      return @matcher_name if @matcher_name
+
+      string_tools = ::SleepingKingStudios::Tools::StringTools
+      name         = string_tools.underscore(self.class.name.split('::').last)
+
+      @matcher_name = name.tr('_', ' ').sub(/ matcher\z/, '')
+    end # method matcher_name
+  end # module
+end # module

data/lib/rspec/sleeping_king_studios/matchers/macros.rb

@@ -0,0 +1,32 @@
+# lib/rspec/sleeping_king_studios/matchers/macros.rb
+
+require 'rspec/sleeping_king_studios/matchers'
+
+module RSpec::SleepingKingStudios::Matchers
+  module Macros
+    # @see RSpec::Matchers::alias_matcher
+    def self.alias_matcher(new_name, old_name, options = {}, &description_override)
+      description_override ||= if defined?(RSpec::Matchers::Pretty)
+        ->(str) { str.gsub(RSpec::Matchers::Pretty.split_words(old_name), RSpec::Matchers::Pretty.split_words(new_name)) }
+      elsif defined?(RSpec::Matchers::EnglishPhrasing)
+        ->(str) { str.gsub(RSpec::Matchers::EnglishPhrasing.split_words(old_name), RSpec::Matchers::EnglishPhrasing.split_words(new_name)) }
+      else
+        ->(str) { str }
+      end # if-elsif-else
+
+      klass = (options.is_a?(Hash) ? options[:klass] : nil) || RSpec::Matchers::AliasedMatcher
+      define_method(new_name) do |*args, &block|
+        matcher = __send__(old_name, *args, &block)
+
+        klass.new(matcher, description_override)
+      end # define_method
+    end # class method alias_matcher
+  end # module
+
+  # Ensure macros are defined on parent module for compatibility reasons.
+  include Macros
+end # module
+
+RSpec.configure do |config|
+  config.include RSpec::SleepingKingStudios::Matchers::Macros
+end # configuration

data/lib/rspec/sleeping_king_studios/matchers/shared/match_parameters.rb

@@ -1,89 +1,191 @@
 # lib/rspec/sleeping_king_studios/matchers/shared/parameters_matcher.rb
 
 require 'rspec/sleeping_king_studios/matchers'
+require 'sleeping_king_studios/tools/array_tools'
+require 'rspec/sleeping_king_studios/support/method_signature_expectation'
 
 module RSpec::SleepingKingStudios::Matchers::Shared
   # Helper methods for checking the parameters and keywords (Ruby 2.0 only) of
   # a method.
   module MatchParameters
-    # Checks whether the method accepts the specified number or range of
-    # arguments.
+    # Convenience method for more fluent specs. Does nothing and returns self.
     #
-    # @param [Method] method the method to check
-    # @param [Integer, Range] arity the expected number or range of parameters
+    # @return self
+    def argument
+      self
+    end # method argument
+    alias_method :arguments, :argument
+
+    # Adds a parameter count expectation and/or one or more keyword
+    # expectations.
     #
-    # @return [Boolean] true if the method accepts the specified number or both
-    #   the specified minimum and maximum number of parameters; otherwise false
-    def check_method_arity method, arity, expect_unlimited_arguments: false
-      parameters = method.parameters
-      required   = parameters.count { |type, | :req  == type }
-      optional   = parameters.count { |type, | :opt  == type }
-      variadic   = parameters.count { |type, | :rest == type }
-      reasons    = {}
-
-      reasons[:expected_unlimited_arguments] = { count: required + optional } if 0 == variadic && expect_unlimited_arguments
-
-      min, max = arity.is_a?(Range) ?
-        [arity.begin, arity.end] :
-        [arity,       arity]
-
-      if min && min < required
-        reasons[:not_enough_args] = { arity: min, count: required }
-      elsif max && 0 == variadic && max > required + optional
-        reasons[:too_many_args]   = { arity: max, count: required + optional }
-      end # if
+    # @overload with count
+    #   Adds a parameter count expectation.
+    #
+    #   @param [Integer, Range, nil] count (optional) The number of expected
+    #     parameters.
+    #
+    #   @return [RespondToMatcher] self
+    # @overload with *keywords
+    #   Adds one or more keyword expectations.
+    #
+    #   @param [Array<String, Symbol>] keywords List of keyword arguments
+    #     accepted by the method.
+    #
+    #   @return self
+    # @overload with count, *keywords
+    #   Adds a parameter count expectation and one or more keyword
+    #   expectations.
+    #
+    #   @param [Integer, Range, nil] count (optional) The number of expected
+    #     parameters.
+    #   @param [Array<String, Symbol>] keywords List of keyword arguments
+    #     accepted by the method.
+    #
+    #   @return self
+    def with *keywords
+      case keywords.first
+      when Range
+        arity = keywords.shift
+
+        method_signature_expectation.min_arguments = arity.begin
+        method_signature_expectation.max_arguments = arity.end
+      when Integer
+        arity = keywords.shift
+
+        method_signature_expectation.min_arguments = arity
+        method_signature_expectation.max_arguments = arity
+      end # case
 
-      reasons.empty? ? nil : reasons
-    end # method check_method_arity
+      method_signature_expectation.keywords = keywords
 
-    # Checks whether the method accepts the specified keywords.
+      self
+    end # method with
+
+    # Adds a block expectation. The actual object will only match a block
+    # expectation if it expects a parameter of the form &block.
     #
-    # @param [Method] method the method to check
-    # @param [Array<String, Symbol>] keywords the expected keywords
+    # @return self
+    def with_a_block
+      method_signature_expectation.block_argument = true
+
+      self
+    end # method with_a_block
+    alias_method :and_a_block, :with_a_block
+
+    # 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
+      method_signature_expectation.any_keywords = true
+
+      self
+    end # method with_arbitrary_keywords
+    alias_method :and_arbitrary_keywords, :with_arbitrary_keywords
+    alias_method :with_any_keywords,      :with_arbitrary_keywords
+    alias_method :and_any_keywords,       :with_any_keywords
+
+    # Adds one or more keyword expectations.
+    #
+    # @param [Array<String, Symbol>] keywords List of keyword arguments
+    #   accepted by the method.
+    #
+    # @return self
+    def with_keywords *keywords
+      method_signature_expectation.keywords = keywords
+
+      self
+    end # method with_keywords
+    alias_method :and_keywords, :with_keywords
+
+    # Adds an unlimited parameter count expectation, e.g. that the method
+    # supports splatted array arguments of the form *args.
     #
-    # @return [Boolean] true if the method accepts the specified keywords;
-    #   otherwise false
-    def check_method_keywords method, keywords, expect_arbitrary_keywords: false
-      keywords ||= []
-      parameters = method.parameters
-      reasons    = {}
-
-      # Check for missing required keywords.
-      if RUBY_VERSION >= "2.1.0"
-        missing = []
-        parameters.select { |type, _| :keyreq == type }.each do |_, keyword|
-          missing << keyword unless keywords.include?(keyword)
-        end # each
-
-        reasons[:missing_keywords] = missing unless missing.empty?
+    # @return self
+    def with_unlimited_arguments
+      method_signature_expectation.unlimited_arguments = true
+
+      self
+    end # method with_unlimited_arguments
+    alias_method :and_unlimited_arguments, :with_unlimited_arguments
+
+    private
+
+    # @api private
+    def check_method_signature method
+      method_signature_expectation.matches?(method)
+    end # method check_method_signature
+
+    # @api private
+    def format_errors errors
+      messages = []
+
+      # TODO: Replace this with "  expected :arity arguments, but method can "\
+      # "receive :count arguments", with :count being one of the following:
+      # - an integer (for methods that do not have optional or variadic params)
+      # - between :min and :max (for methods with optional but not variadic
+      #   params)
+      # - at least :min (for methods with variadic params)
+      if hsh = errors.fetch(:not_enough_args, false)
+        messages << "  expected at least #{hsh[:expected]} arguments, but received #{hsh[:received]}"
       end # if
 
-      unless 0 < parameters.count { |type, _| :keyrest == type }
-        reasons[:expected_arbitrary_keywords] = true if expect_arbitrary_keywords
+      if hsh = errors.fetch(:too_many_args, false)
+        messages << "  expected at most #{hsh[:expected]} arguments, but received #{hsh[:received]}"
+      end # if
 
-        mismatch = []
-        keywords.each do |keyword|
-          mismatch << keyword unless
-            parameters.include?([:key,    keyword]) ||
-            parameters.include?([:keyreq, keyword])
-        end # each
+      # TODO: Replace this with "  expected method to receive unlimited "\
+      # "arguments, but method can receive at most :max arguments"
+      if hsh = errors.fetch(:no_variadic_args, false)
+        messages << "  expected at most #{hsh[:expected]} arguments, but received unlimited arguments"
+      end # if
 
-        reasons[:unexpected_keywords] = mismatch unless mismatch.empty?
-      end # unless
+      # TODO: Replace this with "  expected method to receive arbitrary "\
+      # "keywords, but the method can receive :keyword_list", with
+      # :keyword_list being a comma-separated list. If the method cannot
+      # receive keywords, replace last fragment with ", but the method cannot"\
+      # " receive keywords"
+      if errors.fetch(:no_variadic_keywords, false)
+        messages << "  expected arbitrary keywords"
+      end # if
 
-      reasons.empty? ? nil : reasons
-    end # method check_method_keywords
+      # TODO: Replace this with "  expected method to receive keywords "\
+      # ":received_list, but the method requires keywords :required_list"
+      if ary = errors.fetch(:missing_keywords, false)
+        tools = ::SleepingKingStudios::Tools::ArrayTools
 
-    # Checks whether the method expects a block.
-    #
-    # @param [Method] method the method to check
-    #
-    # @return [Boolean] true if the method expects a block argument; otherwise
-    #   false
-    def check_method_block method
-      0 == method.parameters.count { |type, | :block == type } ? { :expected_block => true } : nil
-    end # method check_method_block
+        messages <<
+          "  missing keyword#{ary.count == 1 ? '' : 's'} "\
+          "#{tools.humanize_list ary.map(&:inspect)}"
+      end # if
+
+      # TODO: Replace this with "  expected method to receive keywords "\
+      # ":received_list, but the method can receive :keyword_list"
+      if ary = errors.fetch(:unexpected_keywords, false)
+        tools = ::SleepingKingStudios::Tools::ArrayTools
+
+        messages <<
+          "  unexpected keyword#{ary.count == 1 ? '' : 's'} "\
+          "#{tools.humanize_list ary.map(&:inspect)}"
+      end # if
+
+      # TODO: Replace this with "  expected method to receive a block "\
+      # "argument, but the method signature does not specify a block argument"
+      if errors.fetch(:no_block_argument, false)
+        messages << "  unexpected block"
+      end # if
+
+      messages.join "\n"
+    end # method format_errors
+
+    # @api private
+    def method_signature_expectation
+      @method_signature_expectation ||=
+        ::RSpec::SleepingKingStudios::Support::MethodSignatureExpectation.new
+    end # method_signature_expectation
 
-    private :check_method_arity, :check_method_block, :check_method_keywords
+    # @api private
+    def method_signature_expectation?
+      !!@method_signature_expectation
+    end # method_signature_expectation
   end # module
 end # module

data/lib/rspec/sleeping_king_studios/matchers/shared/match_property.rb

@@ -5,6 +5,23 @@ module RSpec::SleepingKingStudios::Matchers::Shared
   module MatchProperty
     private
 
+    # Checks whether the value of the predicate matches the expected value. If
+    # the value looks like an RSpec matcher (it responds to :matches?), runs
+    # value.matches?(); otherwise checks for equality using :==.
+    #
+    # @return [Boolean] true if the value matches the expected value; otherwise
+    #   false.
+    def matches_predicate_value?
+      return false unless responds_to_predicate?
+      return true  unless @value_set
+
+      actual_value = @actual.send(:"#{@expected}?")
+
+      @matches_predicate_value = (@value.respond_to?(:matches?) && @value.respond_to?(:description)) ?
+        @value.matches?(actual_value) :
+        @value == actual_value
+    end # method matches_reader_value?
+
     # Checks whether the value of the reader matches the expected value. If the
     # value looks like an RSpec matcher (it responds to :matches?), runs
     # value.matches?(); otherwise checks for equality using :==.
@@ -22,6 +39,14 @@ module RSpec::SleepingKingStudios::Matchers::Shared
         @value == actual_value
     end # method matches_reader_value?
 
+    # Checks whether the object responds to the predicate method :#{property}?.
+    #
+    # @return [Boolean] true if the object responds to the method; otherwise
+    #   false.
+    def responds_to_predicate?
+      @matches_predicate = @actual.respond_to?(:"#{@expected}?")
+    end # method responds_to_predicate?
+
     # Checks whether the object responds to the reader method :#{property}.
     #
     # @return [Boolean] true if the object responds to the method; otherwise

data/lib/rspec/sleeping_king_studios/matchers.rb

@@ -6,7 +6,3 @@ module RSpec::SleepingKingStudios
   # Custom matchers for use with RSpec::Expectations.
   module Matchers; end
 end # module
-
-RSpec.configure do |config|
-  config.include RSpec::SleepingKingStudios::Matchers
-end # configuration

data/lib/rspec/sleeping_king_studios/support/method_signature.rb

@@ -0,0 +1,51 @@
+# lib/rspec/sleeping_king_studios/support/method_signature.rb
+
+require 'rspec/sleeping_king_studios/support'
+
+module RSpec::SleepingKingStudios::Support
+  # @api private
+  class MethodSignature
+    def initialize method
+      parameters = method.parameters
+
+      required = parameters.count { |type, _| :req  == type }
+      optional = parameters.count { |type, _| :opt  == type }
+      variadic = parameters.count { |type, _| :rest == type }
+
+      @min_arguments       = required
+      @max_arguments       = required + optional
+      @unlimited_arguments = variadic > 0
+
+      required = parameters.select { |type, _| :keyreq  == type }.map { |_, keyword| keyword }
+      optional = parameters.select { |type, _| :key     == type }.map { |_, keyword| keyword }
+      variadic = parameters.count  { |type, _| :keyrest == type }
+
+      @required_keywords = required
+      @optional_keywords = optional
+      @any_keywords      = variadic > 0
+
+      @block_argument = parameters.count { |type, _| :block == type } > 0
+    end # method initialize
+
+    attr_reader :min_arguments,
+      :max_arguments,
+      :optional_keywords,
+      :required_keywords
+
+    def any_keywords?
+      !!@any_keywords
+    end # method any_keywords?
+
+    def block_argument?
+      !!@block_argument
+    end # method block_argument?
+
+    def keywords
+      @optional_keywords + @required_keywords
+    end # method keywords
+
+    def unlimited_arguments?
+      !!@unlimited_arguments
+    end # method unlimited_arguments?
+  end # class
+end # module