rspec-expectations 3.8.6

data/lib/rspec/expectations/configuration.rb

@@ -0,0 +1,215 @@
+RSpec::Support.require_rspec_expectations "syntax"
+
+module RSpec
+  module Expectations
+    # Provides configuration options for rspec-expectations.
+    # If you are using rspec-core, you can access this via a
+    # block passed to `RSpec::Core::Configuration#expect_with`.
+    # Otherwise, you can access it via RSpec::Expectations.configuration.
+    #
+    # @example
+    #   RSpec.configure do |rspec|
+    #     rspec.expect_with :rspec do |c|
+    #       # c is the config object
+    #     end
+    #   end
+    #
+    #   # or
+    #
+    #   RSpec::Expectations.configuration
+    class Configuration
+      # @private
+      FALSE_POSITIVE_BEHAVIOURS =
+        {
+          :warn    => lambda { |message| RSpec.warning message },
+          :raise   => lambda { |message| raise ArgumentError, message },
+          :nothing => lambda { |_| true },
+        }
+
+      def initialize
+        @on_potential_false_positives = :warn
+      end
+
+      # Configures the supported syntax.
+      # @param [Array<Symbol>, Symbol] values the syntaxes to enable
+      # @example
+      #   RSpec.configure do |rspec|
+      #     rspec.expect_with :rspec do |c|
+      #       c.syntax = :should
+      #       # or
+      #       c.syntax = :expect
+      #       # or
+      #       c.syntax = [:should, :expect]
+      #     end
+      #   end
+      def syntax=(values)
+        if Array(values).include?(:expect)
+          Expectations::Syntax.enable_expect
+        else
+          Expectations::Syntax.disable_expect
+        end
+
+        if Array(values).include?(:should)
+          Expectations::Syntax.enable_should
+        else
+          Expectations::Syntax.disable_should
+        end
+      end
+
+      # Configures the maximum character length that RSpec will print while
+      # formatting an object. You can set length to nil to prevent RSpec from
+      # doing truncation.
+      # @param [Fixnum] length the number of characters to limit the formatted output to.
+      # @example
+      #   RSpec.configure do |rspec|
+      #     rspec.expect_with :rspec do |c|
+      #       c.max_formatted_output_length = 200
+      #     end
+      #   end
+      def max_formatted_output_length=(length)
+        RSpec::Support::ObjectFormatter.default_instance.max_formatted_output_length = length
+      end
+
+      # The list of configured syntaxes.
+      # @return [Array<Symbol>] the list of configured syntaxes.
+      # @example
+      #   unless RSpec::Matchers.configuration.syntax.include?(:expect)
+      #     raise "this RSpec extension gem requires the rspec-expectations `:expect` syntax"
+      #   end
+      def syntax
+        syntaxes = []
+        syntaxes << :should if Expectations::Syntax.should_enabled?
+        syntaxes << :expect if Expectations::Syntax.expect_enabled?
+        syntaxes
+      end
+
+      if ::RSpec.respond_to?(:configuration)
+        def color?
+          ::RSpec.configuration.color_enabled?
+        end
+      else
+        # Indicates whether or not diffs should be colored.
+        # Delegates to rspec-core's color option if rspec-core
+        # is loaded; otherwise you can set it here.
+        attr_writer :color
+
+        # Indicates whether or not diffs should be colored.
+        # Delegates to rspec-core's color option if rspec-core
+        # is loaded; otherwise you can set it here.
+        def color?
+          defined?(@color) && @color
+        end
+      end
+
+      # Adds `should` and `should_not` to the given classes
+      # or modules. This can be used to ensure `should` works
+      # properly on things like proxy objects (particular
+      # `Delegator`-subclassed objects on 1.8).
+      #
+      # @param [Array<Module>] modules the list of classes or modules
+      #   to add `should` and `should_not` to.
+      def add_should_and_should_not_to(*modules)
+        modules.each do |mod|
+          Expectations::Syntax.enable_should(mod)
+        end
+      end
+
+      # Sets or gets the backtrace formatter. The backtrace formatter should
+      # implement `#format_backtrace(Array<String>)`. This is used
+      # to format backtraces of errors handled by the `raise_error`
+      # matcher.
+      #
+      # If you are using rspec-core, rspec-core's backtrace formatting
+      # will be used (including respecting the presence or absence of
+      # the `--backtrace` option).
+      #
+      # @!attribute [rw] backtrace_formatter
+      attr_writer :backtrace_formatter
+      def backtrace_formatter
+        @backtrace_formatter ||= if defined?(::RSpec.configuration.backtrace_formatter)
+                                   ::RSpec.configuration.backtrace_formatter
+                                 else
+                                   NullBacktraceFormatter
+                                 end
+      end
+
+      # Sets if custom matcher descriptions and failure messages
+      # should include clauses from methods defined using `chain`.
+      # @param value [Boolean]
+      attr_writer :include_chain_clauses_in_custom_matcher_descriptions
+
+      # Indicates whether or not custom matcher descriptions and failure messages
+      # should include clauses from methods defined using `chain`. It is
+      # false by default for backwards compatibility.
+      def include_chain_clauses_in_custom_matcher_descriptions?
+        @include_chain_clauses_in_custom_matcher_descriptions ||= false
+      end
+
+      # @private
+      def reset_syntaxes_to_default
+        self.syntax = [:should, :expect]
+        RSpec::Expectations::Syntax.warn_about_should!
+      end
+
+      # @api private
+      # Null implementation of a backtrace formatter used by default
+      # when rspec-core is not loaded. Does no filtering.
+      NullBacktraceFormatter = Module.new do
+        def self.format_backtrace(backtrace)
+          backtrace
+        end
+      end
+
+      # Configures whether RSpec will warn about matcher use which will
+      # potentially cause false positives in tests.
+      #
+      # @param [Boolean] boolean
+      def warn_about_potential_false_positives=(boolean)
+        if boolean
+          self.on_potential_false_positives = :warn
+        elsif warn_about_potential_false_positives?
+          self.on_potential_false_positives = :nothing
+        else
+          # no-op, handler is something else
+        end
+      end
+      #
+      # Configures what RSpec will do about matcher use which will
+      # potentially cause false positives in tests.
+      #
+      # @param [Symbol] behavior can be set to :warn, :raise or :nothing
+      def on_potential_false_positives=(behavior)
+        unless FALSE_POSITIVE_BEHAVIOURS.key?(behavior)
+          raise ArgumentError, "Supported values are: #{FALSE_POSITIVE_BEHAVIOURS.keys}"
+        end
+        @on_potential_false_positives = behavior
+      end
+
+      # Indicates what RSpec will do about matcher use which will
+      # potentially cause false positives in tests, generally you want to
+      # avoid such scenarios so this defaults to `true`.
+      attr_reader :on_potential_false_positives
+
+      # Indicates whether RSpec will warn about matcher use which will
+      # potentially cause false positives in tests, generally you want to
+      # avoid such scenarios so this defaults to `true`.
+      def warn_about_potential_false_positives?
+        on_potential_false_positives == :warn
+      end
+
+      # @private
+      def false_positives_handler
+        FALSE_POSITIVE_BEHAVIOURS.fetch(@on_potential_false_positives)
+      end
+    end
+
+    # The configuration object.
+    # @return [RSpec::Expectations::Configuration] the configuration object
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    # set default syntax
+    configuration.reset_syntaxes_to_default
+  end
+end

data/lib/rspec/expectations/expectation_target.rb

@@ -0,0 +1,127 @@
+module RSpec
+  module Expectations
+    # Wraps the target of an expectation.
+    #
+    # @example
+    #   expect(something)       # => ExpectationTarget wrapping something
+    #   expect { do_something } # => ExpectationTarget wrapping the block
+    #
+    #   # used with `to`
+    #   expect(actual).to eq(3)
+    #
+    #   # with `not_to`
+    #   expect(actual).not_to eq(3)
+    #
+    # @note `ExpectationTarget` is not intended to be instantiated
+    #   directly by users. Use `expect` instead.
+    class ExpectationTarget
+      # @private
+      # Used as a sentinel value to be able to tell when the user
+      # did not pass an argument. We can't use `nil` for that because
+      # `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
+      end
+
+      # @private
+      def self.for(value, block)
+        if UndefinedValue.equal?(value)
+          unless block
+            raise ArgumentError, "You must pass either an argument or a block to `expect`."
+          end
+          BlockExpectationTarget.new(block)
+        elsif block
+          raise ArgumentError, "You cannot pass both an argument and a block to `expect`."
+        else
+          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 or 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 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)
+        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
+
+      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 BlockExpectationTarget < ExpectationTarget
+      def to(matcher, message=nil, &block)
+        enforce_block_expectation(matcher)
+        super
+      end
+
+      def not_to(matcher, message=nil, &block)
+        enforce_block_expectation(matcher)
+        super
+      end
+      alias to_not not_to
+
+    private
+
+      def enforce_block_expectation(matcher)
+        return if supports_block_expectations?(matcher)
+
+        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
+    end
+  end
+end

data/lib/rspec/expectations/fail_with.rb

@@ -0,0 +1,39 @@
+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 => Differ::OBJECT_PREPARER,
+          :color => RSpec::Matchers.configuration.color?
+        )
+      end
+
+      # Raises an RSpec::Expectations::ExpectationNotMetError with message.
+      # @param [String] message
+      # @param [Object] expected
+      # @param [Object] actual
+      #
+      # Adds a diff to the failure message when `expected` and `actual` are
+      # both present.
+      def fail_with(message, expected=nil, actual=nil)
+        unless message
+          raise ArgumentError, "Failure message is nil. Does your matcher define the " \
+                               "appropriate failure_message[_when_negated] method to return a string?"
+        end
+
+        message = ::RSpec::Matchers::ExpectedsForMultipleDiffs.from(expected).message_with_diff(message, differ, actual)
+
+        RSpec::Support.notify_failure(RSpec::Expectations::ExpectationNotMetError.new message)
+      end
+    end
+  end
+end

data/lib/rspec/expectations/failure_aggregator.rb

@@ -0,0 +1,194 @@
+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?
+        # On JRuby, `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 nil
+        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
+          "#{index_label index}#{indented formatted_message, index}"
+        end
+      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