rspec-expectations 3.0.0.beta1 → 3.0.0.beta2

data/lib/rspec/matchers/built_in/respond_to.rb

@@ -2,6 +2,8 @@ module RSpec
   module Matchers
     module BuiltIn
       class RespondTo
+        include Composable
+
         def initialize(*names)
           @names = names
           @expected_arity = nil
@@ -10,18 +12,17 @@ module RSpec
         def matches?(actual)
           find_failing_method_names(actual, :reject).empty?
         end
-        alias == matches?
 
         def does_not_match?(actual)
           find_failing_method_names(actual, :select).empty?
         end
 
-        def failure_message_for_should
+        def failure_message
           "expected #{@actual.inspect} to respond to #{@failing_method_names.collect {|name| name.inspect }.join(', ')}#{with_arity}"
         end
 
-        def failure_message_for_should_not
-          failure_message_for_should.sub(/to respond to/, 'not to respond to')
+        def failure_message_when_negated
+          failure_message.sub(/to respond to/, 'not to respond to')
         end
 
         def description

data/lib/rspec/matchers/built_in/satisfy.rb

@@ -2,6 +2,8 @@ module RSpec
   module Matchers
     module BuiltIn
       class Satisfy
+        include Composable
+
         def initialize(&block)
           @block = block
         end
@@ -11,13 +13,12 @@ module RSpec
           @actual = actual
           @block.call(actual)
         end
-        alias == matches?
 
-        def failure_message_for_should
+        def failure_message
           "expected #{@actual} to satisfy block"
         end
 
-        def failure_message_for_should_not
+        def failure_message_when_negated
           "expected #{@actual} not to satisfy block"
         end
 

data/lib/rspec/matchers/built_in/start_and_end_with.rb

@@ -3,44 +3,65 @@ module RSpec
     module BuiltIn
       class StartAndEndWith < BaseMatcher
         def initialize(*expected)
+          @actual_does_not_have_ordered_elements = false
           @expected = expected.length == 1 ? expected.first : expected
         end
 
-        def matches?(actual)
-          @actual = actual.respond_to?(:[]) ? actual : (raise ArgumentError.new("#{actual.inspect} does not respond to :[]"))
+        def match(expected, actual)
+          return false unless actual.respond_to?(:[])
+
           begin
-            @expected.respond_to?(:length) ? subset_matches?(@expected, @actual) : element_matches?(@expected, @actual)
+            return subset_matches? if expected.respond_to?(:length)
+            element_matches?
           rescue ArgumentError
-            raise ArgumentError.new("#{actual.inspect} does not have ordered elements")
+            @actual_does_not_have_ordered_elements = true
+            return false
           end
         end
 
-        def failure_message_for_should
-          "expected #{@actual.inspect} to #{self.class.name.split('::').last.sub(/With/,'').downcase} with #{@expected.inspect}"
+        def failure_message
+          super.tap do |msg|
+            if @actual_does_not_have_ordered_elements
+              msg << ", but it does not have ordered elements"
+            elsif !actual.respond_to?(:[])
+              msg << ", but it cannot be indexed using #[]"
+            end
+          end
         end
 
-        def failure_message_for_should_not
-          "expected #{@actual.inspect} not to #{self.class.name.split('::').last.sub(/With/,'').downcase} with #{@expected.inspect}"
+        def description
+          return super unless Hash === expected
+          "#{name_to_sentence} #{surface_descriptions_in(expected).inspect}"
+        end
+
+      private
+
+        def actual_is_unordered
+          ArgumentError.new("#{actual.inspect} does not have ordered elements")
         end
       end
 
       class StartWith < StartAndEndWith
-        def subset_matches?(expected, actual)
-          actual[0, expected.length] == expected
+        private
+
+        def subset_matches?
+          values_match?(expected, actual[0, expected.length])
         end
 
-        def element_matches?(expected, actual)
-          @actual[0] == @expected
+        def element_matches?
+          values_match?(expected, actual[0])
         end
       end
 
       class EndWith < StartAndEndWith
-        def subset_matches?(expected, actual)
-          actual[-expected.length, expected.length] == expected
+        private
+
+        def subset_matches?
+          values_match?(expected, actual[-expected.length, expected.length])
         end
 
-        def element_matches?(expected, actual)
-          actual[-1] == expected
+        def element_matches?
+          values_match?(expected, actual[-1])
         end
       end
     end

data/lib/rspec/matchers/built_in/throw_symbol.rb

@@ -2,6 +2,8 @@ module RSpec
   module Matchers
     module BuiltIn
       class ThrowSymbol
+        include Composable
+
         def initialize(expected_symbol = nil, expected_arg=nil)
           @expected_symbol = expected_symbol
           @expected_arg = expected_arg
@@ -45,19 +47,18 @@ module RSpec
                 if @expected_arg.nil?
                   return @caught_symbol == @expected_symbol
                 else
-                  return (@caught_symbol == @expected_symbol) & (@caught_arg == @expected_arg)
+                  return (@caught_symbol == @expected_symbol) && values_match?(@expected_arg, @caught_arg)
                 end
               end
             end
           end
         end
-        alias == matches?
 
-        def failure_message_for_should
+        def failure_message
           "expected #{expected} to be thrown, got #{caught}"
         end
 
-        def failure_message_for_should_not
+        def failure_message_when_negated
           "expected #{expected('no Symbol')}#{' not' if @expected_symbol} to be thrown, got #{caught}"
         end
 
@@ -79,7 +80,7 @@ module RSpec
           symbol_description = symbol.is_a?(String) ? symbol : symbol.inspect
 
           arg_description = if arg
-                              " with #{arg.inspect}"
+                              " with #{description_of arg}"
                             elsif @expected_arg && @caught_symbol == @expected_symbol
                               " with no argument"
                             else

data/lib/rspec/matchers/built_in/yield.rb

@@ -110,13 +110,13 @@ module RSpec
           self
         end
 
-        def failure_message_for_should
+        def failure_message
           'expected given block to yield control'.tap do |failure_message|
             failure_message << relativity_failure_message
           end
         end
 
-        def failure_message_for_should_not
+        def failure_message_when_negated
           'expected given block not to yield control'.tap do |failure_message|
             failure_message << relativity_failure_message
           end
@@ -162,11 +162,11 @@ module RSpec
           @probe.yielded_once?(:yield_with_no_args) && @probe.single_yield_args.empty?
         end
 
-        def failure_message_for_should
+        def failure_message
           "expected given block to yield with no arguments, but #{failure_reason}"
         end
 
-        def failure_message_for_should_not
+        def failure_message_when_negated
           "expected given block not to yield with no arguments, but did"
         end
 
@@ -182,6 +182,8 @@ module RSpec
       end
 
       class YieldWithArgs
+        include Composable
+
         def initialize(*args)
           @expected = args
         end
@@ -191,19 +193,18 @@ module RSpec
           @actual = @probe.single_yield_args
           @probe.yielded_once?(:yield_with_args) && args_match?
         end
-        alias == matches?
 
-        def failure_message_for_should
+        def failure_message
           "expected given block to yield with arguments, but #{positive_failure_reason}"
         end
 
-        def failure_message_for_should_not
+        def failure_message_when_negated
           "expected given block not to yield with arguments, but #{negative_failure_reason}"
         end
 
         def description
           desc = "yield with args"
-          desc << "(" + @expected.map { |e| e.inspect }.join(", ") + ")" unless @expected.empty?
+          desc << "(#{expected_arg_description})" unless @expected.empty?
           desc
         end
 
@@ -217,11 +218,15 @@ module RSpec
           end
         end
 
+        def expected_arg_description
+          @expected.map { |e| description_of e }.join(", ")
+        end
+
         def negative_failure_reason
           if all_args_match?
             "yielded with expected arguments" +
-              "\nexpected not: #{@expected.inspect}" +
-              "\n         got: #{@actual.inspect} (compared using === and ==)"
+              "\nexpected not: #{surface_descriptions_in(@expected).inspect}" +
+              "\n         got: #{@actual.inspect}"
           else
             "did"
           end
@@ -235,23 +240,21 @@ module RSpec
 
           unless match = all_args_match?
             @positive_args_failure = "yielded with unexpected arguments" +
-              "\nexpected: #{@expected.inspect}" +
-              "\n     got: #{@actual.inspect} (compared using === and ==)"
+              "\nexpected: #{surface_descriptions_in(@expected).inspect}" +
+              "\n     got: #{@actual.inspect}"
           end
 
           match
         end
 
         def all_args_match?
-          return false if @expected.size != @actual.size
-
-          @expected.zip(@actual).all? do |expected, actual|
-            expected === actual || actual == expected
-          end
+          values_match?(@expected, @actual)
         end
       end
 
       class YieldSuccessiveArgs
+        include Composable
+
         def initialize(*args)
           @expected = args
         end
@@ -261,34 +264,33 @@ module RSpec
           @actual = @probe.successive_yield_args
           args_match?
         end
-        alias == matches?
 
-        def failure_message_for_should
+        def failure_message
           "expected given block to yield successively with arguments, but yielded with unexpected arguments" +
-            "\nexpected: #{@expected.inspect}" +
-            "\n     got: #{@actual.inspect} (compared using === and ==)"
+            "\nexpected: #{surface_descriptions_in(@expected).inspect}" +
+            "\n     got: #{@actual.inspect}"
         end
 
-        def failure_message_for_should_not
+        def failure_message_when_negated
           "expected given block not to yield successively with arguments, but yielded with expected arguments" +
-              "\nexpected not: #{@expected.inspect}" +
-              "\n         got: #{@actual.inspect} (compared using === and ==)"
+              "\nexpected not: #{surface_descriptions_in(@expected).inspect}" +
+              "\n         got: #{@actual.inspect}"
         end
 
         def description
           desc = "yield successive args"
-          desc << "(" + @expected.map { |e| e.inspect }.join(", ") + ")"
+          desc << "(#{expected_arg_description})"
           desc
         end
 
       private
 
         def args_match?
-          return false if @expected.size != @actual.size
+          values_match?(@expected, @actual)
+        end
 
-          @expected.zip(@actual).all? do |expected, actual|
-            expected === actual || actual == expected
-          end
+        def expected_arg_description
+          @expected.map { |e| description_of e }.join(", ")
         end
       end
     end

data/lib/rspec/matchers/composable.rb

@@ -0,0 +1,138 @@
+require 'rspec/support/fuzzy_matcher'
+
+module RSpec
+  module Matchers
+    # Mixin designed to support the composable matcher features
+    # of RSpec 3+. Mix it into your custom matcher classes to
+    # allow them to be used in a composable fashion.
+    #
+    # @api public
+    module Composable
+      # Creates a compound `and` expectation. The matcher will
+      # only pass if both sub-matchers pass.
+      # This can be chained together to form an arbitrarily long
+      # chain of matchers.
+      #
+      # @example
+      #   expect(alphabet).to start_with("a").and end_with("z")
+      #
+      # @note The negative form (`expect(...).not_to matcher.and other`)
+      #   is not supported at this time.
+      def and(matcher)
+        BuiltIn::Compound::And.new self, matcher
+      end
+
+      # Creates a compound `or` expectation. The matcher will
+      # pass if either sub-matcher passes.
+      # This can be chained together to form an arbitrarily long
+      # chain of matchers.
+      #
+      # @example
+      #   expect(stoplight.color).to eq("red").or eq("green").or eq("yellow")
+      #
+      # @note The negative form (`expect(...).not_to matcher.or other`)
+      #   is not supported at this time.
+      def or(matcher)
+        BuiltIn::Compound::Or.new self, matcher
+      end
+
+      # Delegates to `#matches?`. Allows matchers to be used in composable
+      # fashion and also supports using matchers in case statements.
+      def ===(value)
+        matches?(value)
+      end
+
+    private unless defined?(::YARD)
+
+      # This provides a generic way to fuzzy-match an expected value against
+      # an actual value. It understands nested data structures (e.g. hashes
+      # and arrays) and is able to match against a matcher being used as
+      # the expected value or within the expected value at any level of
+      # nesting.
+      #
+      # Within a custom matcher you are encouraged to use this whenever your
+      # matcher needs to match two values, unless it needs more precise semantics.
+      # For example, the `eq` matcher _does not_ use this as it is meant to
+      # use `==` (and only `==`) for matching.
+      #
+      # @param expected [Object] what is expected
+      # @param actual [Object] the actual value
+      #
+      # @public
+      def values_match?(expected, actual)
+        Support::FuzzyMatcher.values_match?(expected, actual)
+      end
+
+      # Returns the description of the given object in a way that is
+      # aware of composed matchers. If the object is a matcher with
+      # a `description` method, returns the description; otherwise
+      # returns `object.inspect`.
+      #
+      # You are encouraged to use this in your custom matcher's
+      # `description`, `failure_message` or
+      # `failure_message_when_negated` implementation if you are
+      # supporting matcher arguments.
+      #
+      # @api public
+      def description_of(object)
+        return object.description if Matchers.is_a_describable_matcher?(object)
+        object.inspect
+      end
+
+      # Transforms the given data structue (typically a hash or array)
+      # into a new data structure that, when `#inspect` is called on it,
+      # will provide descriptions of any contained matchers rather than
+      # the normal `#inspect` output.
+      #
+      # You are encouraged to use this in your custom matcher's
+      # `description`, `failure_message` or
+      # `failure_message_when_negated` implementation if you are
+      # supporting any arguments which may be a data structure
+      # containing matchers.
+      #
+      # @api public
+      def surface_descriptions_in(item)
+        if Matchers.is_a_describable_matcher?(item)
+          DescribableItem.new(item)
+        elsif Hash === item
+          Hash[ surface_descriptions_in(item.to_a) ]
+        elsif enumerable?(item)
+          item.map { |subitem| surface_descriptions_in(subitem) }
+        else
+          item
+        end
+      end
+
+      if String.ancestors.include?(Enumerable) # 1.8.7
+        # Strings are not enumerable on 1.9, and on 1.8 they are an infinitely
+        # nested enumerable: since ruby lacks a character class, it yields
+        # 1-character strings, which are themselves enumerable, composed of a
+        # a single 1-character string, which is an enumerable, etc.
+        #
+        # @api private
+        def enumerable?(item)
+          return false if String === item
+          Enumerable === item
+        end
+      else
+        # @api private
+        def enumerable?(item)
+          Enumerable === item
+        end
+      end
+      module_function :surface_descriptions_in, :enumerable? unless defined?(::YARD)
+
+      # Wraps an item in order to surface its `description` via `inspect`.
+      # @api private
+      DescribableItem = Struct.new(:item) do
+        def inspect
+          "(#{item.description})"
+        end
+
+        def pretty_print(pp)
+          pp.text "(#{item.description})"
+        end
+      end
+    end
+  end
+end