rspec-expectations 3.0.4 → 3.12.3

data/lib/rspec/expectations/expectation_target.rb

@@ -21,6 +21,12 @@ module RSpec
       # `nil` is a valid value to pass.
       UndefinedValue = Module.new
 
+      # @note this name aligns with `Minitest::Expectation` so that our
+      #   {InstanceMethods} module can be included in that class when
+      #   used in a Minitest context.
+      # @return [Object] the target of the expectation
+      attr_reader :target
+
       # @api private
       def initialize(value)
         @target = value
@@ -36,43 +42,89 @@ module RSpec
         elsif block
           raise ArgumentError, "You cannot pass both an argument and a block to `expect`."
         else
-          new(value)
+          ValueExpectationTarget.new(value)
+        end
+      end
+
+      # Defines instance {ExpectationTarget} instance methods. These are defined
+      # in a module so we can include it in `Minitest::Expectation` when
+      # `rspec/expectations/minitest_integration` is loaded in order to
+      # support usage with Minitest.
+      module InstanceMethods
+        # Runs the given expectation, passing if `matcher` returns true.
+        # @example
+        #   expect(value).to eq(5)
+        #   expect { perform }.to raise_error
+        # @param [Matcher]
+        #   matcher
+        # @param [String, Proc] message optional message to display when the expectation fails
+        # @return [Boolean] true if the expectation succeeds (else raises)
+        # @see RSpec::Matchers
+        def to(matcher=nil, message=nil, &block)
+          prevent_operator_matchers(:to) unless matcher
+          RSpec::Expectations::PositiveExpectationHandler.handle_matcher(target, matcher, message, &block)
+        end
+
+        # Runs the given expectation, passing if `matcher` returns false.
+        # @example
+        #   expect(value).not_to eq(5)
+        # @param [Matcher]
+        #   matcher
+        # @param [String, Proc] message optional message to display when the expectation fails
+        # @return [Boolean] false if the negative expectation succeeds (else raises)
+        # @see RSpec::Matchers
+        def not_to(matcher=nil, message=nil, &block)
+          prevent_operator_matchers(:not_to) unless matcher
+          RSpec::Expectations::NegativeExpectationHandler.handle_matcher(target, matcher, message, &block)
+        end
+        alias to_not not_to
+
+      private
+
+        def prevent_operator_matchers(verb)
+          raise ArgumentError, "The expect syntax does not support operator matchers, " \
+                               "so you must pass a matcher to `##{verb}`."
         end
       end
 
-      # Runs the given expectation, passing if `matcher` returns true.
-      # @example
-      #   expect(value).to eq(5)
-      #   expect { perform }.to raise_error
-      # @param [Matcher]
-      #   matcher
-      # @param [String or Proc] message optional message to display when the expectation fails
-      # @return [Boolean] true if the expectation succeeds (else raises)
-      # @see RSpec::Matchers
+      include InstanceMethods
+    end
+
+    # @private
+    # Validates the provided matcher to ensure it supports block
+    # expectations, in order to avoid user confusion when they
+    # use a block thinking the expectation will be on the return
+    # value of the block rather than the block itself.
+    class ValueExpectationTarget < ExpectationTarget
       def to(matcher=nil, message=nil, &block)
-        prevent_operator_matchers(:to) unless matcher
-        RSpec::Expectations::PositiveExpectationHandler.handle_matcher(@target, matcher, message, &block)
+        enforce_value_expectation(matcher)
+        super
       end
 
-      # Runs the given expectation, passing if `matcher` returns false.
-      # @example
-      #   expect(value).not_to eq(5)
-      # @param [Matcher]
-      #   matcher
-      # @param [String or Proc] message optional message to display when the expectation fails
-      # @return [Boolean] false if the negative expectation succeeds (else raises)
-      # @see RSpec::Matchers
       def not_to(matcher=nil, message=nil, &block)
-        prevent_operator_matchers(:not_to) unless matcher
-        RSpec::Expectations::NegativeExpectationHandler.handle_matcher(@target, matcher, message, &block)
+        enforce_value_expectation(matcher)
+        super
       end
-      alias to_not not_to
 
     private
 
-      def prevent_operator_matchers(verb)
-        raise ArgumentError, "The expect syntax does not support operator matchers, " \
-                             "so you must pass a matcher to `##{verb}`."
+      def enforce_value_expectation(matcher)
+        return if supports_value_expectations?(matcher)
+
+        RSpec.deprecate(
+          "expect(value).to #{RSpec::Support::ObjectFormatter.format(matcher)}",
+          :message =>
+            "The implicit block expectation syntax is deprecated, you should pass " \
+            "a block rather than an argument to `expect` to use the provided " \
+            "block expectation matcher or the matcher must implement " \
+            "`supports_value_expectations?`. e.g  `expect { value }.to " \
+            "#{RSpec::Support::ObjectFormatter.format(matcher)}` not " \
+            "`expect(value).to #{RSpec::Support::ObjectFormatter.format(matcher)}`"
+        )
+      end
+
+      def supports_value_expectations?(matcher)
+        !matcher.respond_to?(:supports_value_expectations?) || matcher.supports_value_expectations?
       end
     end
 
@@ -98,21 +150,13 @@ module RSpec
       def enforce_block_expectation(matcher)
         return if supports_block_expectations?(matcher)
 
-        raise ExpectationNotMetError, "You must pass an argument rather than " \
-          "a block to use the provided matcher (#{description_of matcher}), or " \
-          "the matcher must implement `supports_block_expectations?`."
+        raise ExpectationNotMetError, "You must pass an argument rather than a block to `expect` to use the provided " \
+          "matcher (#{RSpec::Support::ObjectFormatter.format(matcher)}), or the matcher must implement " \
+          "`supports_block_expectations?`."
       end
 
       def supports_block_expectations?(matcher)
-        matcher.supports_block_expectations?
-      rescue NoMethodError
-        false
-      end
-
-      def description_of(matcher)
-        matcher.description
-      rescue NoMethodError
-        matcher.inspect
+        matcher.respond_to?(:supports_block_expectations?) && matcher.supports_block_expectations?
       end
     end
   end

data/lib/rspec/expectations/fail_with.rb

@@ -1,12 +1,18 @@
-RSpec::Support.require_rspec_support 'differ'
-
 module RSpec
   module Expectations
     class << self
+      # @private
+      class Differ
+        # @private
+        OBJECT_PREPARER = lambda do |object|
+          RSpec::Matchers::Composable.surface_descriptions_in(object)
+        end
+      end
+
       # @private
       def differ
         RSpec::Support::Differ.new(
-          :object_preparer => lambda { |object| RSpec::Matchers::Composable.surface_descriptions_in(object) },
+          :object_preparer => Differ::OBJECT_PREPARER,
           :color => RSpec::Matchers.configuration.color?
         )
       end
@@ -24,10 +30,9 @@ module RSpec
                                "appropriate failure_message[_when_negated] method to return a string?"
         end
 
-        diff = differ.diff(actual, expected)
-        message = "#{message}\nDiff:#{diff}" unless diff.empty?
+        message = ::RSpec::Matchers::ExpectedsForMultipleDiffs.from(expected).message_with_diff(message, differ, actual)
 
-        raise RSpec::Expectations::ExpectationNotMetError, message
+        RSpec::Support.notify_failure(RSpec::Expectations::ExpectationNotMetError.new message)
       end
     end
   end

data/lib/rspec/expectations/failure_aggregator.rb

@@ -0,0 +1,229 @@
+module RSpec
+  module Expectations
+    # @private
+    class FailureAggregator
+      attr_reader :block_label, :metadata
+
+      # @private
+      class AggregatedFailure
+        # @private
+        MESSAGE =
+          'AggregatedFailure: This method caused a failure which has been ' \
+          'suppressed to be aggregated into our failure report by returning ' \
+          'this value, further errors can be ignored.'
+
+        def inspect
+          MESSAGE
+        end
+      end
+
+      AGGREGATED_FAILURE = AggregatedFailure.new
+
+      def aggregate
+        RSpec::Support.with_failure_notifier(self) do
+          begin
+            yield
+          rescue ExpectationNotMetError => e
+            # Normally, expectation failures will be notified via the `call` method, below,
+            # but since the failure notifier uses a thread local variable, failing expectations
+            # in another thread will still raise. We handle that here and categorize it as part
+            # of `failures` rather than letting it fall through and be categorized as part of
+            # `other_errors`.
+            failures << e
+          rescue Support::AllExceptionsExceptOnesWeMustNotRescue => e
+            # While it is normally a bad practice to rescue `Exception`, it's important we do
+            # so here. It's low risk (`notify_aggregated_failures` below will re-raise the exception,
+            # or raise a `MultipleExpectationsNotMetError` that includes the exception), and it's
+            # essential that the user is notified of expectation failures that may have already
+            # occurred in the `aggregate_failures` block. Those expectation failures may provide
+            # important diagnostics for understanding why this exception occurred, and if we simply
+            # allowed this exception to be raised as-is, it would (wrongly) suggest to the user
+            # that the expectation passed when it did not, which would be quite confusing.
+            other_errors << e
+          end
+        end
+
+        notify_aggregated_failures
+      end
+
+      def failures
+        @failures ||= []
+      end
+
+      def other_errors
+        @other_errors ||= []
+      end
+
+      # This method is defined to satisfy the callable interface
+      # expected by `RSpec::Support.with_failure_notifier`.
+      def call(failure, options)
+        source_id = options[:source_id]
+        return if source_id && @seen_source_ids.key?(source_id)
+
+        @seen_source_ids[source_id] = true
+        assign_backtrace(failure) unless failure.backtrace
+        failures << failure
+
+        AGGREGATED_FAILURE
+      end
+
+    private
+
+      if RSpec::Support::Ruby.jruby? && RSpec::Support::Ruby.jruby_version < '9.2.0.0'
+        # On JRuby 9.1.x.x and before, `caller` and `raise` produce different backtraces with
+        # regards to `.java` stack frames. It's important that we use `raise` for JRuby to produce
+        # a backtrace that has a continuous common section with the raised `MultipleExpectationsNotMetError`,
+        # so that rspec-core's truncation logic can work properly on it to list the backtrace
+        # relative to the `aggregate_failures` block.
+        def assign_backtrace(failure)
+          raise failure
+        rescue failure.class => e
+          failure.set_backtrace(e.backtrace)
+        end
+      else
+        # Using `caller` performs better (and is simpler) than `raise` on most Rubies.
+        def assign_backtrace(failure)
+          failure.set_backtrace(caller)
+        end
+      end
+
+      def initialize(block_label, metadata)
+        @block_label     = block_label
+        @metadata        = metadata
+        @seen_source_ids = {} # don't want to load stdlib set
+      end
+
+      def notify_aggregated_failures
+        all_errors = failures + other_errors
+
+        case all_errors.size
+        when 0 then return true
+        when 1 then RSpec::Support.notify_failure all_errors.first
+        else RSpec::Support.notify_failure MultipleExpectationsNotMetError.new(self)
+        end
+      end
+    end
+
+    # Exception raised from `aggregate_failures` when multiple expectations fail.
+    class MultipleExpectationsNotMetError
+      # @return [String] The fully formatted exception message.
+      def message
+        @message ||= (["#{summary}:"] + enumerated_failures + enumerated_errors).join("\n\n")
+      end
+
+      # @return [Array<RSpec::Expectations::ExpectationNotMetError>] The list of expectation failures.
+      def failures
+        @failure_aggregator.failures
+      end
+
+      # @return [Array<Exception>] The list of other exceptions.
+      def other_errors
+        @failure_aggregator.other_errors
+      end
+
+      # @return [Array<Exception>] The list of expectation failures and other exceptions, combined.
+      attr_reader :all_exceptions
+
+      # @return [String] The user-assigned label for the aggregation block.
+      def aggregation_block_label
+        @failure_aggregator.block_label
+      end
+
+      # @return [Hash] The metadata hash passed to `aggregate_failures`.
+      def aggregation_metadata
+        @failure_aggregator.metadata
+      end
+
+      # @return [String] A summary of the failure, including the block label and a count of failures.
+      def summary
+        "Got #{exception_count_description} from failure aggregation " \
+        "block#{block_description}"
+      end
+
+      # return [String] A description of the failure/error counts.
+      def exception_count_description
+        failure_count = pluralize("failure", failures.size)
+        return failure_count if other_errors.empty?
+        error_count = pluralize("other error", other_errors.size)
+        "#{failure_count} and #{error_count}"
+      end
+
+    private
+
+      def initialize(failure_aggregator)
+        @failure_aggregator = failure_aggregator
+        @all_exceptions = failures + other_errors
+      end
+
+      def block_description
+        return "" unless aggregation_block_label
+        " #{aggregation_block_label.inspect}"
+      end
+
+      def pluralize(noun, count)
+        "#{count} #{noun}#{'s' unless count == 1}"
+      end
+
+      def enumerated(exceptions, index_offset)
+        exceptions.each_with_index.map do |exception, index|
+          index += index_offset
+          formatted_message = "#{yield exception}\n#{format_backtrace(exception.backtrace).first}"
+          "#{index_label index}#{indented formatted_message, index}"
+        end
+      end
+
+      def exclusion_patterns
+        patterns = %w[/lib\d*/ruby/ bin/ exe/rspec /lib/bundler/ /exe/bundle:]
+        patterns << "org/jruby/" if RSpec::Support::Ruby.jruby?
+        patterns.map! { |s| Regexp.new(s.gsub('/', File::SEPARATOR)) }
+      end
+
+      def format_backtrace(backtrace)
+        backtrace.map { |l| backtrace_line(l) }.compact.tap { |filtered| filtered.concat backtrace if filtered.empty? }
+      end
+
+      def backtrace_line(line)
+        return if [Regexp.union(RSpec::CallerFilter::IGNORE_REGEX, *exclusion_patterns)].any? { |p| line =~ p }
+
+        # It changes the current path that is relative to
+        # system root to be relative to the project root.
+        line.sub(/(\A|\s)#{File.expand_path('.')}(#{File::SEPARATOR}|\s|\Z)/, '\\1.\\2'.freeze).sub(/\A([^:]+:\d+)$/, '\\1'.freeze)
+      end
+
+      def enumerated_failures
+        enumerated(failures, 0, &:message)
+      end
+
+      def enumerated_errors
+        enumerated(other_errors, failures.size) do |error|
+          "#{error.class}: #{error.message}"
+        end
+      end
+
+      def indented(failure_message, index)
+        line_1, *rest = failure_message.strip.lines.to_a
+        first_line_indentation = ' ' * (longest_index_label_width - width_of_label(index))
+
+        first_line_indentation + line_1 + rest.map do |line|
+          line =~ /\S/ ? indentation + line : line
+        end.join
+      end
+
+      def indentation
+        @indentation ||= ' ' * longest_index_label_width
+      end
+
+      def longest_index_label_width
+        @longest_index_label_width ||= width_of_label(failures.size)
+      end
+
+      def width_of_label(index)
+        index_label(index).chars.count
+      end
+
+      def index_label(index)
+        "  #{index + 1}) "
+      end
+    end
+  end
+end

data/lib/rspec/expectations/handler.rb

@@ -17,14 +17,17 @@ module RSpec
       #
       # @private
       def self.modern_matcher_from(matcher)
-        LegacyMacherAdapter::RSpec2.wrap(matcher) ||
-        LegacyMacherAdapter::RSpec1.wrap(matcher) || matcher
+        LegacyMatcherAdapter::RSpec2.wrap(matcher) ||
+        LegacyMatcherAdapter::RSpec1.wrap(matcher) || matcher
       end
 
-      def self.setup(handler, matcher, message)
+      def self.with_matcher(handler, matcher, message)
         check_message(message)
+        matcher = modern_matcher_from(matcher)
+        yield matcher
+      ensure
         ::RSpec::Matchers.last_expectation_handler = handler
-        ::RSpec::Matchers.last_matcher = modern_matcher_from(matcher)
+        ::RSpec::Matchers.last_matcher = matcher
       end
 
       def self.handle_failure(matcher, message, failure_message_method)
@@ -41,15 +44,21 @@ module RSpec
 
     # @private
     class PositiveExpectationHandler
-      def self.handle_matcher(actual, initial_matcher, message=nil, &block)
-        matcher = ExpectationHelper.setup(self, initial_matcher, message)
+      def self.handle_matcher(actual, initial_matcher, custom_message=nil, &block)
+        ExpectationHelper.with_matcher(self, initial_matcher, custom_message) do |matcher|
+          return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) unless initial_matcher
 
-        return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) unless initial_matcher
-        matcher.matches?(actual, &block) || ExpectationHelper.handle_failure(matcher, message, :failure_message)
+          match_result = matcher.matches?(actual, &block)
+          if custom_message && match_result.respond_to?(:error_generator)
+            match_result.error_generator.opts[:message] = custom_message
+          end
+
+          match_result || ExpectationHelper.handle_failure(matcher, custom_message, :failure_message)
+        end
       end
 
       def self.verb
-        "should"
+        'is expected to'
       end
 
       def self.should_method
@@ -63,11 +72,17 @@ module RSpec
 
     # @private
     class NegativeExpectationHandler
-      def self.handle_matcher(actual, initial_matcher, message=nil, &block)
-        matcher = ExpectationHelper.setup(self, initial_matcher, message)
+      def self.handle_matcher(actual, initial_matcher, custom_message=nil, &block)
+        ExpectationHelper.with_matcher(self, initial_matcher, custom_message) do |matcher|
+          return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) unless initial_matcher
+
+          negated_match_result = does_not_match?(matcher, actual, &block)
+          if custom_message && negated_match_result.respond_to?(:error_generator)
+            negated_match_result.error_generator.opts[:message] = custom_message
+          end
 
-        return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) unless initial_matcher
-        !(does_not_match?(matcher, actual, &block) || ExpectationHelper.handle_failure(matcher, message, :failure_message_when_negated))
+          negated_match_result || ExpectationHelper.handle_failure(matcher, custom_message, :failure_message_when_negated)
+        end
       end
 
       def self.does_not_match?(matcher, actual, &block)
@@ -79,7 +94,7 @@ module RSpec
       end
 
       def self.verb
-        "should not"
+        'is expected not to'
       end
 
       def self.should_method
@@ -95,7 +110,7 @@ module RSpec
     # order to present the current protocol.
     #
     # @private
-    class LegacyMacherAdapter < Matchers::MatcherDelegator
+    class LegacyMatcherAdapter < Matchers::MatcherDelegator
       def initialize(matcher)
         super
         ::RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''), :type => "legacy_matcher")
@@ -157,5 +172,11 @@ module RSpec
         end
       end
     end
+
+    # RSpec 3.0 was released with the class name misspelled. For SemVer compatibility,
+    # we will provide this misspelled alias until 4.0.
+    # @deprecated Use LegacyMatcherAdapter instead.
+    # @private
+    LegacyMacherAdapter = LegacyMatcherAdapter
   end
 end

data/lib/rspec/expectations/minitest_integration.rb

@@ -3,15 +3,56 @@ require 'rspec/expectations'
 Minitest::Test.class_eval do
   include ::RSpec::Matchers
 
+  # This `expect` will only be called if the user is using Minitest < 5.6
+  # or if they are _not_ using Minitest::Spec on 5.6+. Minitest::Spec on 5.6+
+  # defines its own `expect` and will have the assertions incremented via our
+  # definitions of `to`/`not_to`/`to_not` below.
   def expect(*a, &b)
-    assert(true) # so each expectation gets counted in minitest's assertion stats
+    self.assertions += 1
     super
   end
+
+  # Convert a `MultipleExpectationsNotMetError` to a `Minitest::Assertion` error so
+  # it gets counted in minitest's summary stats as a failure rather than an error.
+  # It would be nice to make `MultipleExpectationsNotMetError` subclass
+  # `Minitest::Assertion`, but Minitest's implementation does not treat subclasses
+  # the same, so this is the best we can do.
+  def aggregate_failures(*args, &block)
+    super
+  rescue RSpec::Expectations::MultipleExpectationsNotMetError => e
+    assertion_failed = Minitest::Assertion.new(e.message)
+    assertion_failed.set_backtrace e.backtrace
+    raise assertion_failed
+  end
+end
+
+# Older versions of Minitest (e.g. before 5.6) do not define
+# `Minitest::Expectation`.
+if defined?(::Minitest::Expectation)
+  Minitest::Expectation.class_eval do
+    include RSpec::Expectations::ExpectationTarget::InstanceMethods
+
+    def to(*args)
+      ctx.assertions += 1
+      super
+    end
+
+    def not_to(*args)
+      ctx.assertions += 1
+      super
+    end
+
+    def to_not(*args)
+      ctx.assertions += 1
+      super
+    end
+  end
 end
 
 module RSpec
   module Expectations
     remove_const :ExpectationNotMetError
-    ExpectationNotMetError = ::Minitest::Assertion
+    # Exception raised when an expectation fails.
+    const_set :ExpectationNotMetError, ::Minitest::Assertion
   end
 end

data/lib/rspec/expectations/syntax.rb

@@ -27,7 +27,7 @@ module RSpec
 
         RSpec.deprecate(
           "Using `#{method_name}` from rspec-expectations' old `:should` syntax without explicitly enabling the syntax",
-          :replacement => "the new `:expect` syntax or explicitly enable `:should`"
+          :replacement => "the new `:expect` syntax or explicitly enable `:should` with `config.expect_with(:rspec) { |c| c.syntax = :should }`"
         )
 
         @warn_about_should = false
@@ -41,12 +41,12 @@ module RSpec
 
         syntax_host.module_exec do
           def should(matcher=nil, message=nil, &block)
-            ::RSpec::Expectations::Syntax.warn_about_should_unless_configured(__method__)
+            ::RSpec::Expectations::Syntax.warn_about_should_unless_configured(::Kernel.__method__)
             ::RSpec::Expectations::PositiveExpectationHandler.handle_matcher(self, matcher, message, &block)
           end
 
           def should_not(matcher=nil, message=nil, &block)
-            ::RSpec::Expectations::Syntax.warn_about_should_unless_configured(__method__)
+            ::RSpec::Expectations::Syntax.warn_about_should_unless_configured(::Kernel.__method__)
             ::RSpec::Expectations::NegativeExpectationHandler.handle_matcher(self, matcher, message, &block)
           end
         end
@@ -106,7 +106,7 @@ if defined?(BasicObject)
   # that this syntax does not always play nice with delegate/proxy objects.
   # We recommend you use the non-monkeypatching `:expect` syntax instead.
   class BasicObject
-    # @method should
+    # @method should(matcher, message)
     # Passes if `matcher` returns true.  Available on every `Object`.
     # @example
     #   actual.should eq expected
@@ -118,7 +118,7 @@ if defined?(BasicObject)
     # @note This is only available when you have enabled the `:should` syntax.
     # @see RSpec::Matchers
 
-    # @method should_not
+    # @method should_not(matcher, message)
     # Passes if `matcher` returns false.  Available on every `Object`.
     # @example
     #   actual.should_not eq expected

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '3.0.4'
+      STRING = '3.12.3'
     end
   end
 end

data/lib/rspec/expectations.rb

@@ -1,6 +1,7 @@
 require 'rspec/support'
 RSpec::Support.require_rspec_support "caller_filter"
 RSpec::Support.require_rspec_support "warnings"
+RSpec::Support.require_rspec_support "object_formatter"
 
 require 'rspec/matchers'
 
@@ -63,6 +64,19 @@ module RSpec
     # the user sets an expectation, it can't be caught in their
     # code by a bare `rescue`.
     # @api public
-    ExpectationNotMetError = Class.new(::Exception)
+    class ExpectationNotMetError < Exception
+    end
+
+    # Exception raised from `aggregate_failures` when multiple expectations fail.
+    #
+    # @note The constant is defined here but the extensive logic of this class
+    #   is lazily defined when `FailureAggregator` is autoloaded, since we do
+    #   not need to waste time defining that functionality unless
+    #   `aggregate_failures` is used.
+    class MultipleExpectationsNotMetError < ExpectationNotMetError
+    end
+
+    autoload :BlockSnippetExtractor, "rspec/expectations/block_snippet_extractor"
+    autoload :FailureAggregator,     "rspec/expectations/failure_aggregator"
   end
 end