rspec-expectations 2.11.3 → 3.11.0

data/lib/rspec/expectations.rb

@@ -1,47 +1,82 @@
-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. 
+  # 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
+    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 overriden
+      # 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)
+          overriden    = @description_block.call(base_message)
+          return overriden if overriden != 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

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

@@ -4,27 +4,46 @@ module RSpec
       # @api private
       #
       # Used _internally_ as a base class for matchers that ship with
-      # rspec-expectations.
+      # rspec-expectations and rspec-rails.
       #
       # ### Warning:
       #
-      # This class is for internal use, and subject to change without notice.  We
-      # strongly recommend that you do not base your custom matchers on this
+      # This class is for internal use, and subject to change without notice.
+      # We strongly recommend that you do not base your custom matchers on this
       # class. If/when this changes, we will announce it and remove this warning.
       class BaseMatcher
-        include RSpec::Matchers::Pretty
+        include RSpec::Matchers::Composable
 
+        # @api private
+        # Used to detect when no arg is passed to `initialize`.
+        # `nil` cannot be used because it's a valid value to pass.
+        UNDEFINED = Object.new.freeze
+
+        # @private
         attr_reader :actual, :expected, :rescued_exception
 
-        def initialize(expected = nil)
-          @expected = expected
+        # @private
+        attr_writer :matcher_name
+
+        def initialize(expected=UNDEFINED)
+          @expected = expected unless UNDEFINED.equal?(expected)
         end
 
+        # @api private
+        # Indicates if the match is successful. Delegates to `match`, which
+        # should be defined on a subclass. Takes care of consistently
+        # initializing the `actual` attribute.
         def matches?(actual)
           @actual = actual
           match(expected, actual)
         end
 
+        # @api private
+        # Used to wrap a block of code that will indicate failure by
+        # raising one of the named exceptions.
+        #
+        # This is used by rspec-rails for some of its matchers that
+        # wrap rails' assertions.
         def match_unless_raises(*exceptions)
           exceptions.unshift Exception if exceptions.empty?
           begin
@@ -35,33 +54,144 @@ module RSpec
           end
         end
 
-        def failure_message_for_should
-          assert_ivars :@actual, :@expected
-          "expected #{@actual.inspect} to #{name_to_sentence}#{expected_to_sentence}"
+        # @api private
+        # Generates a description using {EnglishPhrasing}.
+        # @return [String]
+        def description
+          desc = EnglishPhrasing.split_words(self.class.matcher_name)
+          desc << EnglishPhrasing.list(@expected) if defined?(@expected)
+          desc
         end
 
-        def failure_message_for_should_not
-          assert_ivars :@actual, :@expected
-          "expected #{@actual.inspect} not to #{name_to_sentence}#{expected_to_sentence}"
+        # @api private
+        # Matchers are not diffable by default. Override this to make your
+        # subclass diffable.
+        def diffable?
+          false
         end
 
-        def description
-          expected ? "#{name_to_sentence} #{@expected.inspect}" : name_to_sentence
+        # @api private
+        # Most matchers are value matchers (i.e. meant to work with `expect(value)`)
+        # rather than block matchers (i.e. meant to work with `expect { }`), so
+        # this defaults to false. Block matchers must override this to return true.
+        def supports_block_expectations?
+          false
         end
 
-        def diffable?
+        # @private
+        def supports_value_expectations?
+          true
+        end
+
+        # @api private
+        def expects_call_stack_jump?
           false
         end
 
-        def ==(other)
-          matches?(other)
+        # @private
+        def expected_formatted
+          RSpec::Support::ObjectFormatter.format(@expected)
         end
 
-        private
+        # @private
+        def actual_formatted
+          RSpec::Support::ObjectFormatter.format(@actual)
+        end
 
-        def assert_ivars *ivars
-          raise "#{self.class.name} needs to supply #{to_sentence ivars}" unless ivars.all? { |v| instance_variables.map(&:intern).include? v }
+        # @private
+        def self.matcher_name
+          @matcher_name ||= underscore(name.split('::').last)
+        end
+
+        # @private
+        def matcher_name
+          if defined?(@matcher_name)
+            @matcher_name
+          else
+            self.class.matcher_name
+          end
         end
+
+        # @private
+        # Borrowed from ActiveSupport.
+        def self.underscore(camel_cased_word)
+          word = camel_cased_word.to_s.dup
+          word.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+          word.tr!('-', '_')
+          word.downcase!
+          word
+        end
+        private_class_method :underscore
+
+      private
+
+        def assert_ivars(*expected_ivars)
+          return unless (expected_ivars - present_ivars).any?
+          ivar_list = EnglishPhrasing.list(expected_ivars)
+          raise "#{self.class.name} needs to supply#{ivar_list}"
+        end
+
+        if RUBY_VERSION.to_f < 1.9
+          # :nocov:
+          def present_ivars
+            instance_variables.map(&:to_sym)
+          end
+          # :nocov:
+        else
+          alias present_ivars instance_variables
+        end
+
+        # @private
+        module HashFormatting
+          # `{ :a => 5, :b => 2 }.inspect` produces:
+          #
+          #     {:a=>5, :b=>2}
+          #
+          # ...but it looks much better as:
+          #
+          #     {:a => 5, :b => 2}
+          #
+          # This is idempotent and safe to run on a string multiple times.
+          def improve_hash_formatting(inspect_string)
+            inspect_string.gsub(/(\S)=>(\S)/, '\1 => \2')
+          end
+          module_function :improve_hash_formatting
+        end
+
+        include HashFormatting
+
+        # @api private
+        # Provides default implementations of failure messages, based on the `description`.
+        module DefaultFailureMessages
+          # @api private
+          # Provides a good generic failure message. Based on `description`.
+          # When subclassing, if you are not satisfied with this failure message
+          # you often only need to override `description`.
+          # @return [String]
+          def failure_message
+            "expected #{description_of @actual} to #{description}".dup
+          end
+
+          # @api private
+          # Provides a good generic negative failure message. Based on `description`.
+          # When subclassing, if you are not satisfied with this failure message
+          # you often only need to override `description`.
+          # @return [String]
+          def failure_message_when_negated
+            "expected #{description_of @actual} not to #{description}".dup
+          end
+
+          # @private
+          def self.has_default_failure_messages?(matcher)
+            matcher.method(:failure_message).owner == self &&
+              matcher.method(:failure_message_when_negated).owner == self
+          rescue NameError
+            false
+          end
+        end
+
+        include DefaultFailureMessages
       end
     end
   end