rspec-expectations 2.14.0 → 3.13.0

data/lib/rspec/expectations/configuration.rb

@@ -0,0 +1,230 @@
+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
+        @strict_predicate_matchers = false
+      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
+
+      # Configures RSpec to check predicate matchers to `be(true)` / `be(false)` (strict),
+      # or `be_truthy` / `be_falsey` (not strict).
+      # Historically, the default was `false`, but `true` is recommended.
+      def strict_predicate_matchers=(flag)
+        raise ArgumentError, "Pass `true` or `false`" unless flag == true || flag == false
+        @strict_predicate_matchers = flag
+      end
+
+      attr_reader :strict_predicate_matchers
+
+      def strict_predicate_matchers?
+        @strict_predicate_matchers
+      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

@@ -1,87 +1,163 @@
 module RSpec
   module Expectations
     # Wraps the target of an expectation.
+    #
     # @example
-    #   expect(something) # => ExpectationTarget wrapping something
+    #   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
-      class << self
-        attr_accessor :deprecated_should_enabled
-        alias deprecated_should_enabled? deprecated_should_enabled
-      end
+      # @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(target)
-        @target = target
+      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
+          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] 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, 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] 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, matcher)
-        RSpec::Expectations::NegativeExpectationHandler.handle_matcher(@target, matcher, message, &block)
+        enforce_value_expectation(matcher)
+        super
       end
-      alias to_not not_to
-
-      def self.enable_deprecated_should
-        return if deprecated_should_enabled?
 
-        def should(*args)
-          RSpec.deprecate "`expect { }.should`", :replacement => "`expect { }.to`"
-          @target.should(*args)
-        end
+    private
 
-        def should_not(*args)
-          RSpec.deprecate "`expect { }.should_not`", :replacement => "`expect { }.not_to`"
-          @target.should_not(*args)
-        end
+      def enforce_value_expectation(matcher)
+        return if supports_value_expectations?(matcher)
 
-        self.deprecated_should_enabled = true
+        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 self.disable_deprecated_should
-        return unless deprecated_should_enabled?
+      def supports_value_expectations?(matcher)
+        !matcher.respond_to?(:supports_value_expectations?) || matcher.supports_value_expectations?
+      end
+    end
 
-        remove_method :should
-        remove_method :should_not
+    # @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
 
-        self.deprecated_should_enabled = false
+      def not_to(matcher, message=nil, &block)
+        enforce_block_expectation(matcher)
+        super
       end
+      alias to_not not_to
 
     private
 
-      def prevent_operator_matchers(verb, matcher)
-        return if matcher
+      def enforce_block_expectation(matcher)
+        return if supports_block_expectations?(matcher)
 
-        raise ArgumentError, "The expect syntax does not support operator matchers, " +
-                             "so you must pass a matcher to `##{verb}`."
+        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.respond_to?(:supports_block_expectations?) && matcher.supports_block_expectations?
       end
     end
   end
 end
-

data/lib/rspec/expectations/fail_with.rb

@@ -1,9 +1,20 @@
 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
-        @differ ||= Differ.new
+        RSpec::Support::Differ.new(
+          :object_preparer => Differ::OBJECT_PREPARER,
+          :color => RSpec::Matchers.configuration.color?
+        )
       end
 
       # Raises an RSpec::Expectations::ExpectationNotMetError with message.
@@ -14,65 +25,14 @@ module RSpec
       # Adds a diff to the failure message when `expected` and `actual` are
       # both present.
       def fail_with(message, expected=nil, actual=nil)
-        if !message
-          raise ArgumentError, "Failure message is nil. Does your matcher define the " +
-                               "appropriate failure_message_for_* method to return a string?"
-        end
-
-        if actual && expected
-          if all_strings?(actual, expected)
-            if any_multiline_strings?(actual, expected)
-              message << "\nDiff:" << differ.diff_as_string(coerce_to_string(actual), coerce_to_string(expected))
-            end
-          elsif no_procs?(actual, expected) && no_numbers?(actual, expected)
-            message << "\nDiff:" << differ.diff_as_object(actual, expected)
-          end
+        unless message
+          raise ArgumentError, "Failure message is nil. Does your matcher define the " \
+                               "appropriate failure_message[_when_negated] method to return a string?"
         end
 
-        raise(RSpec::Expectations::ExpectationNotMetError.new(message))
-      end
-
-    private
-
-      def no_procs?(*args)
-        args.flatten.none? {|a| Proc === a}
-      end
-
-      def all_strings?(*args)
-        args.flatten.all? {|a| String === a}
-      end
+        message = ::RSpec::Matchers::MultiMatcherDiff.from(expected, actual).message_with_diff(message, differ)
 
-      def any_multiline_strings?(*args)
-        all_strings?(*args) && args.flatten.any? { |a| multiline?(a) }
-      end
-
-      def no_numbers?(*args)
-        args.flatten.none? {|a| Numeric === a}
-      end
-
-      def coerce_to_string(string_or_array)
-        return string_or_array unless Array === string_or_array
-        diffably_stringify(string_or_array).join("\n")
-      end
-
-      def diffably_stringify(array)
-        array.map do |entry|
-          if Array === entry
-            entry.inspect
-          else
-            entry.to_s.gsub("\n", "\\n")
-          end
-        end
-      end
-
-      if String.method_defined?(:encoding)
-        def multiline?(string)
-          string.include?("\n".encode(string.encoding))
-        end
-      else
-        def multiline?(string)
-          string.include?("\n")
-        end
+        RSpec::Support.notify_failure(RSpec::Expectations::ExpectationNotMetError.new message)
       end
     end
   end