rspec-expectations 2.11.3 → 3.11.0

data/lib/rspec/expectations/failure_aggregator.rb

@@ -0,0 +1,212 @@
+module RSpec
+  module Expectations
+    # @private
+    class FailureAggregator
+      attr_reader :block_label, :metadata
+
+      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
+      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,18 +1,39 @@
 module RSpec
   module Expectations
-    class PositiveExpectationHandler        
-      def self.handle_matcher(actual, matcher, message=nil, &block)
-        ::RSpec::Matchers.last_should = :should
+    # @private
+    module ExpectationHelper
+      def self.check_message(msg)
+        unless msg.nil? || msg.respond_to?(:to_str) || msg.respond_to?(:call)
+          ::Kernel.warn [
+            "WARNING: ignoring the provided expectation message argument (",
+            msg.inspect,
+            ") since it is not a string or a proc."
+          ].join
+        end
+      end
+
+      # 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.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 = matcher
-        return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) if matcher.nil?
-
-        match = matcher.matches?(actual, &block)
-        return match if match
-        
-        message ||= matcher.respond_to?(:failure_message_for_should) ?
-                    matcher.failure_message_for_should :
-                    matcher.failure_message
-        
+      end
+
+      def self.handle_failure(matcher, message, failure_message_method)
+        message = message.call if message.respond_to?(:call)
+        message ||= matcher.__send__(failure_message_method)
+
         if matcher.respond_to?(:diffable?) && matcher.diffable?
           ::RSpec::Expectations.fail_with message, matcher.expected, matcher.actual
         else
@@ -21,28 +42,141 @@ module RSpec
       end
     end
 
+    # @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_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
+        'is expected to'
+      end
+
+      def self.should_method
+        :should
+      end
+
+      def self.opposite_should_method
+        :should_not
+      end
+    end
+
+    # @private
     class NegativeExpectationHandler
-      def self.handle_matcher(actual, matcher, message=nil, &block)
-        ::RSpec::Matchers.last_should = :should_not
-        ::RSpec::Matchers.last_matcher = matcher
-        return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) if matcher.nil?
-        
-        match = matcher.respond_to?(:does_not_match?) ?
-                !matcher.does_not_match?(actual, &block) :
-                matcher.matches?(actual, &block)
-        return match unless match
-        
-        message ||= matcher.respond_to?(:failure_message_for_should_not) ?
-                    matcher.failure_message_for_should_not :
-                    matcher.negative_failure_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
 
-        if matcher.respond_to?(:diffable?) && matcher.diffable?
-          ::RSpec::Expectations.fail_with message, matcher.expected, matcher.actual
+          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

data/lib/rspec/expectations/syntax.rb

@@ -4,38 +4,7 @@ module RSpec
     # Provides methods for enabling and disabling the available
     # syntaxes provided by rspec-expectations.
     module Syntax
-      extend self
-
-      # @method should
-      # Passes if `matcher` returns true.  Available on every `Object`.
-      # @example
-      #   actual.should eq expected
-      #   actual.should match /expression/
-      # @param [Matcher]
-      #   matcher
-      # @param [String] message optional message to display when the expectation fails
-      # @return [Boolean] true if the expectation succeeds (else raises)
-      # @see RSpec::Matchers
-
-      # @method should_not
-      # Passes if `matcher` returns false.  Available on every `Object`.
-      # @example
-      #   actual.should_not eq expected
-      # @param [Matcher]
-      #   matcher
-      # @param [String] message optional message to display when the expectation fails
-      # @return [Boolean] false if the negative expectation succeeds (else raises)
-      # @see RSpec::Matchers
-
-      # @method expect
-      # Supports `expect(actual).to matcher` syntax by wrapping `actual` in an
-      # `ExpectationTarget`.
-      # @example
-      #   expect(actual).to eq(expected)
-      #   expect(actual).to_not eq(expected)
-      # @return [ExpectationTarget]
-      # @see ExpectationTarget#to
-      # @see ExpectationTarget#to_not
+      module_function
 
       # @api private
       # Determines where we add `should` and `should_not`.
@@ -43,76 +12,121 @@ module RSpec
         @default_should_host ||= ::Object.ancestors.last
       end
 
+      # @api private
+      # Instructs rspec-expectations to warn on first usage of `should` or `should_not`.
+      # Enabled by default. This is largely here to facilitate testing.
+      def warn_about_should!
+        @warn_about_should = true
+      end
+
+      # @api private
+      # Generates a deprecation warning for the given method if no warning
+      # has already been issued.
+      def warn_about_should_unless_configured(method_name)
+        return unless @warn_about_should
+
+        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` with `config.expect_with(:rspec) { |c| c.syntax = :should }`"
+        )
+
+        @warn_about_should = false
+      end
+
       # @api private
       # Enables the `should` syntax.
-      def enable_should(syntax_host = default_should_host)
+      def enable_should(syntax_host=default_should_host)
+        @warn_about_should = false if syntax_host == default_should_host
         return if should_enabled?(syntax_host)
 
-        syntax_host.module_eval do
+        syntax_host.module_exec do
           def should(matcher=nil, message=nil, &block)
+            ::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(::Kernel.__method__)
             ::RSpec::Expectations::NegativeExpectationHandler.handle_matcher(self, matcher, message, &block)
           end
         end
-
-        ::RSpec::Expectations::ExpectationTarget.enable_deprecated_should if expect_enabled?
       end
 
       # @api private
       # Disables the `should` syntax.
-      def disable_should(syntax_host = default_should_host)
+      def disable_should(syntax_host=default_should_host)
         return unless should_enabled?(syntax_host)
 
-        syntax_host.module_eval do
+        syntax_host.module_exec do
           undef should
           undef should_not
         end
-
-        ::RSpec::Expectations::ExpectationTarget.disable_deprecated_should
       end
 
       # @api private
       # Enables the `expect` syntax.
-      def enable_expect(syntax_host = ::RSpec::Matchers)
+      def enable_expect(syntax_host=::RSpec::Matchers)
         return if expect_enabled?(syntax_host)
 
-        syntax_host.module_eval do
-          def expect(*target, &target_block)
-            target << target_block if block_given?
-            raise ArgumentError.new("You must pass an argument or a block to #expect but not both.") unless target.size == 1
-            ::RSpec::Expectations::ExpectationTarget.new(target.first)
+        syntax_host.module_exec do
+          def expect(value=::RSpec::Expectations::ExpectationTarget::UndefinedValue, &block)
+            ::RSpec::Expectations::ExpectationTarget.for(value, block)
           end
         end
-
-        ::RSpec::Expectations::ExpectationTarget.enable_deprecated_should if should_enabled?
       end
 
       # @api private
       # Disables the `expect` syntax.
-      def disable_expect(syntax_host = ::RSpec::Matchers)
+      def disable_expect(syntax_host=::RSpec::Matchers)
         return unless expect_enabled?(syntax_host)
 
-        syntax_host.module_eval do
+        syntax_host.module_exec do
           undef expect
         end
-
-        ::RSpec::Expectations::ExpectationTarget.disable_deprecated_should
       end
 
       # @api private
       # Indicates whether or not the `should` syntax is enabled.
-      def should_enabled?(syntax_host = default_should_host)
+      def should_enabled?(syntax_host=default_should_host)
         syntax_host.method_defined?(:should)
       end
 
       # @api private
       # Indicates whether or not the `expect` syntax is enabled.
-      def expect_enabled?(syntax_host = ::RSpec::Matchers)
+      def expect_enabled?(syntax_host=::RSpec::Matchers)
         syntax_host.method_defined?(:expect)
       end
     end
   end
 end
+
+if defined?(BasicObject)
+  # The legacy `:should` syntax adds the following methods directly to
+  # `BasicObject` so that they are available off of any object. Note, however,
+  # 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(matcher, message)
+    # Passes if `matcher` returns true.  Available on every `Object`.
+    # @example
+    #   actual.should eq expected
+    #   actual.should match /expression/
+    # @param [Matcher]
+    #   matcher
+    # @param [String] message optional message to display when the expectation fails
+    # @return [Boolean] true if the expectation succeeds (else raises)
+    # @note This is only available when you have enabled the `:should` syntax.
+    # @see RSpec::Matchers
+
+    # @method should_not(matcher, message)
+    # Passes if `matcher` returns false.  Available on every `Object`.
+    # @example
+    #   actual.should_not eq expected
+    # @param [Matcher]
+    #   matcher
+    # @param [String] message optional message to display when the expectation fails
+    # @return [Boolean] false if the negative expectation succeeds (else raises)
+    # @note This is only available when you have enabled the `:should` syntax.
+    # @see RSpec::Matchers
+  end
+end

data/lib/rspec/expectations/version.rb

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