rspec-expectations 2.14.5 → 2.99.0.beta1

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

@@ -11,7 +11,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
@@ -29,13 +33,20 @@ module RSpec
             for query_method in QUERY_METHODS
               next unless collection.respond_to?(query_method)
               @actual = collection.__send__(query_method)
-              break unless @actual.nil?
+
+              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
@@ -45,10 +56,18 @@ module RSpec
         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
@@ -118,6 +137,83 @@ EOF
         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 "
+          deprecation_message << "`expect(#{cardinality_expression(query_method)}).#{expectation_format_method} #{suggested_matcher_expression}`"
+
+          RSpec.deprecate("`#{expectation_expression(query_method)}`", :replacement => deprecation_message)
+        end
+
+        def expectation_expression(query_method)
+          if @negative_expectation
+            RSpec::Expectations::Syntax.negative_expression(target_expression, original_matcher_expression)
+          else
+            RSpec::Expectations::Syntax.positive_expression(target_expression, 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
       end
     end
   end

data/lib/rspec/matchers/differentiate_block_method_types.rb

@@ -0,0 +1,55 @@
+module RSpec
+  module Matchers
+    # Evaluates a block in order to determine what methods, if any,
+    # it defines as instance methods (using `def foo`) vs singleton
+    # methods (using `def self.foo`).
+    #
+    # @api private
+    class DifferentiateBlockMethodTypes
+      def initialize(*block_args, &block)
+        @block_args = block_args
+        @block = block
+
+        ignore_macro_methods
+
+        capture_added_methods(singletons_singleton_class, singleton_methods)
+        capture_added_methods(singleton_class, instance_methods)
+
+        singleton_class.class_exec(*block_args, &block)
+      end
+
+      def singleton_methods
+        @singleton_methods ||= []
+      end
+
+      def instance_methods
+        @instance_methods ||= []
+      end
+
+    private
+
+      def capture_added_methods(object, method_list)
+        object.__send__(:define_method, :singleton_method_added) do |method_name|
+          method_list << method_name
+        end
+
+        method_list.delete(:singleton_method_added)
+      end
+
+      unless method_defined?(:singleton_class)
+        def singleton_class
+          class << self; self; end
+        end
+      end
+
+      def singletons_singleton_class
+        class << singleton_class; self; end
+      end
+
+      def ignore_macro_methods
+        def singleton_class.method_missing(*); self; end
+      end
+    end
+  end
+end
+

data/lib/rspec/matchers/matcher.rb

@@ -1,4 +1,5 @@
 require 'set'
+require 'rspec/matchers/differentiate_block_method_types'
 
 module RSpec
   module Matchers
@@ -22,6 +23,9 @@ module RSpec
           @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
         end
 
         PERSISTENT_INSTANCE_VARIABLES = [
@@ -38,9 +42,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
@@ -237,8 +246,38 @@ module RSpec
           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)
@@ -294,6 +333,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/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
 
 

data/spec/rspec/expectations/syntax_spec.rb

@@ -91,8 +91,8 @@ module RSpec
 
         context "when only :expect is enabled" do
           before do
-            expect(Syntax.should_enabled?).to be_false
-            expect(Syntax.expect_enabled?).to be_true
+            expect(Syntax.should_enabled?).to be_falsey
+            expect(Syntax.expect_enabled?).to be_truthy
           end
 
           it 'generates a positive expression using the expect syntax' do
@@ -106,8 +106,8 @@ module RSpec
 
         context "when both :should and :expect are enabled", :uses_should do
           before do
-            expect(Syntax.should_enabled?).to be_true
-            expect(Syntax.expect_enabled?).to be_true
+            expect(Syntax.should_enabled?).to be_truthy
+            expect(Syntax.expect_enabled?).to be_truthy
           end
 
           it 'generates a positive expression using the expect syntax' do
@@ -121,8 +121,8 @@ module RSpec
 
         context "when only :should is enabled", :uses_only_should do
           before do
-            Syntax.should_enabled?.should be_true
-            Syntax.expect_enabled?.should be_false
+            Syntax.should_enabled?.should be_truthy
+            Syntax.expect_enabled?.should be_falsey
           end
 
           it 'generates a positive expression using the expect syntax' do

data/spec/rspec/expectations_spec.rb

@@ -1,5 +1,19 @@
 module RSpec
   describe Expectations do
+    def file_contents_for(lib, filename)
+      # http://rubular.com/r/HYpUMftlG2
+      path = $LOAD_PATH.find { |p| p.match(/\/rspec-#{lib}(-[a-f0-9]+)?\/lib/) }
+      file = File.join(path, filename)
+      File.read(file)
+    end
+
+    it 'has an up-to-date caller_filter file' do
+      expectations = file_contents_for("expectations", "rspec/expectations/caller_filter.rb")
+      core         = file_contents_for("core",         "rspec/core/caller_filter.rb")
+
+      expect(expectations).to eq(core)
+    end
+
     describe '.method_handle_for(object, method_name)' do
 
       class UntamperedClass

data/spec/rspec/matchers/base_matcher_spec.rb

@@ -8,21 +8,21 @@ module RSpec::Matchers::BuiltIn
       end
 
       it "returns true if there are no errors" do
-        expect(matcher.match_unless_raises {}).to be_true
+        expect(matcher.match_unless_raises {}).to be_truthy
       end
 
       it "returns false if there is an error" do
-        expect(matcher.match_unless_raises { raise }).to be_false
+        expect(matcher.match_unless_raises { raise }).to be_falsey
       end
 
       it "returns false if the only submitted error is raised" do
-        expect(matcher.match_unless_raises(RuntimeError){ raise "foo" }).to be_false
+        expect(matcher.match_unless_raises(RuntimeError){ raise "foo" }).to be_falsey
       end
 
       it "returns false if any of several errors submitted is raised" do
-        expect(matcher.match_unless_raises(RuntimeError, ArgumentError, NameError) { raise "foo" }).to be_false
-        expect(matcher.match_unless_raises(RuntimeError, ArgumentError, NameError) { raise ArgumentError.new('') }).to be_false
-        expect(matcher.match_unless_raises(RuntimeError, ArgumentError, NameError) { raise NameError.new('') }).to be_false
+        expect(matcher.match_unless_raises(RuntimeError, ArgumentError, NameError) { raise "foo" }).to be_falsey
+        expect(matcher.match_unless_raises(RuntimeError, ArgumentError, NameError) { raise ArgumentError.new('') }).to be_falsey
+        expect(matcher.match_unless_raises(RuntimeError, ArgumentError, NameError) { raise NameError.new('') }).to be_falsey
       end
 
       it "re-raises any error other than one of those specified" do
@@ -39,27 +39,6 @@ module RSpec::Matchers::BuiltIn
 
     end
 
-    describe "#failure_message_for_should" do
-      context "when the parameter to .new is omitted" do
-        it "describes what was expected" do
-          matcher_class = Class.new(BaseMatcher) do
-            def name=(name)
-              @name = name
-            end
-
-            def match(expected, actual)
-              false
-            end
-          end
-
-          matcher = matcher_class.new
-          matcher.name = "be something"
-          matcher.matches?("foo")
-          expect(matcher.failure_message_for_should).to eq('expected "foo" to be something')
-        end
-      end
-    end
-
     describe "#==" do
       it "responds the same way as matches?" do
         matcher = Class.new(BaseMatcher) do
@@ -72,10 +51,10 @@ module RSpec::Matchers::BuiltIn
           end
         end
 
-        expect(matcher.new(3).matches?(3)).to be_true
+        expect(matcher.new(3).matches?(3)).to be_truthy
         expect(matcher.new(3)).to eq(3)
 
-        expect(matcher.new(3).matches?(4)).to be_false
+        expect(matcher.new(3).matches?(4)).to be_falsey
         expect(matcher.new(3)).not_to eq(4)
       end
     end

data/spec/rspec/matchers/be_spec.rb

@@ -31,6 +31,21 @@ describe "expect(...).to be_predicate" do
     }.to raise_error(NameError, /happy\?/)
   end
 
+  it 'warns of deprecation when :predicate? is private' do
+    privately_happy = Class.new do
+      private
+        def happy?
+          true
+        end
+    end
+    expect(RSpec).to receive(:deprecate).with(
+      "matching with be_happy on private method happy?",
+      :replacement => "`expect(object.send(:happy?)).to be_true` or change the method's visibility to public",
+      :call_site => RSpec::Mocks::ArgumentMatchers::RegexpMatcher.new(/#{__FILE__}:#{__LINE__ + 2}/)
+    )
+    expect(privately_happy.new).to be_happy
+  end
+
   it "fails on error other than NameError" do
     actual = double("actual")
     actual.should_receive(:foo?).and_raise("aaaah")
@@ -50,7 +65,7 @@ describe "expect(...).to be_predicate" do
   it "does not support operator chaining like a basic `be` matcher does" do
     matcher = be_happy
     value = double(:happy? => false)
-    expect(be_happy == value).to be false
+    expect(matcher == value).to be false
   end
 end
 
@@ -231,35 +246,94 @@ describe "expect(...).not_to be_predicate(*args, &block)" do
   end
 end
 
-describe "expect(...).to be_true" do
+describe "expect(...).to be_truthy" do
   it "passes when actual equal?(true)" do
-    expect(true).to be_true
+    expect(true).to be_truthy
   end
 
   it "passes when actual is 1" do
-    expect(1).to be_true
+    expect(1).to be_truthy
   end
 
   it "fails when actual equal?(false)" do
     expect {
-      expect(false).to be_true
-    }.to fail_with("expected: true value\n     got: false")
+      expect(false).to be_truthy
+    }.to fail_with("expected: truthy value\n     got: false")
   end
 end
 
 describe "expect(...).to be_false" do
-  it "passes when actual equal?(false)" do
+  it "is deprecated" do
+    expect(RSpec).to receive(:deprecate).with(/be_false/, :replacement => match(/falsey.*false/))
+    expect(false).to be_false
+  end
+
+  it "has the correct call site in the deprecation message" do
+    expect_deprecation_with_call_site(__FILE__, __LINE__ + 1)
     expect(false).to be_false
   end
 
+  it "still passes" do
+    allow(RSpec).to receive(:deprecate)
+    expect(false).to be_false
+  end
+
+  it "still fails" do
+    allow(RSpec).to receive(:deprecate)
+    expect {
+      expect(true).to be_false
+    }.to fail_with(/expected: falsey value/)
+  end
+end
+
+describe "expect(...).to be_true" do
+  it "is deprecated" do
+    expect(RSpec).to receive(:deprecate).with(/be_true/, :replacement => match(/truthy.*true/))
+    expect(true).to be_true
+  end
+
+  it "still passes" do
+    allow(RSpec).to receive(:deprecate)
+    expect(true).to be_true
+  end
+
+  it "still fails" do
+    allow(RSpec).to receive(:deprecate)
+    expect {
+      expect(false).to be_true
+    }.to fail_with(/expected: truthy value/)
+  end
+end
+
+describe "expect(...).to be_falsey" do
+  it "passes when actual equal?(false)" do
+    expect(false).to be_falsey
+  end
+
   it "passes when actual equal?(nil)" do
-    expect(nil).to be_false
+    expect(nil).to be_falsey
   end
 
   it "fails when actual equal?(true)" do
     expect {
-      expect(true).to be_false
-    }.to fail_with("expected: false value\n     got: true")
+      expect(true).to be_falsey
+    }.to fail_with("expected: falsey value\n     got: true")
+  end
+end
+
+describe "expect(...).to be_falsy" do
+  it "passes when actual equal?(false)" do
+    expect(false).to be_falsy
+  end
+
+  it "passes when actual equal?(nil)" do
+    expect(nil).to be_falsy
+  end
+
+  it "fails when actual equal?(true)" do
+    expect {
+      expect(true).to be_falsy
+    }.to fail_with("expected: falsey value\n     got: true")
   end
 end