rspec-expectations 2.13.0 → 3.0.0

data/lib/rspec/expectations/handler.rb

@@ -1,31 +1,36 @@
 module RSpec
   module Expectations
 
-    class ExpectationHandler
-      def self.message_must_be_string(msg)
-        "WARNING: ignoring the provided expectation message argument " +
-        "(#{msg.inspect}) since it is not a string."
-      end
-
+    # @private
+    module ExpectationHelper
       def self.check_message(msg)
-        ::Kernel.warn message_must_be_string(msg) unless msg.nil? || msg.is_a?(String)
+        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
-    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)
+        LegacyMacherAdapter::RSpec2.wrap(matcher) ||
+        LegacyMacherAdapter::RSpec1.wrap(matcher) || matcher
+      end
 
-      def self.handle_matcher(actual, matcher, message=nil, &block)
+      def self.setup(handler, matcher, message)
         check_message(message)
-        ::RSpec::Matchers.last_should = :should
-        ::RSpec::Matchers.last_matcher = matcher
-        return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) if matcher.nil?
-
-        match = matcher.matches?(actual, &block)
-        return match if match
+        ::RSpec::Matchers.last_expectation_handler = handler
+        ::RSpec::Matchers.last_matcher = modern_matcher_from(matcher)
+      end
 
-        message ||= matcher.respond_to?(:failure_message_for_should) ?
-                    matcher.failure_message_for_should :
-                    matcher.failure_message
+      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
@@ -35,26 +40,121 @@ 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, message=nil, &block)
+        matcher = ExpectationHelper.setup(self, initial_matcher, message)
 
-        match = matcher.respond_to?(:does_not_match?) ?
-                !matcher.does_not_match?(actual, &block) :
-                matcher.matches?(actual, &block)
-        return match unless match
+        return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) unless initial_matcher
+        matcher.matches?(actual, &block) or ExpectationHelper.handle_failure(matcher, message, :failure_message)
+      end
 
-        message ||= matcher.respond_to?(:failure_message_for_should_not) ?
-                    matcher.failure_message_for_should_not :
-                    matcher.negative_failure_message
+      def self.verb
+        "should"
+      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, message=nil, &block)
+        matcher = ExpectationHelper.setup(self, initial_matcher, message)
+
+        return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) unless initial_matcher
+        !(does_not_match?(matcher, actual, &block) or ExpectationHelper.handle_failure(matcher, message, :failure_message_when_negated))
+      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
+        "should not"
+      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 LegacyMacherAdapter < 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

data/lib/rspec/expectations/minitest_integration.rb

@@ -0,0 +1,16 @@
+require 'rspec/expectations'
+
+Minitest::Test.class_eval do
+  include ::RSpec::Matchers
+
+  def expect(*a, &b)
+    assert(true) # so each expectation gets counted in minitest's assertion stats
+    super
+  end
+end
+
+module RSpec::Expectations
+  remove_const :ExpectationNotMetError
+  ExpectationNotMetError = ::Minitest::Assertion
+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,22 +12,44 @@ 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)
+        if @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`"
+          )
+
+          @warn_about_should = false
+        end
+      end
+
       # @api private
       # Enables the `should` syntax.
       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(__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(__method__)
             ::RSpec::Expectations::NegativeExpectationHandler.handle_matcher(self, matcher, message, &block)
           end
         end
-
-        ::RSpec::Expectations::ExpectationTarget.enable_deprecated_should if expect_enabled?
       end
 
       # @api private
@@ -66,12 +57,10 @@ module RSpec
       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
@@ -79,15 +68,11 @@ module RSpec
       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
@@ -95,11 +80,9 @@ module RSpec
       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
@@ -113,52 +96,35 @@ module RSpec
       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
+
+# 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
+  # 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
+  # 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

data/lib/rspec/expectations/version.rb

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

data/lib/rspec/expectations.rb

@@ -1,47 +1,69 @@
-require 'rspec/expectations/extensions'
+require 'rspec/support'
+RSpec::Support.require_rspec_support "caller_filter"
+RSpec::Support.require_rspec_support "warnings"
+
 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`.
+  # `eq.failure_message_when_negated`.
   #
   # rspec-expectations ships with a standard set of useful matchers, and writing
-  # your own matchers is quite simple. 
+  # your own matchers is quite simple.
   #
   # See [RSpec::Matchers](../RSpec/Matchers) for more information about the
   # 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
+    ExpectationNotMetError = Class.new(::Exception)
   end
 end
+

data/lib/rspec/matchers/aliased_matcher.rb

@@ -0,0 +1,41 @@
+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 return_val.respond_to?(:description)
+        AliasedMatcher.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 this method. The description is different to reflect the aliased
+      # name.
+      #
+      # @api private
+      def description
+        @description_block.call(super)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+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
+          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
+          described_items = surface_descriptions_in(matcher)
+          improve_hash_formatting "all#{to_sentence(described_items)}"
+        end
+
+      private
+
+        def match(_, actual)
+          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
+          super
+        end
+
+      end
+    end
+  end
+end