rspec-expectations 3.0.4 → 3.12.3

data/lib/rspec/matchers/composable.rb

@@ -80,11 +80,10 @@ module RSpec
       #
       # @!visibility public
       def description_of(object)
-        return object.description if Matchers.is_a_describable_matcher?(object)
-        object.inspect
+        RSpec::Support::ObjectFormatter.format(object)
       end
 
-      # Transforms the given data structue (typically a hash or array)
+      # Transforms the given data structure (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.
@@ -101,14 +100,10 @@ module RSpec
           DescribableItem.new(item)
         elsif Hash === item
           Hash[surface_descriptions_in(item.to_a)]
-        elsif Struct === item
-          item.inspect
-        elsif enumerable?(item)
-          begin
-            item.map { |subitem| surface_descriptions_in(subitem) }
-          rescue IOError # STDOUT is enumerable but `map` raises an error
-            item.inspect
-          end
+        elsif Struct === item || unreadable_io?(item)
+          RSpec::Support::ObjectFormatter.format(item)
+        elsif should_enumerate?(item)
+          item.map { |subitem| surface_descriptions_in(subitem) }
         else
           item
         end
@@ -135,45 +130,38 @@ module RSpec
           object.clone
         elsif Hash === object
           Hash[with_matchers_cloned(object.to_a)]
-        elsif Struct === object
-          object
-        elsif enumerable?(object)
-          begin
-            object.map { |subobject| with_matchers_cloned(subobject) }
-          rescue IOError # STDOUT is enumerable but `map` raises an error
-            object
-          end
+        elsif should_enumerate?(object)
+          object.map { |subobject| with_matchers_cloned(subobject) }
         else
           object
         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
+      # @api private
+      # We should enumerate arrays as long as they are not recursive.
+      def should_enumerate?(item)
+        Array === item && item.none? { |subitem| subitem.equal?(item) }
+      end
+
+      # @api private
+      def unreadable_io?(object)
+        return false unless IO === object
+        object.each {} # STDOUT is enumerable but raises an error
+        false
+      rescue IOError
+        true
       end
-      module_function :surface_descriptions_in, :enumerable?
+      module_function :surface_descriptions_in, :should_enumerate?, :unreadable_io?
 
       # Wraps an item in order to surface its `description` via `inspect`.
       # @api private
       DescribableItem = Struct.new(:item) do
+        # Inspectable version of the item description
         def inspect
           "(#{item.description})"
         end
 
+        # A pretty printed version of the item description.
         def pretty_print(pp)
           pp.text "(#{item.description})"
         end

data/lib/rspec/matchers/dsl.rb

@@ -1,16 +1,102 @@
+RSpec::Support.require_rspec_support "with_keywords_when_needed"
+
 module RSpec
   module Matchers
     # Defines the custom matcher DSL.
     module DSL
+      # Defines a matcher alias. The returned matcher's `description` will be overridden
+      # to reflect the phrasing of the new name, which will be used in failure messages
+      # when passed as an argument to another matcher in a composed matcher expression.
+      #
+      # @example
+      #   RSpec::Matchers.alias_matcher :a_list_that_sums_to, :sum_to
+      #   sum_to(3).description # => "sum to 3"
+      #   a_list_that_sums_to(3).description # => "a list that sums to 3"
+      #
+      # @example
+      #   RSpec::Matchers.alias_matcher :a_list_sorted_by, :be_sorted_by do |description|
+      #     description.sub("be sorted by", "a list sorted by")
+      #   end
+      #
+      #   be_sorted_by(:age).description # => "be sorted by age"
+      #   a_list_sorted_by(:age).description # => "a list sorted by age"
+      #
+      # @param new_name [Symbol] the new name for the matcher
+      # @param old_name [Symbol] the original name for the matcher
+      # @param options  [Hash] options for the aliased matcher
+      # @option options [Class] :klass the ruby class to use as the decorator. (Not normally used).
+      # @yield [String] optional block that, when given, is used to define the overridden
+      #   logic. The yielded arg is the original description or failure message. If no
+      #   block is provided, a default override is used based on the old and new names.
+      # @see RSpec::Matchers
+      def alias_matcher(new_name, old_name, options={}, &description_override)
+        description_override ||= lambda do |old_desc|
+          old_desc.gsub(EnglishPhrasing.split_words(old_name), EnglishPhrasing.split_words(new_name))
+        end
+        klass = options.fetch(:klass) { AliasedMatcher }
+
+        define_method(new_name) do |*args, &block|
+          matcher = __send__(old_name, *args, &block)
+          matcher.matcher_name = new_name if matcher.respond_to?(:matcher_name=)
+          klass.new(matcher, description_override)
+        end
+        ruby2_keywords new_name if respond_to?(:ruby2_keywords, true)
+      end
+
+      # Defines a negated matcher. The returned matcher's `description` and `failure_message`
+      # will be overridden to reflect the phrasing of the new name, and the match logic will
+      # be based on the original matcher but negated.
+      #
+      # @example
+      #   RSpec::Matchers.define_negated_matcher :exclude, :include
+      #   include(1, 2).description # => "include 1 and 2"
+      #   exclude(1, 2).description # => "exclude 1 and 2"
+      #
+      # @param negated_name [Symbol] the name for the negated matcher
+      # @param base_name [Symbol] the name of the original matcher that will be negated
+      # @yield [String] optional block that, when given, is used to define the overridden
+      #   logic. The yielded arg is the original description or failure message. If no
+      #   block is provided, a default override is used based on the old and new names.
+      # @see RSpec::Matchers
+      def define_negated_matcher(negated_name, base_name, &description_override)
+        alias_matcher(negated_name, base_name, :klass => AliasedNegatedMatcher, &description_override)
+      end
+
       # Defines a custom matcher.
+      #
+      # @param name [Symbol] the name for the matcher
+      # @yield [Object] block that is used to define the matcher.
+      #   The block is evaluated in the context of your custom matcher class.
+      #   When args are passed to your matcher, they will be yielded here,
+      #   usually representing the expected value(s).
       # @see RSpec::Matchers
       def define(name, &declarations)
-        define_method name do |*expected|
-          RSpec::Matchers::DSL::Matcher.new(name, declarations, self, *expected)
+        warn_about_block_args(name, declarations)
+        define_method name do |*expected, &block_arg|
+          RSpec::Matchers::DSL::Matcher.new(name, declarations, self, *expected, &block_arg)
         end
       end
       alias_method :matcher, :define
 
+    private
+
+      if Proc.method_defined?(:parameters)
+        def warn_about_block_args(name, declarations)
+          declarations.parameters.each do |type, arg_name|
+            next unless type == :block
+            RSpec.warning("Your `#{name}` custom matcher receives a block argument (`#{arg_name}`), " \
+                          "but due to limitations in ruby, RSpec cannot provide the block. Instead, " \
+                          "use the `block_arg` method to access the block")
+          end
+        end
+      else
+        # :nocov:
+        def warn_about_block_args(*)
+          # There's no way to detect block params on 1.8 since the method reflection APIs don't expose it
+        end
+        # :nocov:
+      end
+
       RSpec.configure { |c| c.extend self } if RSpec.respond_to?(:configure)
 
       # Contains the methods that are available from within the
@@ -35,28 +121,53 @@ module RSpec
         #     expect(3).to be_even     # fails
         #     expect(4).not_to be_even # fails
         #
+        # By default the match block will swallow expectation errors (e.g.
+        # caused by using an expectation such as `expect(1).to eq 2`), if you
+        # wish to allow these to bubble up, pass in the option
+        # `:notify_expectation_failures => true`.
+        #
+        # @param [Hash] options for defining the behavior of the match block.
         # @yield [Object] actual the actual value (i.e. the value wrapped by `expect`)
-        def match(&match_block)
+        def match(options={}, &match_block)
           define_user_override(:matches?, match_block) do |actual|
-            begin
-              @actual = actual
-              super(*actual_arg_for(match_block))
-            rescue RSpec::Expectations::ExpectationNotMetError
-              false
+            @actual = actual
+            RSpec::Support.with_failure_notifier(RAISE_NOTIFIER) do
+              begin
+                super(*actual_arg_for(match_block))
+              rescue RSpec::Expectations::ExpectationNotMetError
+                raise if options[:notify_expectation_failures]
+                false
+              end
             end
           end
         end
 
+        # @private
+        RAISE_NOTIFIER = Proc.new { |err, _opts| raise err }
+
         # Use this to define the block for a negative expectation (`expect(...).not_to`)
         # when the positive and negative forms require different handling. This
         # is rarely necessary, but can be helpful, for example, when specifying
         # asynchronous processes that require different timeouts.
         #
+        # By default the match block will swallow expectation errors (e.g.
+        # caused by using an expectation such as `expect(1).to eq 2`), if you
+        # wish to allow these to bubble up, pass in the option
+        # `:notify_expectation_failures => true`.
+        #
+        # @param [Hash] options for defining the behavior of the match block.
         # @yield [Object] actual the actual value (i.e. the value wrapped by `expect`)
-        def match_when_negated(&match_block)
+        def match_when_negated(options={}, &match_block)
           define_user_override(:does_not_match?, match_block) do |actual|
-            @actual = actual
-            super(*actual_arg_for(match_block))
+            begin
+              @actual = actual
+              RSpec::Support.with_failure_notifier(RAISE_NOTIFIER) do
+                super(*actual_arg_for(match_block))
+              end
+            rescue RSpec::Expectations::ExpectationNotMetError
+              raise if options[:notify_expectation_failures]
+              false
+            end
           end
         end
 
@@ -87,7 +198,7 @@ module RSpec
           end
         end
 
-        # Customizes the failure messsage to use when this matcher is
+        # Customizes the failure message to use when this matcher is
         # asked to positively match. Only use this when the message
         # generated by default doesn't suit your needs.
         #
@@ -106,7 +217,7 @@ module RSpec
           define_user_override(__method__, definition)
         end
 
-        # Customize the failure messsage to use when this matcher is asked
+        # Customize the failure message to use when this matcher is asked
         # to negatively match. Only use this when the message generated by
         # default doesn't suit your needs.
         #
@@ -160,7 +271,16 @@ module RSpec
         # Convenience for defining methods on this matcher to create a fluent
         # interface. The trick about fluent interfaces is that each method must
         # return self in order to chain methods together. `chain` handles that
-        # for you.
+        # for you. If the method is invoked and the
+        # `include_chain_clauses_in_custom_matcher_descriptions` config option
+        # hash been enabled, the chained method name and args will be added to the
+        # default description and failure message.
+        #
+        # In the common case where you just want the chained method to store some
+        # value(s) for later use (e.g. in `match`), you can provide one or more
+        # attribute names instead of a block; the chained method will store its
+        # arguments in instance variables with those names, and the values will
+        # be exposed via getters.
         #
         # @example
         #
@@ -175,21 +295,43 @@ module RSpec
         #     end
         #
         #     expect(minor).to have_errors_on(:age).with("Not old enough to participate")
-        def chain(name, &definition)
-          define_user_override(name, definition) do |*args, &block|
+        def chain(method_name, *attr_names, &definition)
+          unless block_given? ^ attr_names.any?
+            raise ArgumentError, "You must pass either a block or some attribute names (but not both) to `chain`."
+          end
+
+          definition = assign_attributes(attr_names) if attr_names.any?
+
+          define_user_override(method_name, definition) do |*args, &block|
             super(*args, &block)
+            @chained_method_clauses.push([method_name, args])
             self
           end
         end
 
+        def assign_attributes(attr_names)
+          attr_reader(*attr_names)
+          private(*attr_names)
+
+          lambda do |*attr_values|
+            attr_names.zip(attr_values) do |attr_name, attr_value|
+              instance_variable_set(:"@#{attr_name}", attr_value)
+            end
+          end
+        end
+
+        # assign_attributes isn't defined in the private section below because
+        # that makes MRI 1.9.2 emit a warning about private attributes.
+        private :assign_attributes
+
       private
 
         # Does the following:
         #
-        # - Defines the named method usign a user-provided block
+        # - Defines the named method using a user-provided block
         #   in @user_method_defs, which is included as an ancestor
         #   in the singleton class in which we eval the `define` block.
-        # - Defines an overriden definition for the same method
+        # - Defines an overridden definition for the same method
         #   usign the provided `our_def` block.
         # - Provides a default `our_def` block for the common case
         #   of needing to call the user's definition with `@actual`
@@ -197,7 +339,7 @@ module RSpec
         #
         # This compiles the user block into an actual method, allowing
         # them to use normal method constructs like `return`
-        # (e.g. for a early guard statement), while allowing us to define
+        # (e.g. for an early guard statement), while allowing us to define
         # an override that can provide the wrapped handling
         # (e.g. assigning `@actual`, rescueing errors, etc) and
         # can `super` to the user's definition.
@@ -241,6 +383,8 @@ module RSpec
       # override any of these using the {RSpec::Matchers::DSL::Macros Macros} methods
       # from within an `RSpec::Matchers.define` block.
       module DefaultImplementations
+        include BuiltIn::BaseMatcher::DefaultFailureMessages
+
         # @api private
         # Used internally by objects returns by `should` and `should_not`.
         def diffable?
@@ -249,24 +393,37 @@ module RSpec
 
         # The default description.
         def description
-          "#{name_to_sentence}#{to_sentence expected}"
+          english_name = EnglishPhrasing.split_words(name)
+          expected_list = EnglishPhrasing.list(expected)
+          "#{english_name}#{expected_list}#{chained_method_clause_sentences}"
         end
 
-        # The default failure message for positive expectations.
-        def failure_message
-          "expected #{actual.inspect} to #{name_to_sentence}#{to_sentence expected}"
+        # Matchers do not support block expectations by default. You
+        # must opt-in.
+        def supports_block_expectations?
+          false
         end
 
-        # The default failure message for negative expectations.
-        def failure_message_when_negated
-          "expected #{actual.inspect} not to #{name_to_sentence}#{to_sentence expected}"
+        def supports_value_expectations?
+          true
         end
 
-        # Matchers do not support block expectations by default. You
-        # must opt-in.
-        def supports_block_expectations?
+        # Most matchers do not expect call stack jumps.
+        def expects_call_stack_jump?
           false
         end
+
+      private
+
+        def chained_method_clause_sentences
+          return '' unless Expectations.configuration.include_chain_clauses_in_custom_matcher_descriptions?
+
+          @chained_method_clauses.map do |(method_name, method_args)|
+            english_name = EnglishPhrasing.split_words(method_name)
+            arg_list = EnglishPhrasing.list(method_args)
+            " #{english_name}#{arg_list}"
+          end.join
+        end
       end
 
       # The class used for custom matchers. The block passed to
@@ -280,9 +437,6 @@ module RSpec
         # Allows expectation expressions to be used in the match block.
         include RSpec::Matchers
 
-        # Converts matcher name and expected args to an English expresion.
-        include RSpec::Matchers::Pretty
-
         # Supports the matcher composability features of RSpec 3+.
         include Composable
 
@@ -298,18 +452,27 @@ module RSpec
         # Could be useful to extract details for a failure message.
         attr_reader :rescued_exception
 
+        # The block parameter used in the expectation
+        attr_reader :block_arg
+
+        # The name of the matcher.
+        attr_reader :name
+
         # @api private
-        def initialize(name, declarations, matcher_execution_context, *expected)
+        def initialize(name, declarations, matcher_execution_context, *expected, &block_arg)
           @name     = name
           @actual   = nil
           @expected_as_array = expected
           @matcher_execution_context = matcher_execution_context
+          @chained_method_clauses = []
+          @block_arg = block_arg
 
-          class << self
+          klass = class << self
             # See `Macros#define_user_override` above, for an explanation.
             include(@user_method_defs = Module.new)
             self
-          end.class_exec(*expected, &declarations)
+          end
+          RSpec::Support::WithKeywordsWhenNeeded.class_exec(klass, *expected, &declarations)
         end
 
         # Provides the expected value. This will return an array if
@@ -345,11 +508,13 @@ module RSpec
             super || @matcher_execution_context.respond_to?(method, include_private)
           end
         else # for 1.8.7
+          # :nocov:
           # Indicates that this matcher responds to messages
           # from the `@matcher_execution_context` as well.
           def respond_to?(method, include_private=false)
             super || @matcher_execution_context.respond_to?(method, include_private)
           end
+          # :nocov:
         end
 
       private
@@ -371,9 +536,10 @@ module RSpec
             super(method, *args, &block)
           end
         end
+        # The method_missing method should be refactored to pass kw args in RSpec 4
+        # then this can be removed
+        ruby2_keywords :method_missing if respond_to?(:ruby2_keywords, true)
       end
     end
   end
 end
-
-RSpec::Matchers.extend RSpec::Matchers::DSL

data/lib/rspec/matchers/english_phrasing.rb

@@ -0,0 +1,58 @@
+module RSpec
+  module Matchers
+    # Facilitates converting ruby objects to English phrases.
+    module EnglishPhrasing
+      # Converts a symbol into an English expression.
+      #
+      #     split_words(:banana_creme_pie) #=> "banana creme pie"
+      #
+      def self.split_words(sym)
+        sym.to_s.tr('_', ' ')
+      end
+
+      # @note The returned string has a leading space except
+      # when given an empty list.
+      #
+      # Converts an object (often a collection of objects)
+      # into an English list.
+      #
+      #     list(['banana', 'kiwi', 'mango'])
+      #     #=> " \"banana\", \"kiwi\", and \"mango\""
+      #
+      # Given an empty collection, returns the empty string.
+      #
+      #     list([]) #=> ""
+      #
+      def self.list(obj)
+        return " #{RSpec::Support::ObjectFormatter.format(obj)}" if !obj || Struct === obj || Hash === obj
+        items = Array(obj).map { |w| RSpec::Support::ObjectFormatter.format(w) }
+        case items.length
+        when 0
+          ""
+        when 1
+          " #{items[0]}"
+        when 2
+          " #{items[0]} and #{items[1]}"
+        else
+          " #{items[0...-1].join(', ')}, and #{items[-1]}"
+        end
+      end
+
+      if RUBY_VERSION == '1.8.7'
+        # Not sure why, but on travis on 1.8.7 we have gotten these warnings:
+        # lib/rspec/matchers/english_phrasing.rb:28: warning: default `to_a' will be obsolete
+        # So it appears that `Array` can trigger that (e.g. by calling `to_a` on the passed object?)
+        # So here we replace `Kernel#Array` with our own warning-free implementation for 1.8.7.
+        # @private
+        # rubocop:disable Naming/MethodName
+        def self.Array(obj)
+          case obj
+          when Array then obj
+          else [obj]
+          end
+        end
+        # rubocop:enable Naming/MethodName
+      end
+    end
+  end
+end

data/lib/rspec/matchers/expecteds_for_multiple_diffs.rb

@@ -0,0 +1,82 @@
+module RSpec
+  module Matchers
+    # @api private
+    # Handles list of expected values when there is a need to render
+    # multiple diffs. Also can handle one value.
+    class ExpectedsForMultipleDiffs
+      # @private
+      # Default diff label when there is only one matcher in diff
+      # output
+      DEFAULT_DIFF_LABEL = "Diff:".freeze
+
+      # @private
+      # Maximum readable matcher description length
+      DESCRIPTION_MAX_LENGTH = 65
+
+      def initialize(expected_list)
+        @expected_list = expected_list
+      end
+
+      # @api private
+      # Wraps provided expected value in instance of
+      # ExpectedForMultipleDiffs. If provided value is already an
+      # ExpectedForMultipleDiffs then it just returns it.
+      # @param [Any] expected value to be wrapped
+      # @return [RSpec::Matchers::ExpectedsForMultipleDiffs]
+      def self.from(expected)
+        return expected if self === expected
+        new([[expected, DEFAULT_DIFF_LABEL]])
+      end
+
+      # @api private
+      # Wraps provided matcher list in instance of
+      # ExpectedForMultipleDiffs.
+      # @param [Array<Any>] matchers list of matchers to wrap
+      # @return [RSpec::Matchers::ExpectedsForMultipleDiffs]
+      def self.for_many_matchers(matchers)
+        new(matchers.map { |m| [m.expected, diff_label_for(m)] })
+      end
+
+      # @api private
+      # Returns message with diff(s) appended for provided differ
+      # factory and actual value if there are any
+      # @param [String] message original failure message
+      # @param [Proc] differ
+      # @param [Any] actual value
+      # @return [String]
+      def message_with_diff(message, differ, actual)
+        diff = diffs(differ, actual)
+        message = "#{message}\n#{diff}" unless diff.empty?
+        message
+      end
+
+    private
+
+      class << self
+        private
+
+        def diff_label_for(matcher)
+          "Diff for (#{truncated(RSpec::Support::ObjectFormatter.format(matcher))}):"
+        end
+
+        def truncated(description)
+          return description if description.length <= DESCRIPTION_MAX_LENGTH
+          description[0...DESCRIPTION_MAX_LENGTH - 3] << "..."
+        end
+      end
+
+      def diffs(differ, actual)
+        @expected_list.map do |(expected, diff_label)|
+          diff = differ.diff(actual, expected)
+          next if diff.strip.empty?
+          if diff == "\e[0m\n\e[0m"
+            "#{diff_label}\n" \
+              "  <The diff is empty, are your objects producing identical `#inspect` output?>"
+          else
+            "#{diff_label}#{diff}"
+          end
+        end.compact.join("\n")
+      end
+    end
+  end
+end

data/lib/rspec/matchers/fail_matchers.rb

@@ -0,0 +1,42 @@
+require 'rspec/expectations'
+
+module RSpec
+  module Matchers
+    # Matchers for testing RSpec matchers. Include them with:
+    #
+    #     require 'rspec/matchers/fail_matchers'
+    #     RSpec.configure do |config|
+    #       config.include RSpec::Matchers::FailMatchers
+    #     end
+    #
+    module FailMatchers
+      # Matches if an expectation fails
+      #
+      # @example
+      #   expect { some_expectation }.to fail
+      def fail(&block)
+        raise_error(RSpec::Expectations::ExpectationNotMetError, &block)
+      end
+
+      # Matches if an expectation fails with the provided message
+      #
+      # @example
+      #   expect { some_expectation }.to fail_with("some failure message")
+      #   expect { some_expectation }.to fail_with(/some failure message/)
+      def fail_with(message)
+        raise_error(RSpec::Expectations::ExpectationNotMetError, message)
+      end
+
+      # Matches if an expectation fails including the provided message
+      #
+      # @example
+      #   expect { some_expectation }.to fail_including("portion of some failure message")
+      def fail_including(*snippets)
+        raise_error(
+          RSpec::Expectations::ExpectationNotMetError,
+          a_string_including(*snippets)
+        )
+      end
+    end
+  end
+end

data/lib/rspec/matchers/generated_descriptions.rb

@@ -21,8 +21,7 @@ module RSpec
       "#{last_expectation_handler.verb} #{last_description}"
     end
 
-  private
-
+    # @private
     def self.last_description
       last_matcher.respond_to?(:description) ? last_matcher.description : <<-MESSAGE
 When you call a matcher in an example without a String, like this: