rspec-expectations 2.13.0 → 2.99.0

data/lib/rspec/matchers/be_close.rb

@@ -2,7 +2,10 @@ module RSpec
   module Matchers
     # @deprecated use +be_within+ instead.
     def be_close(expected, delta)
-      RSpec.deprecate("be_close(#{expected}, #{delta})", "be_within(#{delta}).of(#{expected})")
+      RSpec.deprecate("be_close(#{expected}, #{delta})",
+        :replacement => "be_within(#{delta}).of(#{expected})",
+        :type        => 'the be_close matcher'
+      )
       be_within(delta).of(expected)
     end
   end

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

@@ -13,11 +13,14 @@ module RSpec
       # class. If/when this changes, we will announce it and remove this warning.
       class BaseMatcher
         include RSpec::Matchers::Pretty
+        include RSpec::Matchers::MatchAliases
+
+        UNDEFINED = Object.new.freeze
 
         attr_reader :actual, :expected, :rescued_exception
 
-        def initialize(expected = nil)
-          @expected = expected
+        def initialize(expected = UNDEFINED)
+          @expected = expected unless UNDEFINED.equal?(expected)
         end
 
         def matches?(actual)
@@ -36,28 +39,32 @@ module RSpec
         end
 
         def failure_message_for_should
-          assert_ivars :@actual, :@expected
-          "expected #{@actual.inspect} to #{name_to_sentence}#{expected_to_sentence}"
+          assert_ivars :@actual
+          "expected #{@actual.inspect} to #{name_to_sentence}#{to_sentence expected}"
         end
 
         def failure_message_for_should_not
-          assert_ivars :@actual, :@expected
-          "expected #{@actual.inspect} not to #{name_to_sentence}#{expected_to_sentence}"
+          assert_ivars :@actual
+          "expected #{@actual.inspect} not to #{name_to_sentence}#{to_sentence expected}"
         end
 
         def description
-          expected ? "#{name_to_sentence} #{@expected.inspect}" : name_to_sentence
+          defined?(@expected) ? "#{name_to_sentence} #{@expected.inspect}" : name_to_sentence
         end
 
         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 *ivars
           raise "#{self.class.name} needs to supply #{to_sentence ivars}" unless ivars.all? { |v| instance_variables.map(&:intern).include? v }

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

@@ -3,31 +3,31 @@ require 'rspec/matchers/dsl'
 module RSpec
   module Matchers
     module BuiltIn
-      class BeTrue < BaseMatcher
+      class BeTruthy < BaseMatcher
         def match(_, actual)
           !!actual
         end
 
         def failure_message_for_should
-          "expected: true value\n     got: #{actual.inspect}"
+          "expected: truthy value\n     got: #{actual.inspect}"
         end
 
         def failure_message_for_should_not
-          "expected: non-true value\n     got: #{actual.inspect}"
+          "expected: falsey value\n     got: #{actual.inspect}"
         end
       end
 
-      class BeFalse < BaseMatcher
+      class BeFalsey < BaseMatcher
         def match(_, actual)
           !actual
         end
 
         def failure_message_for_should
-          "expected: false value\n     got: #{actual.inspect}"
+          "expected: falsey value\n     got: #{actual.inspect}"
         end
 
         def failure_message_for_should_not
-          "expected: non-false value\n     got: #{actual.inspect}"
+          "expected: truthy value\n     got: #{actual.inspect}"
         end
       end
 
@@ -45,7 +45,33 @@ module RSpec
         end
       end
 
+      module BeHelpers
+        private
+
+        def args_to_s
+          @args.empty? ? "" : parenthesize(inspected_args.join(', '))
+        end
+
+        def parenthesize(string)
+          "(#{string})"
+        end
+
+        def inspected_args
+          @args.collect{|a| a.inspect}
+        end
+
+        def expected_to_sentence
+          split_words(@expected)
+        end
+
+        def args_to_sentence
+          to_sentence(@args)
+        end
+      end
+
       class Be < BaseMatcher
+        include BeHelpers
+
         def initialize(*args, &block)
           @args = args
         end
@@ -67,28 +93,6 @@ module RSpec
             BeComparedTo.new(operand, operator)
           end
         end
-
-        private
-
-        def args_to_s
-          @args.empty? ? "" : parenthesize(inspected_args.join(', '))
-        end
-
-        def parenthesize(string)
-          "(#{string})"
-        end
-
-        def inspected_args
-          @args.collect{|a| a.inspect}
-        end
-
-        def expected_to_sentence
-          split_words(@expected)
-        end
-
-        def args_to_sentence
-          to_sentence(@args)
-        end
       end
 
       class BeComparedTo < Be
@@ -126,7 +130,9 @@ it is a bit confusing.
         end
       end
 
-      class BePredicate < Be
+      class BePredicate < BaseMatcher
+        include BeHelpers
+
         def initialize(*args, &block)
           @expected = parse_expected(args.shift)
           @args = args
@@ -135,19 +141,32 @@ it is a bit confusing.
 
         def matches?(actual)
           @actual = actual
+
+          if is_private_on?( @actual )
+            RSpec.deprecate "matching with be_#{predicate.to_s.gsub(/\?$/,'')} on private method #{predicate}",
+              :replacement => "`expect(object.send(#{predicate.inspect})).to be_true` or change the method's visibility to public",
+              :call_site => caller(0)[3]
+          end
+
           begin
-            return @result = actual.__send__(predicate, *@args, &@block)
+            @result = actual.__send__(predicate, *@args, &@block)
+            check_respond_to(predicate)
+            return @result
           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
 
           begin
-            return @result = actual.__send__(present_tense_predicate, *@args, &@block)
+            @result = actual.__send__(present_tense_predicate, *@args, &@block)
+            check_respond_to(present_tense_predicate)
+            return @result
           rescue NameError
             raise predicate_missing_error
           end
         end
 
+        alias === matches?
+
         def failure_message_for_should
           "expected #{predicate}#{args_to_s} to return true, got #{@result.inspect}"
         end
@@ -160,7 +179,18 @@ it is a bit confusing.
           "#{prefix_to_sentence}#{expected_to_sentence}#{args_to_sentence}"
         end
 
-        private
+      private
+
+        # support 1.8.7
+        if String === methods.first
+          def is_private_on? actual
+            actual.private_methods.include? predicate.to_s
+          end
+        else
+          def is_private_on? actual
+            actual.private_methods.include? predicate
+          end
+        end
 
         def predicate
           "#{@expected}?".to_sym
@@ -183,6 +213,13 @@ it is a bit confusing.
         def prefix_to_sentence
           split_words(@prefix)
         end
+
+        def check_respond_to(method)
+          RSpec.deprecate(
+            "Matching with #{@prefix}#{@expected} on an object that doesn't respond to `#{method}`",
+            :replacement => "`respond_to_missing?` or `respond_to?` on your object"
+          ) unless actual.respond_to?(method)
+        end
       end
     end
   end

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

@@ -2,6 +2,8 @@ module RSpec
   module Matchers
     module BuiltIn
       class BeWithin
+        include MatchAliases
+
         def initialize(delta)
           @delta = delta
         end
@@ -12,7 +14,6 @@ module RSpec
           raise needs_subtractable unless @actual.respond_to? :-
           (@actual - @expected).abs <= @tolerance
         end
-        alias == matches?
 
         def of(expected)
           @expected  = expected
@@ -23,7 +24,7 @@ module RSpec
 
         def percent_of(expected)
           @expected  = expected
-          @tolerance = @delta * @expected / 100
+          @tolerance = @delta * @expected.abs / 100.0
           @unit      = '%'
           self
         end
@@ -40,7 +41,12 @@ module RSpec
           "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 `-`"

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

@@ -2,6 +2,8 @@ module RSpec
   module Matchers
     module BuiltIn
       class Change
+        include MatchAliases
+
         def initialize(receiver=nil, message=nil, &block)
           @message = message
           @value_proc = block || lambda {receiver.__send__(message)}
@@ -18,7 +20,39 @@ module RSpec
 
           (!change_expected? || changed?) && matches_before? && matches_after? && matches_expected_delta? && matches_min? && matches_max?
         end
-        alias == matches?
+
+        def does_not_match?(event_proc, &block)
+          expression = if @expected_delta
+            "by()"
+          elsif @minimum
+            "by_at_least()"
+          elsif @maximum
+            "by_at_most()"
+          elsif @eval_after
+            "to()"
+          end
+
+          if expression
+            RSpec.deprecate("`expect { }.not_to change { }.#{expression}`")
+          end
+
+          matched_positively = matches?(event_proc, &block)
+
+          unless matches_before?
+            RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''))
+              |The semantics of `expect { }.not_to change { }.from()` are changing
+              |in RSpec 3. In RSpec 2.x, this would pass if the value changed but
+              |the starting value was not what you specified with `from()`. In
+              |RSpec 3, this will only pass if the starting value matches your
+              |`from()` value _and_ it has not changed.
+              |
+              |You have an expectation that relies upon the old RSpec 2.x semantics
+              |at: #{CallerFilter.first_non_rspec_line}"
+            EOS
+          end
+
+          !matched_positively
+        end
 
         def raise_block_syntax_error
           raise SyntaxError.new(<<-MESSAGE)
@@ -39,7 +73,7 @@ MESSAGE
           if @eval_before && !expected_matches_actual?(@expected_before, @actual_before)
             "#{message} should have initially been #{@expected_before.inspect}, but was #{@actual_before.inspect}"
           elsif @eval_after && !expected_matches_actual?(@expected_after, @actual_after)
-            "#{message} should have been changed to #{@expected_after.inspect}, but is now #{@actual_after.inspect}"
+            "#{message} should have been changed to #{failure_message_for_expected_after}, but is now #{@actual_after.inspect}"
           elsif @expected_delta
             "#{message} should have been changed by #{@expected_delta.inspect}, but was changed by #{actual_delta.inspect}"
           elsif @minimum
@@ -90,8 +124,20 @@ MESSAGE
           "change ##{message}"
         end
 
+        def supports_block_expectations?
+          true
+        end
+
         private
 
+        def failure_message_for_expected_after
+          if RSpec::Matchers.is_a_matcher?(@expected_after)
+            @expected_after.description
+          else
+            @expected_after.inspect
+          end
+        end
+
         def message
           @message || "result"
         end
@@ -125,7 +171,7 @@ MESSAGE
         end
 
         def expected_matches_actual?(expected, actual)
-          expected === actual
+          expected === actual || actual == expected
         end
       end
     end

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

@@ -2,31 +2,57 @@ module RSpec
   module Matchers
     module BuiltIn
       class Has
+        include MatchAliases
+
         def initialize(expected, *args)
           @expected, @args = expected, args
         end
 
         def matches?(actual)
-          actual.__send__(predicate(@expected), *@args)
+          method = predicate
+
+          if is_private_on?(actual)
+            RSpec.deprecate "matching with #{@expected} on private method #{predicate}",
+              :replacement => "`expect(object.send(#{predicate.inspect})).to be_true` or change the method's visibility to public"
+          end
+
+          result = actual.__send__(method, *@args)
+          check_respond_to(actual, method)
+          result
         end
-        alias == matches?
 
         def failure_message_for_should
-          "expected ##{predicate(@expected)}#{failure_message_args_description} to return true, got false"
+          "expected ##{predicate}#{failure_message_args_description} to return true, got false"
         end
 
         def failure_message_for_should_not
-          "expected ##{predicate(@expected)}#{failure_message_args_description} to return false, got true"
+          "expected ##{predicate}#{failure_message_args_description} to return false, got true"
         end
 
         def description
           [method_description(@expected), args_description].compact.join(' ')
         end
 
-        private
+        # @private
+        def supports_block_expectations?
+          false
+        end
+
+      private
 
-        def predicate(sym)
-          "#{sym.to_s.sub("have_","has_")}?".to_sym
+        # support 1.8.7
+        if String === methods.first
+          def is_private_on? actual
+            actual.private_methods.include? predicate.to_s
+          end
+        else
+          def is_private_on? actual
+            actual.private_methods.include? predicate
+          end
+        end
+
+        def predicate
+          "#{@expected.to_s.sub("have_","has_")}?".to_sym
         end
 
         def method_description(method)
@@ -42,6 +68,13 @@ module RSpec
           desc = args_description
           "(#{desc})" if desc
         end
+
+        def check_respond_to(actual, method)
+          RSpec.deprecate(
+            "Matching with #{@expected} on an object that doesn't respond to `#{method}`",
+            :replacement => "`respond_to_missing?` or `respond_to?` on your object"
+          ) unless actual.respond_to?(method)
+        end
       end
     end
   end

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

@@ -2,6 +2,10 @@ module RSpec
   module Matchers
     module BuiltIn
       class Have
+        include MatchAliases
+
+        QUERY_METHODS = [:size, :length, :count].freeze
+
         def initialize(expected, relativity=:exactly)
           @expected = case expected
                       when :no then 0
@@ -9,7 +13,11 @@ module RSpec
                       else expected
                       end
           @relativity = relativity
+
           @actual = @collection_name = @plural_collection_name = nil
+          @target_owns_a_collection = false
+          @negative_expectation = false
+          @expectation_format_method = "to"
         end
 
         def relativities
@@ -22,21 +30,45 @@ module RSpec
 
         def matches?(collection_or_owner)
           collection = determine_collection(collection_or_owner)
-          query_method = determine_query_method(collection)
-          raise not_a_collection unless query_method
-          @actual = collection.__send__(query_method)
+          case collection
+          when enumerator_class
+            for query_method in QUERY_METHODS
+              next unless collection.respond_to?(query_method)
+              @actual = collection.__send__(query_method)
+
+              if @actual
+                print_deprecation_message(query_method)
+                break
+              end
+            end
+
+            raise not_a_collection if @actual.nil?
+          else
+            query_method = determine_query_method(collection)
+            raise not_a_collection unless query_method
+            @actual = collection.__send__(query_method)
+
+            print_deprecation_message(query_method)
+          end
           case @relativity
           when :at_least then @actual >= @expected
           when :at_most  then @actual <= @expected
           else                @actual == @expected
           end
         end
-        alias == matches?
+
+        def does_not_match?(collection_or_owner)
+          @negative_expectation = true
+          @expectation_format_method = "to_not"
+          !matches?(collection_or_owner)
+        end
 
         def determine_collection(collection_or_owner)
           if collection_or_owner.respond_to?(@collection_name)
+            @target_owns_a_collection = true
             collection_or_owner.__send__(@collection_name, *@args, &@block)
           elsif (@plural_collection_name && collection_or_owner.respond_to?(@plural_collection_name))
+            @target_owns_a_collection = true
             collection_or_owner.__send__(@plural_collection_name, *@args, &@block)
           elsif determine_query_method(collection_or_owner)
             collection_or_owner
@@ -46,7 +78,7 @@ module RSpec
         end
 
         def determine_query_method(collection)
-          [:size, :length, :count].detect {|m| collection.respond_to?(m)}
+          QUERY_METHODS.detect {|m| collection.respond_to?(m)}
         end
 
         def not_a_collection
@@ -102,6 +134,139 @@ EOF
         def relative_expectation
           "#{relativities[@relativity]}#{@expected}"
         end
+
+        def enumerator_class
+          RUBY_VERSION < '1.9' ? Enumerable::Enumerator : Enumerator
+        end
+
+        def print_deprecation_message(query_method)
+          deprecation_message = "the rspec-collection_matchers gem "
+          deprecation_message << "or replace your expectation with something like "
+          if for_rspec_rails_error_on?
+            # It is supposed to be safe to be able to convert the args array to
+            # a string. This is because the `errors_on` method only takes two
+            # valid arguments: attribute name (symbol/string) and a hash
+            deprecated_call = expectation_expression(query_method, "record")
+            deprecated_call << "(#{errors_on_args_list})" unless @args.empty?
+
+            deprecation_message << <<-EOS.gsub(/^\s+\|/, '')
+              |
+              |
+              |    #{record_valid_expression}
+              |    expect(#{record_errors_expression(query_method)}).#{expectation_format_method} #{suggested_matcher_expression}
+              |
+            EOS
+          else
+            deprecated_call = expectation_expression(query_method)
+            deprecation_message << "`expect(#{cardinality_expression(query_method)}).#{expectation_format_method} #{suggested_matcher_expression}`"
+          end
+
+          RSpec.deprecate("`#{deprecated_call}`",
+            :replacement => deprecation_message,
+            :type        => "the have matcher"
+          )
+        end
+
+        def expectation_expression(query_method, target = nil)
+          target ||= target_expression
+          if @negative_expectation
+            RSpec::Expectations::Syntax.negative_expression(target, original_matcher_expression)
+          else
+            RSpec::Expectations::Syntax.positive_expression(target, original_matcher_expression)
+          end
+        end
+
+        def target_expression
+          if @target_owns_a_collection
+            'collection_owner'
+          else
+            'collection'
+          end
+        end
+
+        def original_matcher_expression
+          "#{matcher_method}(#{@expected}).#{@collection_name}"
+        end
+
+        def expectation_format_method
+          if @relativity == :exactly
+            @expectation_format_method
+          else
+            "to"
+          end
+        end
+
+        def cardinality_expression(query_method)
+          expression = "#{target_expression}."
+          expression << "#{@collection_name}." if @target_owns_a_collection
+          expression << String(query_method)
+        end
+
+        def suggested_matcher_expression
+          send("suggested_matcher_expression_for_#{@relativity}")
+        end
+
+        def suggested_matcher_expression_for_exactly
+          "eq(#{@expected})"
+        end
+
+        def suggested_matcher_expression_for_at_most
+          if @negative_expectation
+            "be > #{@expected}"
+          else
+            "be <= #{@expected}"
+          end
+        end
+
+        def suggested_matcher_expression_for_at_least
+          if @negative_expectation
+            "be < #{@expected}"
+          else
+            "be >= #{@expected}"
+          end
+        end
+
+        def matcher_method
+          case @relativity
+          when :exactly
+            "have"
+          when :at_most
+            "have_at_most"
+          when :at_least
+            "have_at_least"
+          end
+        end
+
+        # RSpec Rails `errors_on` specific helpers
+        def for_rspec_rails_error_on?
+          defined?(RSpec::Rails) &&
+            /\.errors?_on\b/ =~ original_matcher_expression
+        end
+
+        def errors_on_args_list
+          list = @args.first.inspect
+          context = validation_context
+          list << ", :context => #{context}" if context
+          list
+        end
+
+        def record_valid_expression
+          expression = "record.valid?"
+          if on_context = validation_context
+            expression << "(#{on_context})"
+          end
+          expression
+        end
+
+        def validation_context
+          return unless Hash === @args.last
+          @args.last[:context].inspect
+        end
+
+        def record_errors_expression(query_method)
+          attribute = (@args.first || :attr)
+          "record.errors[#{attribute.inspect}].#{String(query_method)}"
+        end
       end
     end
   end