rspec-expectations 2.14.0 → 3.13.0

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,185 @@ 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
+
+        # @private
+        module StringEncodingFormatting
+          # @api private
+          # @return [Boolean] True if the actual and expected string encoding are different.
+          #   i.e. the failure may be related to encoding differences and the encoding
+          #   should be shown to the user. false otherwise.
+          if String.method_defined?(:encoding)
+            def string_encoding_differs?
+              actual.is_a?(String) && expected.is_a?(String) && actual.encoding != expected.encoding
+            end
+          else
+            # @api private
+            # @return [Boolean] False always as the curent Ruby version does not support String encoding
+            def string_encoding_differs?
+              false
+            end
+          end
+          module_function :string_encoding_differs?
+
+          if String.method_defined?(:encoding)
+            # @api private
+            # Formats a String's encoding as a human readable string
+            # @param value [String]
+            # @return [String]
+            def format_encoding(value)
+              "#<Encoding:#{value.encoding.name}>"
+            end
+          else
+            # @api private
+            # Formats a String's encoding as a human readable string
+            # @param _value [String]
+            # @return [nil] nil as the curent Ruby version does not support String encoding
+            def format_encoding(_value)
+              nil
+            end
+          end
+          module_function :format_encoding
+        end
+
+        include StringEncodingFormatting
+
+        # @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

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

@@ -1,74 +1,78 @@
-require 'rspec/matchers/dsl'
-
 module RSpec
   module Matchers
     module BuiltIn
-      class BeTrue < BaseMatcher
-        def match(_, actual)
-          !!actual
+      # @api private
+      # Provides the implementation for `be_truthy`.
+      # Not intended to be instantiated directly.
+      class BeTruthy < BaseMatcher
+        # @api private
+        # @return [String]
+        def failure_message
+          "expected: truthy value\n     got: #{actual_formatted}"
         end
 
-        def failure_message_for_should
-          "expected: true value\n     got: #{actual.inspect}"
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          "expected: falsey value\n     got: #{actual_formatted}"
         end
 
-        def failure_message_for_should_not
-          "expected: non-true value\n     got: #{actual.inspect}"
-        end
-      end
+      private
 
-      class BeFalse < BaseMatcher
         def match(_, actual)
-          !actual
+          !!actual
         end
+      end
 
-        def failure_message_for_should
-          "expected: false value\n     got: #{actual.inspect}"
+      # @api private
+      # Provides the implementation for `be_falsey`.
+      # Not intended to be instantiated directly.
+      class BeFalsey < BaseMatcher
+        # @api private
+        # @return [String]
+        def failure_message
+          "expected: falsey value\n     got: #{actual_formatted}"
         end
 
-        def failure_message_for_should_not
-          "expected: non-false value\n     got: #{actual.inspect}"
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          "expected: truthy value\n     got: #{actual_formatted}"
         end
-      end
 
-      class BeNil < BaseMatcher
+      private
+
         def match(_, actual)
-          actual.nil?
+          !actual
         end
+      end
 
-        def failure_message_for_should
-          "expected: nil\n     got: #{actual.inspect}"
+      # @api private
+      # Provides the implementation for `be_nil`.
+      # Not intended to be instantiated directly.
+      class BeNil < BaseMatcher
+        # @api private
+        # @return [String]
+        def failure_message
+          "expected: nil\n     got: #{actual_formatted}"
         end
 
-        def failure_message_for_should_not
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
           "expected: not nil\n     got: nil"
         end
-      end
 
-      class Be < BaseMatcher
-        def initialize(*args, &block)
-          @args = args
-        end
+      private
 
         def match(_, actual)
-          !!actual
-        end
-
-        def failure_message_for_should
-          "expected #{@actual.inspect} to evaluate to true"
-        end
-
-        def failure_message_for_should_not
-          "expected #{@actual.inspect} to evaluate to false"
-        end
-
-        [:==, :<, :<=, :>=, :>, :===, :=~].each do |operator|
-          define_method operator do |operand|
-            BeComparedTo.new(operand, operator)
-          end
+          actual.nil?
         end
+      end
 
-        private
+      # @private
+      module BeHelpers
+      private
 
         def args_to_s
           @args.empty? ? "" : parenthesize(inspected_args.join(', '))
@@ -79,111 +83,107 @@ module RSpec
         end
 
         def inspected_args
-          @args.collect{|a| a.inspect}
+          @args.map { |a| RSpec::Support::ObjectFormatter.format(a) }
         end
 
         def expected_to_sentence
-          split_words(@expected)
+          EnglishPhrasing.split_words(@expected)
         end
 
         def args_to_sentence
-          to_sentence(@args)
+          EnglishPhrasing.list(@args)
         end
       end
 
-      class BeComparedTo < Be
-        def initialize(operand, operator)
-          @expected, @operator = operand, operator
-            @args = []
-        end
-
-        def matches?(actual)
-          @actual = actual
-          @actual.__send__ @operator, @expected
-        end
+      # @api private
+      # Provides the implementation for `be`.
+      # Not intended to be instantiated directly.
+      class Be < BaseMatcher
+        include BeHelpers
 
-        def failure_message_for_should
-          "expected: #{@operator} #{@expected.inspect}\n     got: #{@operator.to_s.gsub(/./, ' ')} #{@actual.inspect}"
+        def initialize(*args)
+          @args = args
         end
 
-        def failure_message_for_should_not
-          message = <<-MESSAGE
-`#{negative_expectation_expression}` not only FAILED,
-it is a bit confusing.
-          MESSAGE
-
-          raise message << ([:===,:==].include?(@operator) ?
-                            "It might be more clearly expressed without the \"be\"?" :
-                            "It might be more clearly expressed in the positive?")
+        # @api private
+        # @return [String]
+        def failure_message
+          "expected #{actual_formatted} to evaluate to true"
         end
 
-        def description
-          "be #{@operator} #{expected_to_sentence}#{args_to_sentence}"
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          "expected #{actual_formatted} to evaluate to false"
         end
 
-        def negative_expectation_expression
-          Expectations::Syntax.negative_expression("actual", "be #{@operator} #{@expected}")
-        end
-      end
-
-      class BePredicate < Be
-        def initialize(*args, &block)
-          @expected = parse_expected(args.shift)
-          @args = args
-          @block = block
+        [:==, :<, :<=, :>=, :>, :===, :=~].each do |operator|
+          define_method operator do |operand|
+            BeComparedTo.new(operand, operator)
+          end
         end
 
-        def matches?(actual)
-          @actual = actual
-          begin
-            return @result = actual.__send__(predicate, *@args, &@block)
-          rescue NameError => predicate_missing_error
-            "this needs to be here or rcov will not count this branch even though it's executed in a code example"
-          end
+      private
 
-          begin
-            return @result = actual.__send__(present_tense_predicate, *@args, &@block)
-          rescue NameError
-            raise predicate_missing_error
-          end
+        def match(_, actual)
+          !!actual
         end
+      end
 
-        alias === matches?
+      # @api private
+      # Provides the implementation of `be <operator> value`.
+      # Not intended to be instantiated directly.
+      class BeComparedTo < BaseMatcher
+        include BeHelpers
 
-        def failure_message_for_should
-          "expected #{predicate}#{args_to_s} to return true, got #{@result.inspect}"
+        def initialize(operand, operator)
+          @expected = operand
+          @operator = operator
+          @args = []
         end
 
-        def failure_message_for_should_not
-          "expected #{predicate}#{args_to_s} to return false, got #{@result.inspect}"
+        def matches?(actual)
+          perform_match(actual)
+        rescue ArgumentError, NoMethodError
+          false
         end
 
-        def description
-          "#{prefix_to_sentence}#{expected_to_sentence}#{args_to_sentence}"
+        def does_not_match?(actual)
+          !perform_match(actual)
+        rescue ArgumentError, NoMethodError
+          false
         end
 
-        private
-
-        def predicate
-          "#{@expected}?".to_sym
+        # @api private
+        # @return [String]
+        def failure_message
+          "expected: #{@operator} #{expected_formatted}\n" \
+          "     got: #{@operator.to_s.gsub(/./, ' ')} #{actual_formatted}"
         end
 
-        def present_tense_predicate
-          "#{@expected}s?".to_sym
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          message = "`expect(#{actual_formatted}).not_to " \
+                    "be #{@operator} #{expected_formatted}`"
+          if [:<, :>, :<=, :>=].include?(@operator)
+            message + " not only FAILED, it is a bit confusing."
+          else
+            message
+          end
         end
 
-        def parse_expected(expected)
-          @prefix, expected = prefix_and_expected(expected)
-          expected
+        # @api private
+        # @return [String]
+        def description
+          "be #{@operator} #{expected_to_sentence}#{args_to_sentence}"
         end
 
-        def prefix_and_expected(symbol)
-          symbol.to_s =~ /^(be_(an?_)?)(.*)/
-          return $1, $3
-        end
+      private
 
-        def prefix_to_sentence
-          split_words(@prefix)
+        def perform_match(actual)
+          @actual = actual
+          @actual.__send__ @operator, @expected
         end
       end
     end

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

@@ -0,0 +1,77 @@
+module RSpec
+  module Matchers
+    module BuiltIn
+      # @api private
+      # Provides the implementation for `be_between`.
+      # Not intended to be instantiated directly.
+      class BeBetween < BaseMatcher
+        def initialize(min, max)
+          @min, @max = min, max
+          inclusive
+        end
+
+        # @api public
+        # Makes the between comparison inclusive.
+        #
+        # @example
+        #   expect(3).to be_between(2, 3).inclusive
+        #
+        # @note The matcher is inclusive by default; this simply provides
+        #       a way to be more explicit about it.
+        def inclusive
+          @less_than_operator = :<=
+          @greater_than_operator = :>=
+          @mode = :inclusive
+          self
+        end
+
+        # @api public
+        # Makes the between comparison exclusive.
+        #
+        # @example
+        #   expect(3).to be_between(2, 4).exclusive
+        def exclusive
+          @less_than_operator = :<
+          @greater_than_operator = :>
+          @mode = :exclusive
+          self
+        end
+
+        # @api private
+        # @return [Boolean]
+        def matches?(actual)
+          @actual = actual
+          comparable? && compare
+        rescue ArgumentError
+          false
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message
+          "#{super}#{not_comparable_clause}"
+        end
+
+        # @api private
+        # @return [String]
+        def description
+          "be between #{description_of @min} and #{description_of @max} (#{@mode})"
+        end
+
+      private
+
+        def comparable?
+          @actual.respond_to?(@less_than_operator) && @actual.respond_to?(@greater_than_operator)
+        end
+
+        def not_comparable_clause
+          ", but it does not respond to `#{@less_than_operator}` and `#{@greater_than_operator}`" unless comparable?
+        end
+
+        def compare
+          @actual.__send__(@greater_than_operator, @min) && @actual.__send__(@less_than_operator, @max)
+        end
+      end
+    end
+  end
+end

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

@@ -1,14 +1,25 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `be_an_instance_of`.
+      # Not intended to be instantiated directly.
       class BeAnInstanceOf < BaseMatcher
-        def match(expected, actual)
-          actual.instance_of? expected
-        end
-
+        # @api private
+        # @return [String]
         def description
           "be an instance of #{expected}"
         end
+
+      private
+
+        def match(expected, actual)
+          actual.instance_of?(expected)
+        rescue NoMethodError
+          raise ::ArgumentError, "The #{matcher_name} matcher requires that " \
+                                 "the actual object responds to #instance_of? method " \
+                                 "but a `NoMethodError` was encountered instead."
+        end
       end
     end
   end

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

@@ -1,9 +1,18 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `be_a_kind_of`.
+      # Not intended to be instantiated directly.
       class BeAKindOf < BaseMatcher
+      private
+
         def match(expected, actual)
-          actual.kind_of? expected
+          actual.kind_of?(expected)
+        rescue NoMethodError
+          raise ::ArgumentError, "The #{matcher_name} matcher requires that " \
+                                 "the actual object responds to #kind_of? method " \
+                                 "but a `NoMethodError` was encountered instead."
         end
       end
     end