rspec-expectations 2.14.5 → 2.99.0

data/lib/rspec/matchers/matcher.rb

@@ -1,4 +1,5 @@
 require 'set'
+require 'rspec/matchers/differentiate_block_method_types'
 
 module RSpec
   module Matchers
@@ -10,8 +11,7 @@ module RSpec
         include RSpec::Matchers::Pretty
         include RSpec::Matchers
 
-        attr_reader :expected, :actual, :rescued_exception
-        attr_accessor :matcher_execution_context
+        attr_reader :actual, :rescued_exception
 
         # @api private
         def initialize(name, &declarations)
@@ -19,17 +19,50 @@ module RSpec
           @declarations = declarations
           @actual       = nil
           @diffable     = false
+          @supports_block_expectations = false
           @expected_exception, @rescued_exception = nil, nil
           @match_for_should_not_block = nil
           @messages = {}
+          @define_block_executed = false
+          @block_method_differentiator = nil
+          @deprecated_methods = Set.new
+          @matcher_execution_context = nil
         end
 
         PERSISTENT_INSTANCE_VARIABLES = [
           :@name, :@declarations, :@diffable,
+          :@supports_block_expectations,
           :@match_block, :@match_for_should_not_block,
           :@expected_exception
         ].to_set
 
+        def expected
+          if @expected.size == 1
+            RSpec.warn_deprecation(
+              "Custom matchers in 3.x will set expected to be a single value "+
+              "(when provided as such) rather than an array. This may change "+
+              "the behaviour of your matcher.\n"+
+              "To continue to access this as an array use `expected_array`\n"+
+              "Called from: #{ RSpec::CallerFilter.first_non_rspec_line }\n\n"
+            )
+          end
+          @expected
+        end
+
+        def expected_as_array
+          @expected
+        end
+
+        def matcher_execution_context=(value)
+          RSpec.deprecate("`matcher_execution_context=` on custom matchers")
+          @matcher_execution_context = value
+        end
+
+        def matcher_execution_context
+          RSpec.deprecate("`matcher_execution_context` on custom matchers")
+          @matcher_execution_context
+        end
+
         # @api private
         def for_expected(*expected)
           @expected = expected
@@ -38,9 +71,14 @@ module RSpec
               instance_variable_set(ivar, nil) unless (PERSISTENT_INSTANCE_VARIABLES + [:@expected]).include?(ivar)
             end
             @messages = {}
+            @deprecated_methods = Set.new
+
+            @block_method_differentiator = DifferentiateBlockMethodTypes.new(*@expected, &@declarations)
             making_declared_methods_public do
               instance_eval_with_args(*@expected, &@declarations)
             end
+
+            @define_block_executed = true
             self
           end
         end
@@ -183,6 +221,10 @@ module RSpec
           @diffable = true
         end
 
+        def supports_block_expectations
+          @supports_block_expectations = true
+        end
+
         # Convenience for defining methods on this matcher to create a fluent
         # interface. The trick about fluent interfaces is that each method must
         # return self in order to chain methods together. `chain` handles that
@@ -214,6 +256,11 @@ module RSpec
           @diffable
         end
 
+        # @api private
+        def supports_block_expectations?
+          @supports_block_expectations
+        end
+
         # @api private
         # Used internally by +should_not+
         def does_not_match?(actual)
@@ -224,21 +271,51 @@ module RSpec
         end
 
         def respond_to?(method, include_private=false)
-          super || matcher_execution_context.respond_to?(method, include_private)
+          super || @matcher_execution_context.respond_to?(method, include_private)
         end
 
         private
 
         def method_missing(method, *args, &block)
-          if matcher_execution_context.respond_to?(method)
-            matcher_execution_context.__send__ method, *args, &block
+          if @matcher_execution_context.respond_to?(method)
+            @matcher_execution_context.__send__ method, *args, &block
           else
             super(method, *args, &block)
           end
         end
 
-        def include(*args)
-          singleton_class.__send__(:include, *args)
+        def include(*modules)
+          return_value = singleton_class.__send__(:include, *modules)
+
+          modules.each do |mod|
+            mod.instance_methods.each do |name|
+              add_deprecation_warning_to(name,
+                "Calling a helper method (`#{name}`) from a module included in a custom matcher as a macro",
+                "`extend #{mod.name || "TheModule"}`",
+                "included in the custom matcher",
+                :unless
+              )
+            end
+          end
+
+          return_value
+        end
+
+        def extend(*modules)
+          return_value = super
+
+          modules.each do |mod|
+            mod.instance_methods.each do |name|
+              add_deprecation_warning_to(name,
+                "Calling a helper method (`#{name}`) from a module extended onto a custom matcher",
+                "`include #{mod.name || "TheModule"}`",
+                "extended onto the custom matcher",
+                :if
+              )
+            end
+          end unless @define_block_executed
+
+          return_value
         end
 
         def define_method(name, &block)
@@ -278,15 +355,15 @@ module RSpec
         end
 
         def default_description
-          "#{name_to_sentence}#{expected_to_sentence}"
+          "#{name_to_sentence}#{to_sentence expected_as_array}"
         end
 
         def default_failure_message_for_should
-          "expected #{actual.inspect} to #{name_to_sentence}#{expected_to_sentence}"
+          "expected #{actual.inspect} to #{name_to_sentence}#{to_sentence expected_as_array}"
         end
 
         def default_failure_message_for_should_not
-          "expected #{actual.inspect} not to #{name_to_sentence}#{expected_to_sentence}"
+          "expected #{actual.inspect} not to #{name_to_sentence}#{to_sentence expected_as_array}"
         end
 
         unless method_defined?(:singleton_class)
@@ -294,6 +371,50 @@ module RSpec
             class << self; self; end
           end
         end
+
+        def singleton_method_added(name)
+          return unless @block_method_differentiator
+
+          if @block_method_differentiator.instance_methods.include?(name)
+            add_deprecation_warning_to(name,
+              "Calling a helper method (`#{name}`) defined as an instance method (using `def #{name}`) as a macro from a custom matcher `define` block",
+              "`def self.#{name}` (to define it as a singleton method)",
+              "defined in the custom matcher definition block",
+              :unless
+            )
+          elsif @block_method_differentiator.singleton_methods.include?(name)
+            add_deprecation_warning_to(name,
+              "Calling a helper method (`#{name}`) defined as a singleton method (using `def self.#{name}`) on a custom matcher",
+              "`def #{name}` (to define it as an instance method)",
+              "defined in the custom matcher definition block",
+              :if
+            )
+          end
+        end
+
+        def add_deprecation_warning_to(method_name, msg, replacement, extra_call_site_msg, condition)
+          return if @deprecated_methods.include?(method_name)
+          @deprecated_methods << method_name
+
+          aliased_name = aliased_name_for(method_name)
+          singleton_class.__send__(:alias_method, aliased_name, method_name)
+
+          singleton_class.class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+            def #{method_name}(*a, &b)
+              ::RSpec.deprecate(#{msg.inspect},
+                :replacement => #{replacement.inspect},
+                :call_site => CallerFilter.first_non_rspec_line + " and #{extra_call_site_msg} at #{CallerFilter.first_non_rspec_line}"
+              ) #{condition} @define_block_executed
+
+              __send__(#{aliased_name.inspect}, *a, &b)
+            end
+          EOS
+        end
+
+        def aliased_name_for(method_name)
+          target, punctuation = method_name.to_s.sub(/([?!=])$/, ''), $1
+          "#{target}_without_rspec_deprecation_warning#{punctuation}"
+        end
       end
     end
   end

data/lib/rspec/matchers/operator_matcher.rb

@@ -1,95 +1,95 @@
 module RSpec
   module Matchers
-    class OperatorMatcher
-      class << self
-        def registry
-          @registry ||= {}
-        end
+    module BuiltIn
+      class OperatorMatcher
+        class << self
+          def registry
+            @registry ||= {}
+          end
 
-        def register(klass, operator, matcher)
-          registry[klass] ||= {}
-          registry[klass][operator] = matcher
-        end
+          def register(klass, operator, matcher)
+            registry[klass] ||= {}
+            registry[klass][operator] = matcher
+          end
 
-        def unregister(klass, operator)
-          registry[klass] && registry[klass].delete(operator)
-        end
+          def unregister(klass, operator)
+            registry[klass] && registry[klass].delete(operator)
+          end
 
-        def get(klass, operator)
-          klass.ancestors.each { |ancestor|
-            matcher = registry[ancestor] && registry[ancestor][operator]
-            return matcher if matcher
-          }
+          def get(klass, operator)
+            klass.ancestors.each { |ancestor|
+              matcher = registry[ancestor] && registry[ancestor][operator]
+              return matcher if matcher
+            }
 
-          nil
+            nil
+          end
         end
-      end
 
-      def initialize(actual)
-        @actual = actual
-      end
+        def initialize(actual)
+          @actual = actual
+        end
 
-      def self.use_custom_matcher_or_delegate(operator)
-        define_method(operator) do |expected|
-          if uses_generic_implementation_of?(operator) && matcher = OperatorMatcher.get(@actual.class, operator)
-            @actual.__send__(::RSpec::Matchers.last_should, matcher.new(expected))
-          else
-            eval_match(@actual, operator, expected)
+        def self.use_custom_matcher_or_delegate(operator)
+          define_method(operator) do |expected|
+            if uses_generic_implementation_of?(operator) && matcher = OperatorMatcher.get(@actual.class, operator)
+              @actual.__send__(::RSpec::Matchers.last_should, matcher.new(expected))
+            else
+              eval_match(@actual, operator, expected)
+            end
           end
-        end
 
-        negative_operator = operator.sub(/^=/, '!')
-        if negative_operator != operator && respond_to?(negative_operator)
-          define_method(negative_operator) do |expected|
-            opposite_should = ::RSpec::Matchers.last_should == :should ? :should_not : :should
-            raise "RSpec does not support `#{::RSpec::Matchers.last_should} #{negative_operator} expected`.  " +
-              "Use `#{opposite_should} #{operator} expected` instead."
+          negative_operator = operator.sub(/^=/, '!')
+          if negative_operator != operator && respond_to?(negative_operator)
+            define_method(negative_operator) do |expected|
+              opposite_should = ::RSpec::Matchers.last_should == :should ? :should_not : :should
+              raise "RSpec does not support `#{::RSpec::Matchers.last_should} #{negative_operator} expected`.  " +
+                "Use `#{opposite_should} #{operator} expected` instead."
+            end
           end
         end
-      end
 
-      ['==', '===', '=~', '>', '>=', '<', '<='].each do |operator|
-        use_custom_matcher_or_delegate operator
-      end
+        ['==', '===', '=~', '>', '>=', '<', '<='].each do |operator|
+          use_custom_matcher_or_delegate operator
+        end
 
-      def fail_with_message(message)
-        RSpec::Expectations.fail_with(message, @expected, @actual)
-      end
+        def fail_with_message(message)
+          RSpec::Expectations.fail_with(message, @expected, @actual)
+        end
 
-      def description
-        "#{@operator} #{@expected.inspect}"
-      end
+        def description
+          "#{@operator} #{@expected.inspect}"
+        end
 
-    private
+      private
 
-      if Method.method_defined?(:owner) # 1.8.6 lacks Method#owner :-(
-        def uses_generic_implementation_of?(op)
-          Expectations.method_handle_for(@actual, op).owner == ::Kernel
-        rescue NameError
-          false
-        end
-      else
-        def uses_generic_implementation_of?(op)
-          # This is a bit of a hack, but:
-          #
-          # {}.method(:=~).to_s # => "#<Method: Hash(Kernel)#=~>"
-          #
-          # In the absence of Method#owner, this is the best we
-          # can do to see if the method comes from Kernel.
-          Expectations.method_handle_for(@actual, op).to_s.include?('(Kernel)')
-        rescue NameError
-          false
+        if Method.method_defined?(:owner) # 1.8.6 lacks Method#owner :-(
+          def uses_generic_implementation_of?(op)
+            Expectations.method_handle_for(@actual, op).owner == ::Kernel
+          rescue NameError
+            false
+          end
+        else
+          def uses_generic_implementation_of?(op)
+            # This is a bit of a hack, but:
+            #
+            # {}.method(:=~).to_s # => "#<Method: Hash(Kernel)#=~>"
+            #
+            # In the absence of Method#owner, this is the best we
+            # can do to see if the method comes from Kernel.
+            Expectations.method_handle_for(@actual, op).to_s.include?('(Kernel)')
+          rescue NameError
+            false
+          end
         end
-      end
 
-      def eval_match(actual, operator, expected)
-        ::RSpec::Matchers.last_matcher = self
-        @operator, @expected = operator, expected
-        __delegate_operator(actual, operator, expected)
+        def eval_match(actual, operator, expected)
+          ::RSpec::Matchers.last_matcher = self
+          @operator, @expected = operator, expected
+          __delegate_operator(actual, operator, expected)
+        end
       end
-    end
 
-    module BuiltIn
       class PositiveOperatorMatcher < OperatorMatcher
         def __delegate_operator(actual, operator, expected)
           if actual.__send__(operator, expected)

data/lib/rspec/matchers/pretty.rb

@@ -21,6 +21,8 @@ module RSpec
       end
 
       def _pretty_print(array)
+        RSpec.deprecate("`RSpec::Matchers::Pretty#_pretty_print`",
+                        :replacement => "`RSpec::Matchers::Pretty#to_sentence`")
         result = ""
         array.each_with_index do |item, index|
           if index < (array.length - 2)
@@ -43,6 +45,8 @@ module RSpec
       end
 
       def expected_to_sentence
+        RSpec.deprecate("`RSpec::Matchers::Pretty#expected_to_sentence`",
+                        :replacement => "`RSpec::Matchers::Pretty#to_sentence(expected)`")
         to_sentence(@expected) if defined?(@expected)
       end
 

data/lib/rspec/matchers/test_unit_integration.rb

@@ -3,9 +3,26 @@
 # and a 1.9 bug can lead to infinite recursion from the `super` call in our
 # method_missing hook.  See this gist for more info:
 # https://gist.github.com/845896
-if defined?(MiniTest::Unit::TestCase)
-  MiniTest::Unit::TestCase.send(:include, RSpec::Matchers)
-end
-if defined?(Test::Unit::TestCase)
-  Test::Unit::TestCase.send(:include, RSpec::Matchers)
+if defined?(MiniTest::TestCase)
+  MiniTest::TestCase.add_setup_hook do |instance|
+    unless ::RSpec::Matchers === instance
+      ::RSpec.deprecate("rspec-expectations' built-in integration with minitest < 5.x",
+                        :replacement => "`include RSpec::Matchers` from within `Minitest::TestCase`")
+
+      MiniTest::TestCase.send(:include, RSpec::Matchers)
+    end
+  end
+elsif defined?(Test::Unit::TestCase)
+  Test::Unit::TestCase.class_eval do
+    def setup
+      unless ::RSpec::Matchers === self
+        ::RSpec.deprecate("rspec-expectations' built-in integration with Test::Unit",
+                          :replacement => "`include RSpec::Matchers` from within `Test::Unit::TestCase`")
+
+        Test::Unit::TestCase.send(:include, RSpec::Matchers)
+      end
+
+      super if defined?(super)
+    end
+  end
 end

data/lib/rspec/matchers.rb

@@ -1,6 +1,7 @@
 require 'rspec/matchers/extensions/instance_eval_with_args'
 require 'rspec/matchers/pretty'
 
+require 'rspec/matchers/match_aliases'
 require 'rspec/matchers/built_in'
 require 'rspec/matchers/matcher'
 require 'rspec/matchers/operator_matcher'
@@ -24,6 +25,7 @@ module RSpec
   #     does_not_match?(actual)
   #     failure_message_for_should_not
   #     description
+  #     supports_block_expectations?
   #
   # ## Predicates
   #
@@ -183,24 +185,42 @@ module RSpec
       obj.respond_to?(:failure_message_for_should) || obj.respond_to?(:failure_message)
     end
 
-    # Passes if actual is truthy (anything but false or nil)
     def be_true
-      BuiltIn::BeTrue.new
+      RSpec.deprecate("`be_true`", :replacement =>
+        "`be_truthy` (for Ruby's conditional semantics) or " +
+        "`be true` (for exact `== true` equality)"
+      )
+      BuiltIn::BeTruthy.new
     end
 
-    # Passes if actual is falsy (false or nil)
     def be_false
-      BuiltIn::BeFalse.new
+      RSpec.deprecate("`be_false`", :replacement =>
+        "`be_falsey` (for Ruby's conditional semantics) or " +
+        "`be false` (for exact `== false` equality)"
+      )
+      BuiltIn::BeFalsey.new
+    end
+
+    # Passes if actual is truthy (anything but false or nil)
+    def be_truthy
+      BuiltIn::BeTruthy.new
     end
 
+    # Passes if actual is falsy (false or nil)
+    def be_falsey
+      BuiltIn::BeFalsey.new
+    end
+
+    alias_method :be_falsy, :be_falsey
+
     # Passes if actual is nil
     def be_nil
       BuiltIn::BeNil.new
     end
 
     # @example
-    #   expect(actual).to     be_true
-    #   expect(actual).to     be_false
+    #   expect(actual).to     be_truthy
+    #   expect(actual).to     be_falsey
     #   expect(actual).to     be_nil
     #   expect(actual).to     be_[arbitrary_predicate](*args)
     #   expect(actual).not_to be_nil
@@ -689,6 +709,20 @@ module RSpec
       BuiltIn::MatchArray.new(array)
     end
 
-    OperatorMatcher.register(Enumerable, '=~', BuiltIn::MatchArray)
+    BuiltIn::OperatorMatcher.register(Enumerable, '=~', BuiltIn::MatchArray)
+
+    def self.const_missing(name)
+      case name
+        when :OperatorMatcher
+          RSpec.deprecate("`RSpec::Matchers::OperatorMatcher`",
+                          :replacement => "`RSpec::Matchers::BuiltIn::OperatorMatcher`")
+          BuiltIn::OperatorMatcher
+        when :Configuration
+          RSpec.deprecate("`RSpec::Matchers::Configuration`",
+                          :replacement => "`RSpec::Expectations::Configuration`")
+          Expectations::Configuration
+        else super
+      end
+    end
   end
 end

data/lib/rspec-expectations.rb

@@ -1 +1,6 @@
 require "rspec/expectations"
+
+RSpec.deprecate("`require 'rspec-expectations'`",
+                :replacement => "`require 'rspec/expectations'`",
+                # we explcitly pass a caller because CallerFilter ignores this file
+                :call_site => caller[RUBY_PLATFORM == 'java' ? 2 : 0])

data/spec/rspec/{matchers → expectations}/configuration_spec.rb

@@ -2,10 +2,10 @@ require 'spec_helper'
 require 'delegate'
 
 module RSpec
-  module Matchers
+  module Expectations
     describe "RSpec::Matchers.configuration" do
       it 'returns a memoized configuration instance' do
-        expect(RSpec::Matchers.configuration).to be_a(RSpec::Matchers::Configuration)
+        expect(RSpec::Matchers.configuration).to be_a(RSpec::Expectations::Configuration)
         expect(RSpec::Matchers.configuration).to be(RSpec::Matchers.configuration)
       end
     end
@@ -13,6 +13,25 @@ module RSpec
     describe Configuration do
       let(:config) { Configuration.new }
 
+      context "when accessing it using the old 2.x const name" do
+        it 'returns the new constant' do
+          allow_deprecation
+          expect(RSpec::Matchers::Configuration).to be(RSpec::Expectations::Configuration)
+        end
+
+        it 'issues a deprecation warning' do
+          expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /RSpec::Matchers::Configuration/)
+          RSpec::Matchers::Configuration
+        end
+
+        it 'allows other undefined constant to raise errors like normal' do
+          expect_no_deprecation
+          expect {
+            RSpec::Matchers::FooBarBazz
+          }.to raise_error(NameError, /RSpec::Matchers::FooBarBazz/)
+        end
+      end
+
       describe "#backtrace_formatter" do
         let(:original_backtrace) { %w[ clean-me/a.rb other/file.rb clean-me/b.rb ] }
         let(:cleaned_backtrace)  { %w[ other/file.rb ] }

data/spec/rspec/expectations/expectation_target_spec.rb

@@ -22,6 +22,12 @@ module RSpec
           }.to raise_error(ArgumentError)
         end
 
+        it 'raises a wrong number of args ArgumentError when given two args' do
+          expect {
+            expect(1, 2)
+          }.to raise_error(ArgumentError, /wrong number of arg/)
+        end
+
         it 'raises an ArgumentError when given neither an argument nor a block' do
           expect {
             expect
@@ -76,6 +82,62 @@ module RSpec
           }.to raise_error(ArgumentError)
         end
       end
+
+      context "when passed a block" do
+        it 'can be used with a block matcher' do
+          expect { }.not_to raise_error
+        end
+
+        context 'when passed a value matcher' do
+          it 'issues a warning to instruct the user to use a value expression or fix the matcher (for `to`)' do
+            expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /block expectation/)
+            expect { }.to be_an(Object)
+          end
+
+          it 'issues a warning to instruct the user to use a value expression or fix the matcher (for `not_to`)' do
+            expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /block expectation/)
+            expect { }.not_to be_an(String)
+          end
+
+          it 'issues a warning to instruct the user to use a value expression or fix the matcher (for `to_not`)' do
+            expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /block expectation/)
+            expect { }.to_not be_an(String)
+          end
+
+          it 'assumes a custom matcher that does not define `supports_block_expectations?` is not a block matcher (since it is relatively rare)' do
+            custom_matcher = Module.new do
+              def self.matches?(value); true; end
+              def self.description; "foo"; end
+            end
+
+            expect_deprecation_with_call_site(__FILE__, __LINE__ + 2, /block expectation/)
+            expect(3).to custom_matcher # to show the custom matcher can be used as a matcher
+            expect { 3 }.to custom_matcher
+          end
+
+          it "uses the matcher's `description` in the warning" do
+            custom_matcher = Module.new do
+              def self.matches?(value); true; end
+              def self.description; "matcher-description"; end
+            end
+
+            expect_deprecation_with_replacement(/\(matcher-description\)/)
+            expect { }.to custom_matcher
+          end
+
+          context 'when the matcher does not define `description` (since it is an optional part of the protocol)' do
+            it 'uses `inspect` in the warning instead' do
+              custom_matcher = Module.new do
+                def self.matches?(value); true; end
+                def self.inspect; "matcher-inspect"; end
+              end
+
+              expect_deprecation_with_replacement(/\(matcher-inspect\)/)
+              expect { }.to custom_matcher
+            end
+          end
+        end
+      end
     end
   end
 end

data/spec/rspec/expectations/extensions/kernel_spec.rb

@@ -32,6 +32,10 @@ describe Object, "#should" do
           true
         end
 
+        def respond_to?(name, include_all=false)
+          super || name == :proxied? || @target.respond_to?(name, include_all)
+        end
+
         def method_missing(name, *args)
           @target.send(name, *args)
         end

data/spec/rspec/expectations/handler_spec.rb

@@ -140,7 +140,7 @@ module RSpec
           actual = Object.new
           matcher.should_receive(:matches?).with(actual).and_return(false)
           matcher.stub(:negative_failure_message).and_return("ignore")
-          expect(RSpec::Expectations::NegativeExpectationHandler.handle_matcher(actual, matcher)).to be_false
+          expect(RSpec::Expectations::NegativeExpectationHandler.handle_matcher(actual, matcher)).to be_falsey
         end