rspec-expectations 2.13.0 → 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,97 +1,101 @@
 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
 
-      if Method.method_defined?(:owner) # 1.8.6 lacks Method#owner :-(
-        def uses_generic_implementation_of?(op)
-          @actual.method(op).owner == ::Kernel
-        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.
-          @actual.method(op).to_s.include?('(Kernel)')
+        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)
             true
           elsif ['==','===', '=~'].include?(operator)
-            fail_with_message("expected: #{expected.inspect}\n     got: #{actual.inspect} (using #{operator})") 
+            fail_with_message("expected: #{expected.inspect}\n     got: #{actual.inspect} (using #{operator})")
           else
             fail_with_message("expected: #{operator} #{expected.inspect}\n     got: #{operator.gsub(/./, ' ')} #{actual.inspect}")
           end

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)
@@ -35,7 +37,7 @@ module RSpec
       end
 
       def to_word(item)
-        item.respond_to?(:description) ? item.description : item.inspect
+        is_matcher_with_description?(item) ? item.description : item.inspect
       end
 
       def name_to_sentence
@@ -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
 
@@ -59,6 +63,12 @@ module RSpec
         word.downcase!
         word
       end
+
+      private
+
+      def is_matcher_with_description?(object)
+        RSpec::Matchers.is_a_matcher?(object) && object.respond_to?(:description)
+      end
     end
   end
 end

data/lib/rspec/matchers/test_unit_integration.rb

@@ -0,0 +1,28 @@
+# Include Matchers for other test frameworks.  Note that MiniTest _must_
+# come before TU because on ruby 1.9, T::U::TC is a subclass of MT::U::TC
+# 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::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