rspec-expectations 2.13.0 → 3.0.0

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

@@ -4,7 +4,7 @@ module RSpec
       # @api private
       #
       # Used _internally_ as a base class for matchers that ship with
-      # rspec-expectations.
+      # rspec-expectations and rspec-rails.
       #
       # ### Warning:
       #
@@ -13,18 +13,35 @@ module RSpec
       # 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
+        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,32 +52,63 @@ 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
+        # 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
+          assert_ivars :@actual
+          "expected #{@actual.inspect} to #{description}"
         end
 
-        def failure_message_for_should_not
-          assert_ivars :@actual, :@expected
-          "expected #{@actual.inspect} not to #{name_to_sentence}#{expected_to_sentence}"
+        # @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
+          assert_ivars :@actual
+          "expected #{@actual.inspect} not to #{description}"
         end
 
+        # @api private
+        # Generates a "pretty" description using the logic in {Pretty}.
+        # @return [String]
         def description
-          expected ? "#{name_to_sentence} #{@expected.inspect}" : name_to_sentence
+          return name_to_sentence unless defined?(@expected)
+          "#{name_to_sentence}#{to_sentence @expected}"
         end
 
+        # @api private
+        # Matchers are not diffable by default. Override this to make your
+        # subclass diffable.
         def diffable?
           false
         end
 
-        def ==(other)
-          matches?(other)
+        # @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
 
-        private
+      private
+
+        def assert_ivars(*expected_ivars)
+          if (expected_ivars - present_ivars).any?
+            raise "#{self.class.name} needs to supply#{to_sentence expected_ivars}"
+          end
+        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 }
+        if RUBY_VERSION.to_f < 1.9
+          def present_ivars
+            instance_variables.map { |v| v.to_sym }
+          end
+        else
+          alias present_ivars instance_variables
         end
       end
     end

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

@@ -1,73 +1,80 @@
-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.inspect}"
         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.inspect}"
         end
 
-        def failure_message_for_should_not
-          "expected: non-true value\n     got: #{actual.inspect}"
+      private
+
+        def match(_, actual)
+          !!actual
         end
       end
 
-      class BeFalse < BaseMatcher
-        def match(_, actual)
-          !actual
+      # @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.inspect}"
         end
 
-        def failure_message_for_should
-          "expected: false value\n     got: #{actual.inspect}"
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          "expected: truthy value\n     got: #{actual.inspect}"
         end
 
-        def failure_message_for_should_not
-          "expected: non-false value\n     got: #{actual.inspect}"
+      private
+
+        def match(_, actual)
+          !actual
         end
       end
 
+      # @api private
+      # Provides the implementation for `be_nil`.
+      # Not intended to be instantiated directly.
       class BeNil < BaseMatcher
-        def match(_, actual)
-          actual.nil?
-        end
 
-        def failure_message_for_should
+        # @api private
+        # @return [String]
+        def failure_message
           "expected: nil\n     got: #{actual.inspect}"
         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
+      module BeHelpers
         private
 
         def args_to_s
@@ -91,10 +98,50 @@ module RSpec
         end
       end
 
-      class BeComparedTo < Be
+      # @api private
+      # Provides the implementation for `be`.
+      # Not intended to be instantiated directly.
+      class Be < BaseMatcher
+        include BeHelpers
+
+        def initialize(*args, &block)
+          @args = args
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message
+          "expected #{@actual.inspect} to evaluate to true"
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          "expected #{@actual.inspect} to evaluate to false"
+        end
+
+        [:==, :<, :<=, :>=, :>, :===, :=~].each do |operator|
+          define_method operator do |operand|
+            BeComparedTo.new(operand, operator)
+          end
+        end
+
+      private
+
+        def match(_, actual)
+          !!actual
+        end
+      end
+
+      # @api private
+      # Provides the implementation of `be <operator> value`.
+      # Not intended to be instantiated directly.
+      class BeComparedTo < BaseMatcher
+        include BeHelpers
+
         def initialize(operand, operator)
           @expected, @operator = operand, operator
-            @args = []
+          @args = []
         end
 
         def matches?(actual)
@@ -102,72 +149,104 @@ module RSpec
           @actual.__send__ @operator, @expected
         end
 
-        def failure_message_for_should
+        # @api private
+        # @return [String]
+        def failure_message
           "expected: #{@operator} #{@expected.inspect}\n     got: #{@operator.to_s.gsub(/./, ' ')} #{@actual.inspect}"
         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_when_negated
+          message = "`expect(#{@actual.inspect}).not_to be #{@operator} #{@expected.inspect}`"
+          if [:<, :>, :<=, :>=].include?(@operator)
+            message + " not only FAILED, it is a bit confusing."
+          else
+            message
+          end
         end
 
+        # @api private
+        # @return [String]
         def description
           "be #{@operator} #{expected_to_sentence}#{args_to_sentence}"
         end
-
-        def negative_expectation_expression
-          Expectations::Syntax.negative_expression("actual", "be #{@operator} #{@expected}")
-        end
       end
 
-      class BePredicate < Be
+      # @api private
+      # Provides the implementation of `be_<predicate>`.
+      # Not intended to be instantiated directly.
+      class BePredicate < BaseMatcher
+        include BeHelpers
+
         def initialize(*args, &block)
           @expected = parse_expected(args.shift)
           @args = args
           @block = block
         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
+        def matches?(actual, &block)
+          @actual  = actual
+          @block ||= block
+          predicate_accessible? && predicate_matches?
+        end
 
-          begin
-            return @result = actual.__send__(present_tense_predicate, *@args, &@block)
-          rescue NameError
-            raise predicate_missing_error
-          end
+        def does_not_match?(actual, &block)
+          @actual  = actual
+          @block ||= block
+          predicate_accessible? && !predicate_matches?
         end
 
-        def failure_message_for_should
-          "expected #{predicate}#{args_to_s} to return true, got #{@result.inspect}"
+        # @api private
+        # @return [String]
+        def failure_message
+          failure_message_expecting(true)
         end
 
-        def failure_message_for_should_not
-          "expected #{predicate}#{args_to_s} to return false, got #{@result.inspect}"
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          failure_message_expecting(false)
         end
 
+        # @api private
+        # @return [String]
         def description
           "#{prefix_to_sentence}#{expected_to_sentence}#{args_to_sentence}"
         end
 
-        private
+      private
+
+        def predicate_accessible?
+          !private_predicate? && predicate_exists?
+        end
+
+        # support 1.8.7, evaluate once at load time for performance
+        if String === methods.first
+          def private_predicate?
+            @actual.private_methods.include? predicate.to_s
+          end
+        else
+          def private_predicate?
+            @actual.private_methods.include? predicate
+          end
+        end
+
+        def predicate_exists?
+          actual.respond_to?(predicate) || actual.respond_to?(present_tense_predicate)
+        end
+
+        def predicate_matches?
+          method_name = actual.respond_to?(predicate) ? predicate : present_tense_predicate
+          @predicate_matches = actual.__send__(method_name, *@args, &@block)
+        end
 
         def predicate
-          "#{@expected}?".to_sym
+          :"#{@expected}?"
         end
 
         def present_tense_predicate
-          "#{@expected}s?".to_sym
+          :"#{@expected}s?"
         end
 
         def parse_expected(expected)
@@ -176,13 +255,25 @@ it is a bit confusing.
         end
 
         def prefix_and_expected(symbol)
-          symbol.to_s =~ /^(be_(an?_)?)(.*)/
-          return $1, $3
+          Matchers::BE_PREDICATE_REGEX.match(symbol.to_s).captures.compact
         end
 
         def prefix_to_sentence
           split_words(@prefix)
         end
+
+        def failure_message_expecting(value)
+          validity_message ||
+            "expected `#{@actual.inspect}.#{predicate}#{args_to_s}` to return #{value}, got #{@predicate_matches.inspect}"
+        end
+
+        def validity_message
+          if private_predicate?
+            "expected #{@actual} to respond to `#{predicate}` but `#{predicate}` is a private method"
+          elsif !predicate_exists?
+            "expected #{@actual} to respond to `#{predicate}`"
+          end
+        end
       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 #{@min.inspect} and #{@max.inspect} (#{@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,22 @@
 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
+        end
       end
     end
   end

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

@@ -1,7 +1,12 @@
 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
         end

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

@@ -1,19 +1,18 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `be_within`.
+      # Not intended to be instantiated directly.
       class BeWithin
+        include Composable
+
         def initialize(delta)
           @delta = delta
         end
 
-        def matches?(actual)
-          @actual = actual
-          raise needs_expected     unless defined? @expected
-          raise needs_subtractable unless @actual.respond_to? :-
-          (@actual - @expected).abs <= @tolerance
-        end
-        alias == matches?
-
+        # @api public
+        # Sets the expected value.
         def of(expected)
           @expected  = expected
           @tolerance = @delta
@@ -21,34 +20,59 @@ module RSpec
           self
         end
 
+        # @api public
+        # Sets the expected value, and makes the matcher do
+        # a percent comparison.
         def percent_of(expected)
           @expected  = expected
-          @tolerance = @delta * @expected / 100
+          @tolerance = @delta * @expected.abs / 100.0
           @unit      = '%'
           self
         end
 
-        def failure_message_for_should
-          "expected #{@actual} to #{description}"
+        # @private
+        def matches?(actual)
+          @actual = actual
+          raise needs_expected unless defined? @expected
+          numeric? && (@actual - @expected).abs <= @tolerance
         end
 
-        def failure_message_for_should_not
-          "expected #{@actual} not to #{description}"
+        # @api private
+        # @return [String]
+        def failure_message
+          "expected #{@actual.inspect} to #{description}#{not_numeric_clause}"
         end
 
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          "expected #{@actual.inspect} not to #{description}"
+        end
+
+        # @api private
+        # @return [String]
         def description
           "be within #{@delta}#{@unit} of #{@expected}"
         end
 
-        private
+        # @private
+        def supports_block_expectations?
+          false
+        end
+
+      private
 
-        def needs_subtractable
-          ArgumentError.new "The actual value (#{@actual.inspect}) must respond to `-`"
+        def numeric?
+          @actual.respond_to?(:-)
         end
 
         def needs_expected
           ArgumentError.new "You must set an expected value using #of: be_within(#{@delta}).of(expected_value)"
         end
+
+        def not_numeric_clause
+          ", but it could not be treated as a numeric value" unless numeric?
+        end
       end
     end
   end