rspec-expectations 2.14.0 → 3.13.0

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).not_to eq(expected)
-      # @return [ExpectationTarget]
-      # @see ExpectationTarget#to
-      # @see ExpectationTarget#not_to
+      module_function
 
       # @api private
       # Determines where we add `should` and `should_not`.
@@ -43,122 +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
-
-      # @api private
-      # Generates a positive expectation expression.
-      def positive_expression(target_expression, matcher_expression)
-        expression_generator.positive_expression(target_expression, matcher_expression)
-      end
-
-      # @api private
-      # Generates a negative expectation expression.
-      def negative_expression(target_expression, matcher_expression)
-        expression_generator.negative_expression(target_expression, matcher_expression)
-      end
-
-      # @api private
-      # Selects which expression generator to use based on the configured syntax.
-      def expression_generator
-        if expect_enabled?
-          ExpectExpressionGenerator
-        else
-          ShouldExpressionGenerator
-        end
-      end
-
-      # @api private
-      # Generates expectation expressions for the `should` syntax.
-      module ShouldExpressionGenerator
-        def self.positive_expression(target_expression, matcher_expression)
-          "#{target_expression}.should #{matcher_expression}"
-        end
-
-        def self.negative_expression(target_expression, matcher_expression)
-          "#{target_expression}.should_not #{matcher_expression}"
-        end
-      end
-
-      # @api private
-      # Generates expectation expressions for the `expect` syntax.
-      module ExpectExpressionGenerator
-        def self.positive_expression(target_expression, matcher_expression)
-          "expect(#{target_expression}).to #{matcher_expression}"
-        end
-
-        def self.negative_expression(target_expression, matcher_expression)
-          "expect(#{target_expression}).not_to #{matcher_expression}"
-        end
-      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.14.0'
+      STRING = '3.13.0'
     end
   end
 end

data/lib/rspec/expectations.rb

@@ -1,40 +1,55 @@
-require 'rspec/expectations/extensions'
+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'
-require 'rspec/expectations/expectation_target'
-require 'rspec/matchers/configuration'
-require 'rspec/expectations/fail_with'
-require 'rspec/expectations/errors'
-require 'rspec/expectations/deprecation'
-require 'rspec/expectations/handler'
-require 'rspec/expectations/version'
-require 'rspec/expectations/differ'
+
+RSpec::Support.define_optimized_require_for_rspec(:expectations) { |f| require_relative(f) }
+
+%w[
+  expectation_target
+  configuration
+  fail_with
+  handler
+  version
+].each { |file| RSpec::Support.require_rspec_expectations(file) }
 
 module RSpec
-  # RSpec::Expectations adds two instance methods to every object:
+  # RSpec::Expectations provides a simple, readable API to express
+  # the expected outcomes in a code example. To express an expected
+  # outcome, wrap an object or block in `expect`, call `to` or `to_not`
+  # (aliased as `not_to`) and pass it a matcher object:
   #
-  #     should(matcher=nil)
-  #     should_not(matcher=nil)
+  #     expect(order.total).to eq(Money.new(5.55, :USD))
+  #     expect(list).to include(user)
+  #     expect(message).not_to match(/foo/)
+  #     expect { do_something }.to raise_error
   #
-  # Both methods take an optional matcher object (See
-  # [RSpec::Matchers](../RSpec/Matchers)).  When `should` is invoked with a
-  # matcher, it turns around and calls `matcher.matches?(self)`.  For example,
+  # The last form (the block form) is needed to match against ruby constructs
+  # that are not objects, but can only be observed when executing a block
+  # of code. This includes raising errors, throwing symbols, yielding,
+  # and changing values.
+  #
+  # When `expect(...).to` is invoked with a matcher, it turns around
+  # and calls `matcher.matches?(<object wrapped by expect>)`.  For example,
   # in the expression:
   #
-  #     order.total.should eq(Money.new(5.55, :USD))
+  #     expect(order.total).to eq(Money.new(5.55, :USD))
   #
-  # the `should` method invokes the equivalent of `eq.matches?(order.total)`. If
-  # `matches?` returns true, the expectation is met and execution continues. If
-  # `false`, then the spec fails with the message returned by
-  # `eq.failure_message_for_should`.
+  # ...`eq(Money.new(5.55, :USD))` returns a matcher object, and it results
+  # in the equivalent of `eq.matches?(order.total)`. If `matches?` returns
+  # `true`, the expectation is met and execution continues. If `false`, then
+  # the spec fails with the message returned by `eq.failure_message`.
   #
   # Given the expression:
   #
-  #     order.entries.should_not include(entry)
+  #     expect(order.entries).not_to include(entry)
   #
-  # the `should_not` method invokes the equivalent of
+  # ...the `not_to` method (also available as `to_not`) invokes the equivalent of
   # `include.matches?(order.entries)`, but it interprets `false` as success, and
   # `true` as a failure, using the message generated by
-  # `eq.failure_message_for_should_not`.
+  # `include.failure_message_when_negated`.
   #
   # rspec-expectations ships with a standard set of useful matchers, and writing
   # your own matchers is quite simple.
@@ -43,5 +58,25 @@ module RSpec
   # built-in matchers that ship with rspec-expectations, and how to write your
   # own custom matchers.
   module Expectations
+    # Exception raised when an expectation fails.
+    #
+    # @note We subclass Exception so that in a stub implementation if
+    # the user sets an expectation, it can't be caught in their
+    # code by a bare `rescue`.
+    # @api public
+    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

data/lib/rspec/matchers/aliased_matcher.rb

@@ -0,0 +1,116 @@
+module RSpec
+  module Matchers
+    # Decorator that wraps a matcher and overrides `description`
+    # using the provided block in order to support an alias
+    # of a matcher. This is intended for use when composing
+    # matchers, so that you can use an expression like
+    # `include( a_value_within(0.1).of(3) )` rather than
+    # `include( be_within(0.1).of(3) )`, and have the corresponding
+    # description read naturally.
+    #
+    # @api private
+    class AliasedMatcher < MatcherDelegator
+      def initialize(base_matcher, description_block)
+        @description_block = description_block
+        super(base_matcher)
+      end
+
+      # Forward messages on to the wrapped matcher.
+      # Since many matchers provide a fluent interface
+      # (e.g. `a_value_within(0.1).of(3)`), we need to wrap
+      # the returned value if it responds to `description`,
+      # so that our override can be applied when it is eventually
+      # used.
+      def method_missing(*)
+        return_val = super
+        return return_val unless RSpec::Matchers.is_a_matcher?(return_val)
+        self.class.new(return_val, @description_block)
+      end
+
+      # Provides the description of the aliased matcher. Aliased matchers
+      # are designed to behave identically to the original matcher except
+      # for the description and failure messages. The description is different
+      # to reflect the aliased name.
+      #
+      # @api private
+      def description
+        @description_block.call(super)
+      end
+
+      # Provides the failure_message of the aliased matcher. Aliased matchers
+      # are designed to behave identically to the original matcher except
+      # for the description and failure messages. The failure_message is different
+      # to reflect the aliased name.
+      #
+      # @api private
+      def failure_message
+        @description_block.call(super)
+      end
+
+      # Provides the failure_message_when_negated of the aliased matcher. Aliased matchers
+      # are designed to behave identically to the original matcher except
+      # for the description and failure messages. The failure_message_when_negated is different
+      # to reflect the aliased name.
+      #
+      # @api private
+      def failure_message_when_negated
+        @description_block.call(super)
+      end
+    end
+
+    # Decorator used for matchers that have special implementations of
+    # operators like `==` and `===`.
+    # @private
+    class AliasedMatcherWithOperatorSupport < AliasedMatcher
+      # We undef these so that they get delegated via `method_missing`.
+      undef ==
+      undef ===
+    end
+
+    # @private
+    class AliasedNegatedMatcher < AliasedMatcher
+      def matches?(*args, &block)
+        if @base_matcher.respond_to?(:does_not_match?)
+          @base_matcher.does_not_match?(*args, &block)
+        else
+          !super
+        end
+      end
+
+      def does_not_match?(*args, &block)
+        @base_matcher.matches?(*args, &block)
+      end
+
+      def failure_message
+        optimal_failure_message(__method__, :failure_message_when_negated)
+      end
+
+      def failure_message_when_negated
+        optimal_failure_message(__method__, :failure_message)
+      end
+
+    private
+
+      DefaultFailureMessages = BuiltIn::BaseMatcher::DefaultFailureMessages
+
+      # For a matcher that uses the default failure messages, we prefer to
+      # use the override provided by the `description_block`, because it
+      # includes the phrasing that the user has expressed a preference for
+      # by going through the effort of defining a negated matcher.
+      #
+      # However, if the override didn't actually change anything, then we
+      # should return the opposite failure message instead -- the overridden
+      # message is going to be confusing if we return it as-is, as it represents
+      # the non-negated failure message for a negated match (or vice versa).
+      def optimal_failure_message(same, inverted)
+        if DefaultFailureMessages.has_default_failure_messages?(@base_matcher)
+          base_message = @base_matcher.__send__(same)
+          overridden    = @description_block.call(base_message)
+          return overridden if overridden != base_message
+        end
+
+        @base_matcher.__send__(inverted)
+      end
+    end
+  end
+end

data/lib/rspec/matchers/built_in/all.rb

@@ -0,0 +1,86 @@
+module RSpec
+  module Matchers
+    module BuiltIn
+      # @api private
+      # Provides the implementation for `all`.
+      # Not intended to be instantiated directly.
+      class All < BaseMatcher
+        # @private
+        attr_reader :matcher, :failed_objects
+
+        def initialize(matcher)
+          @matcher = matcher
+          @failed_objects = {}
+        end
+
+        # @private
+        def does_not_match?(_actual)
+          raise NotImplementedError, '`expect().not_to all( matcher )` is not supported.'
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message
+          unless iterable?
+            return "#{improve_hash_formatting(super)}, but was not iterable"
+          end
+
+          all_messages = [improve_hash_formatting(super)]
+          failed_objects.each do |index, matcher_failure_message|
+            all_messages << failure_message_for_item(index, matcher_failure_message)
+          end
+          all_messages.join("\n\n")
+        end
+
+        # @api private
+        # @return [String]
+        def description
+          improve_hash_formatting "all #{description_of matcher}"
+        end
+
+      private
+
+        def match(_expected, _actual)
+          return false unless iterable?
+
+          index_failed_objects
+          failed_objects.empty?
+        end
+
+        def index_failed_objects
+          actual.each_with_index do |actual_item, index|
+            cloned_matcher = matcher.clone
+            matches = cloned_matcher.matches?(actual_item)
+            failed_objects[index] = cloned_matcher.failure_message unless matches
+          end
+        end
+
+        def failure_message_for_item(index, failure_message)
+          failure_message = indent_multiline_message(add_new_line_if_needed(failure_message))
+          indent_multiline_message("object at index #{index} failed to match:#{failure_message}")
+        end
+
+        def add_new_line_if_needed(message)
+          message.start_with?("\n") ? message : "\n#{message}"
+        end
+
+        def indent_multiline_message(message)
+          message = message.sub(/\n+\z/, '')
+          message.lines.map do |line|
+            line =~ /\S/ ? '   ' + line : line
+          end.join
+        end
+
+        def initialize_copy(other)
+          @matcher = @matcher.clone
+          @failed_objects = @failed_objects.clone
+          super
+        end
+
+        def iterable?
+          @actual.respond_to?(:each_with_index)
+        end
+      end
+    end
+  end
+end