rspec-expectations 2.14.0 → 3.13.0

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

@@ -1,7 +1,7 @@
 module RSpec
   module Expectations
-
-    class ExpectationHandler
+    # @private
+    module ExpectationHelper
       def self.check_message(msg)
         unless msg.nil? || msg.respond_to?(:to_str) || msg.respond_to?(:call)
           ::Kernel.warn [
@@ -11,24 +11,28 @@ module RSpec
           ].join
         end
       end
-    end
 
-    class PositiveExpectationHandler < ExpectationHandler
+      # Returns an RSpec-3+ compatible matcher, wrapping a legacy one
+      # in an adapter if necessary.
+      #
+      # @private
+      def self.modern_matcher_from(matcher)
+        LegacyMatcherAdapter::RSpec2.wrap(matcher) ||
+        LegacyMatcherAdapter::RSpec1.wrap(matcher) || matcher
+      end
 
-      def self.handle_matcher(actual, matcher, message=nil, &block)
+      def self.with_matcher(handler, matcher, message)
         check_message(message)
-        ::RSpec::Matchers.last_should = :should
+        matcher = modern_matcher_from(matcher)
+        yield matcher
+      ensure
+        ::RSpec::Matchers.last_expectation_handler = handler
         ::RSpec::Matchers.last_matcher = matcher
-        return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) if matcher.nil?
-
-        match = matcher.matches?(actual, &block)
-        return match if match
+      end
 
+      def self.handle_failure(matcher, message, failure_message_method)
         message = message.call if message.respond_to?(:call)
-
-        message ||= matcher.respond_to?(:failure_message_for_should) ?
-                    matcher.failure_message_for_should :
-                    matcher.failure_message
+        message ||= matcher.__send__(failure_message_method)
 
         if matcher.respond_to?(:diffable?) && matcher.diffable?
           ::RSpec::Expectations.fail_with message, matcher.expected, matcher.actual
@@ -38,31 +42,141 @@ module RSpec
       end
     end
 
-    class NegativeExpectationHandler < ExpectationHandler
-      def self.handle_matcher(actual, matcher, message=nil, &block)
-        check_message(message)
-        ::RSpec::Matchers.last_should = :should_not
-        ::RSpec::Matchers.last_matcher = matcher
-        return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) if matcher.nil?
+    # @private
+    class PositiveExpectationHandler
+      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
 
-        match = matcher.respond_to?(:does_not_match?) ?
-                !matcher.does_not_match?(actual, &block) :
-                matcher.matches?(actual, &block)
-        return match unless match
+          match_result = matcher.matches?(actual, &block)
+          if custom_message && match_result.respond_to?(:error_generator)
+            match_result.error_generator.opts[:message] = custom_message
+          end
 
-        message = message.call if message.respond_to?(:call)
+          match_result || ExpectationHelper.handle_failure(matcher, custom_message, :failure_message)
+        end
+      end
 
-        message ||= matcher.respond_to?(:failure_message_for_should_not) ?
-                    matcher.failure_message_for_should_not :
-                    matcher.negative_failure_message
+      def self.verb
+        'is expected to'
+      end
 
-        if matcher.respond_to?(:diffable?) && matcher.diffable?
-          ::RSpec::Expectations.fail_with message, matcher.expected, matcher.actual
+      def self.should_method
+        :should
+      end
+
+      def self.opposite_should_method
+        :should_not
+      end
+    end
+
+    # @private
+    class NegativeExpectationHandler
+      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
+
+          negated_match_result || ExpectationHelper.handle_failure(matcher, custom_message, :failure_message_when_negated)
+        end
+      end
+
+      def self.does_not_match?(matcher, actual, &block)
+        if matcher.respond_to?(:does_not_match?)
+          matcher.does_not_match?(actual, &block)
         else
-          ::RSpec::Expectations.fail_with message
+          !matcher.matches?(actual, &block)
+        end
+      end
+
+      def self.verb
+        'is expected not to'
+      end
+
+      def self.should_method
+        :should_not
+      end
+
+      def self.opposite_should_method
+        :should
+      end
+    end
+
+    # Wraps a matcher written against one of the legacy protocols in
+    # order to present the current protocol.
+    #
+    # @private
+    class LegacyMatcherAdapter < Matchers::MatcherDelegator
+      def initialize(matcher)
+        super
+        ::RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''), :type => "legacy_matcher")
+          |#{matcher.class.name || matcher.inspect} implements a legacy RSpec matcher
+          |protocol. For the current protocol you should expose the failure messages
+          |via the `failure_message` and `failure_message_when_negated` methods.
+          |(Used from #{CallerFilter.first_non_rspec_line})
+        EOS
+      end
+
+      def self.wrap(matcher)
+        new(matcher) if interface_matches?(matcher)
+      end
+
+      # Starting in RSpec 1.2 (and continuing through all 2.x releases),
+      # the failure message protocol was:
+      #   * `failure_message_for_should`
+      #   * `failure_message_for_should_not`
+      # @private
+      class RSpec2 < self
+        def failure_message
+          base_matcher.failure_message_for_should
+        end
+
+        def failure_message_when_negated
+          base_matcher.failure_message_for_should_not
+        end
+
+        def self.interface_matches?(matcher)
+          (
+            !matcher.respond_to?(:failure_message) &&
+            matcher.respond_to?(:failure_message_for_should)
+          ) || (
+            !matcher.respond_to?(:failure_message_when_negated) &&
+            matcher.respond_to?(:failure_message_for_should_not)
+          )
+        end
+      end
+
+      # Before RSpec 1.2, the failure message protocol was:
+      #   * `failure_message`
+      #   * `negative_failure_message`
+      # @private
+      class RSpec1 < self
+        def failure_message
+          base_matcher.failure_message
+        end
+
+        def failure_message_when_negated
+          base_matcher.negative_failure_message
+        end
+
+        # Note: `failure_message` is part of the RSpec 3 protocol
+        # (paired with `failure_message_when_negated`), so we don't check
+        # for `failure_message` here.
+        def self.interface_matches?(matcher)
+          !matcher.respond_to?(:failure_message_when_negated) &&
+          matcher.respond_to?(:negative_failure_message)
         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

@@ -0,0 +1,58 @@
+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)
+    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
+    # Exception raised when an expectation fails.
+    const_set :ExpectationNotMetError, ::Minitest::Assertion
+  end
+end