rspec-expectations 2.14.0 → 3.13.0

data/lib/rspec/matchers/generated_descriptions.rb

@@ -1,30 +1,36 @@
 module RSpec
   module Matchers
     class << self
-      attr_accessor :last_matcher, :last_should
+      # @private
+      attr_accessor :last_matcher, :last_expectation_handler
     end
 
+    # @api private
+    # Used by rspec-core to clear the state used to generate
+    # descriptions after an example.
     def self.clear_generated_description
       self.last_matcher = nil
-      self.last_should = nil
+      self.last_expectation_handler = nil
     end
 
+    # @api private
+    # Generates an an example description based on the last expectation.
+    # Used by rspec-core's one-liner syntax.
     def self.generated_description
-      return nil if last_should.nil?
-      "#{last_should.to_s.gsub('_',' ')} #{last_description}"
+      return nil if last_expectation_handler.nil?
+      "#{last_expectation_handler.verb} #{last_description}"
     end
 
-  private
-
+    # @private
     def self.last_description
       last_matcher.respond_to?(:description) ? last_matcher.description : <<-MESSAGE
 When you call a matcher in an example without a String, like this:
 
-specify { object.should matcher }
+specify { expect(object).to matcher }
 
 or this:
 
-it { should matcher }
+it { is_expected.to matcher }
 
 RSpec expects the matcher to have a #description method. You should either
 add a String to the example this matcher is being used in, or give it a

data/lib/rspec/matchers/matcher_delegator.rb

@@ -0,0 +1,61 @@
+module RSpec
+  module Matchers
+    # Provides a base class with as little methods as possible, so that
+    # most methods can be delegated via `method_missing`.
+    #
+    # On Ruby 2.0+ BasicObject could be used for this purpose, but it
+    # introduce some extra complexity with constant resolution, so the
+    # BlankSlate pattern was prefered.
+    # @private
+    class BaseDelegator
+      kept_methods = [
+        # Methods that raise warnings if removed.
+        :__id__, :__send__, :object_id,
+
+        # Methods that are explicitly undefined in some subclasses.
+        :==, :===,
+
+        # Methods we keep on purpose.
+        :class, :respond_to?, :__method__, :method, :dup,
+        :clone, :initialize_dup, :initialize_copy, :initialize_clone,
+      ]
+      instance_methods.each do |method|
+        unless kept_methods.include?(method.to_sym)
+          undef_method(method)
+        end
+      end
+    end
+
+    # Provides the necessary plumbing to wrap a matcher with a decorator.
+    # @private
+    class MatcherDelegator < BaseDelegator
+      include Composable
+      attr_reader :base_matcher
+
+      def initialize(base_matcher)
+        @base_matcher = base_matcher
+      end
+
+      def method_missing(*args, &block)
+        base_matcher.__send__(*args, &block)
+      end
+
+      if ::RUBY_VERSION.to_f > 1.8
+        def respond_to_missing?(name, include_all=false)
+          super || base_matcher.respond_to?(name, include_all)
+        end
+      else
+        # :nocov:
+        def respond_to?(name, include_all=false)
+          super || base_matcher.respond_to?(name, include_all)
+        end
+        # :nocov:
+      end
+
+      def initialize_copy(other)
+        @base_matcher = @base_matcher.clone
+        super
+      end
+    end
+  end
+end

data/lib/rspec/matchers/matcher_protocol.rb

@@ -0,0 +1,105 @@
+module RSpec
+  module Matchers
+    # rspec-expectations can work with any matcher object that implements this protocol.
+    #
+    # @note This class is not loaded at runtime by rspec-expectations. It exists
+    #   purely to provide documentation for the matcher protocol.
+    class MatcherProtocol
+      # @!group Required Methods
+
+      # @!method matches?(actual)
+      #   @param actual [Object] The object being matched against.
+      #   @yield For an expression like `expect(x).to matcher do...end`, the `do/end`
+      #     block binds to `to`. It passes that block, if there is one, on to this method.
+      #   @return [Boolean] true if this matcher matches the provided object.
+
+      # @!method failure_message
+      #   This will only be called if {#matches?} returns false.
+      #   @return [String] Explanation for the failure.
+
+      # @!endgroup
+
+      # @!group Optional Methods
+
+      # @!method does_not_match?(actual)
+      #   In a negative expectation such as `expect(x).not_to foo`, RSpec will
+      #   call `foo.does_not_match?(x)` if this method is defined. If it's not
+      #   defined it will fall back to using `!foo.matches?(x)`. This allows you
+      #   to provide custom logic for the negative case.
+      #
+      #   @param actual [Object] The object being matched against.
+      #   @yield For an expression like `expect(x).not_to matcher do...end`, the `do/end`
+      #     block binds to `not_to`. It passes that block, if there is one, on to this method.
+      #   @return [Boolean] true if this matcher does not match the provided object.
+
+      # @!method failure_message_when_negated
+      #   This will only be called when a negative match fails.
+      #   @return [String] Explanation for the failure.
+      #   @note This method is listed as optional because matchers do not have to
+      #     support negation. But if your matcher does support negation, this is a
+      #     required method -- otherwise, you'll get a `NoMethodError`.
+
+      # @!method description
+      #   The description is used for two things:
+      #
+      #     * When using RSpec's one-liner syntax
+      #       (e.g. `it { is_expected.to matcher }`), the description
+      #       is used to generate the example's doc string since you
+      #       have not provided one.
+      #     * In a composed matcher expression, the description is used
+      #       as part of the failure message (and description) of the outer
+      #       matcher.
+      #
+      #   @return [String] Description of the matcher.
+
+      # @!method supports_block_expectations?
+      #   Indicates that this matcher can be used in a block expectation expression,
+      #   such as `expect { foo }.to raise_error`. Generally speaking, this is
+      #   only needed for matchers which operate on a side effect of a block, rather
+      #   than on a particular object.
+      #   @return [Boolean] true if this matcher can be used in block expressions.
+      #   @note If not defined, RSpec assumes a value of `false` for this method.
+
+      # @!method supports_value_expectations?
+      #   Indicates that this matcher can be used in a value expectation expression,
+      #   such as `expect(foo).to eq(bar)`.
+      #   @return [Boolean] true if this matcher can be used in value expressions.
+      #   @note If not defined, RSpec assumes a value of `true` for this method.
+
+      # @!method expects_call_stack_jump?
+      #   Indicates that when this matcher is used in a block expectation
+      #   expression, it expects the block to use a ruby construct that causes
+      #   a call stack jump (such as raising an error or throwing a symbol).
+      #
+      #   This is used internally for compound block expressions, as matchers
+      #   which expect call stack jumps must be treated with care to work properly.
+      #
+      #   @return [Boolean] true if the matcher expects a call stack jump
+      #
+      #   @note This method is very rarely used or needed.
+      #   @note If not defined, RSpec assumes a value of `false` for this method.
+
+      # @!method diffable?
+      #   @return [Boolean] true if `actual` and `expected` can be diffed.
+      #   Indicates that this matcher provides `actual` and `expected` attributes,
+      #   and that the values returned by these can be usefully diffed, which can
+      #   be included in the output.
+
+      # @!method actual
+      #   @return [String, Object] If an object (rather than a string) is provided,
+      #     RSpec will use the `pp` library to convert it to multi-line output in
+      #     order to diff.
+      #   The actual value for the purposes of a diff.
+      #   @note This method is required if `diffable?` returns true.
+
+      # @!method expected
+      #   @return [String, Object] If an object (rather than a string) is provided,
+      #     RSpec will use the `pp` library to convert it to multi-line output in
+      #     order to diff.
+      #   The expected value for the purposes of a diff.
+      #   @note This method is required if `diffable?` returns true.
+
+      # @!endgroup
+    end
+  end
+end

data/lib/rspec/matchers/multi_matcher_diff.rb

@@ -0,0 +1,82 @@
+module RSpec
+  module Matchers
+    # @api private
+    # Handles list of expected and actual value pairs when there is a need
+    # to render multiple diffs. Also can handle one pair.
+    class MultiMatcherDiff
+      # @private
+      # Default diff label when there is only one matcher in diff
+      # output
+      DEFAULT_DIFF_LABEL = "Diff:".freeze
+
+      # @private
+      # Maximum readable matcher description length
+      DESCRIPTION_MAX_LENGTH = 65
+
+      def initialize(expected_list)
+        @expected_list = expected_list
+      end
+
+      # @api private
+      # Wraps provided expected value in instance of
+      # MultiMatcherDiff. If provided value is already an
+      # MultiMatcherDiff then it just returns it.
+      # @param [Any] expected value to be wrapped
+      # @param [Any] actual value
+      # @return [RSpec::Matchers::MultiMatcherDiff]
+      def self.from(expected, actual)
+        return expected if self === expected
+        new([[expected, DEFAULT_DIFF_LABEL, actual]])
+      end
+
+      # @api private
+      # Wraps provided matcher list in instance of
+      # MultiMatcherDiff.
+      # @param [Array<Any>] matchers list of matchers to wrap
+      # @return [RSpec::Matchers::MultiMatcherDiff]
+      def self.for_many_matchers(matchers)
+        new(matchers.map { |m| [m.expected, diff_label_for(m), m.actual] })
+      end
+
+      # @api private
+      # Returns message with diff(s) appended for provided differ
+      # factory and actual value if there are any
+      # @param [String] message original failure message
+      # @param [Proc] differ
+      # @return [String]
+      def message_with_diff(message, differ)
+        diff = diffs(differ)
+        message = "#{message}\n#{diff}" unless diff.empty?
+        message
+      end
+
+    private
+
+      class << self
+        private
+
+        def diff_label_for(matcher)
+          "Diff for (#{truncated(RSpec::Support::ObjectFormatter.format(matcher))}):"
+        end
+
+        def truncated(description)
+          return description if description.length <= DESCRIPTION_MAX_LENGTH
+          description[0...DESCRIPTION_MAX_LENGTH - 3] << "..."
+        end
+      end
+
+      def diffs(differ)
+        @expected_list.map do |(expected, diff_label, actual)|
+          diff = differ.diff(actual, expected)
+          next if diff.strip.empty?
+          if diff == "\e[0m\n\e[0m"
+            "#{diff_label}\n" \
+              "  <The diff is empty, are your objects producing identical `#inspect` output?>"
+          else
+            "#{diff_label}#{diff}"
+          end
+        end.compact.join("\n")
+      end
+    end
+  end
+end