rspec-expectations 2.14.5 → 2.99.0

data/spec/rspec/matchers/matcher_spec.rb

@@ -33,8 +33,8 @@ module RSpec::Matchers::DSL
       m1 = example_matcher(1)
       m2 = example_matcher(2)
 
-      expect(m1.matches?(1)).to be_true
-      expect(m2.matches?(2)).to be_true
+      expect(m1.matches?(1)).to be_truthy
+      expect(m2.matches?(2)).to be_truthy
     end
 
     context "with an included module" do
@@ -66,6 +66,29 @@ module RSpec::Matchers::DSL
       end
     end
 
+    context "matching blocks" do
+      it 'warns when matching blocks by default' do
+        matcher = RSpec::Matchers::DSL::Matcher.new(:not_supporting_blocks) do
+          match { true }
+        end.for_expected
+
+        expect_deprecation_with_call_site(__FILE__, __LINE__ + 2, /block expectation/)
+        expect(3).to matcher
+        expect { 3 }.to matcher
+      end
+
+      it 'does not when if it declares `supports_block_expectations`' do
+        matcher = RSpec::Matchers::DSL::Matcher.new(:supporting_blocks) do
+          match { true }
+          supports_block_expectations
+        end.for_expected
+
+        expect_no_deprecation
+        expect(3).to matcher
+        expect { 3 }.to matcher
+      end
+    end
+
     context "without overrides" do
       before(:each) do
         @matcher = RSpec::Matchers::DSL::Matcher.new(:be_a_multiple_of) do |multiple|
@@ -104,13 +127,13 @@ module RSpec::Matchers::DSL
       end
 
       it "invokes the match_for_should block for #matches?" do
-        expect(matcher.matches?(77)).to be_true
-        expect(matcher.matches?(18)).to be_false
+        expect(matcher.matches?(77)).to be_truthy
+        expect(matcher.matches?(18)).to be_falsey
       end
 
       it "invokes the match_for_should_not block for #does_not_match?" do
-        expect(matcher.does_not_match?(77)).to be_false
-        expect(matcher.does_not_match?(18)).to be_true
+        expect(matcher.does_not_match?(77)).to be_falsey
+        expect(matcher.does_not_match?(18)).to be_truthy
       end
 
       it "provides a default failure message for #should_not" do
@@ -138,6 +161,19 @@ module RSpec::Matchers::DSL
     end
 
     it "provides expected" do
+      expect_no_deprecation
+      matcher = RSpec::Matchers::DSL::Matcher.new(:name) {}.for_expected('expected', 'strings')
+      expect(matcher.expected).to eq %w[expected strings]
+    end
+
+    it "provides expected as an array" do
+      expect_no_deprecation
+      matcher = RSpec::Matchers::DSL::Matcher.new(:name) {}.for_expected('expected string')
+      expect(matcher.expected_as_array).to eq ['expected string']
+    end
+
+    it "warns of deprecation about expected when it's a single value" do
+      expect_deprecation_with_call_site __FILE__, __LINE__ + 2
       matcher = RSpec::Matchers::DSL::Matcher.new(:name) {}.for_expected('expected string')
       expect(matcher.expected).to eq ['expected string']
     end
@@ -159,7 +195,7 @@ module RSpec::Matchers::DSL
             expect(actual).to eq expected
           end
         end.for_expected('value')
-        expect(matcher.matches?('value')).to be_true
+        expect(matcher.matches?('value')).to be_truthy
       end
 
       it "returns false if the wrapped expectation fails" do
@@ -168,7 +204,7 @@ module RSpec::Matchers::DSL
             expect(actual).to eq expected
           end
         end.for_expected('value')
-        expect(matcher.matches?('other value')).to be_false
+        expect(matcher.matches?('other value')).to be_falsey
       end
     end
 
@@ -191,11 +227,11 @@ module RSpec::Matchers::DSL
       end
 
       it "does not hide result of match block when true" do
-        expect(@matcher.matches?(true)).to be_true
+        expect(@matcher.matches?(true)).to be_truthy
       end
 
       it "does not hide result of match block when false" do
-        expect(@matcher.matches?(false)).to be_false
+        expect(@matcher.matches?(false)).to be_falsey
       end
 
       it "overrides the description" do
@@ -220,7 +256,7 @@ module RSpec::Matchers::DSL
             actual == 5
           end
         end.for_expected
-        expect(matcher.matches?(5)).to be_true
+        expect(matcher.matches?(5)).to be_truthy
       end
 
       it "exposes arg submitted through #new to matcher block" do
@@ -229,7 +265,7 @@ module RSpec::Matchers::DSL
             actual > expected
           end
         end.for_expected(4)
-        expect(matcher.matches?(5)).to be_true
+        expect(matcher.matches?(5)).to be_truthy
       end
     end
 
@@ -243,7 +279,7 @@ module RSpec::Matchers::DSL
       end
 
       it "matches" do
-        expect(@matcher.matches?(5)).to be_true
+        expect(@matcher.matches?(5)).to be_truthy
       end
 
       it "describes" do
@@ -261,7 +297,7 @@ module RSpec::Matchers::DSL
       end
 
       it "matches" do
-        expect(@matcher.matches?(5)).to be_true
+        expect(@matcher.matches?(5)).to be_truthy
       end
 
       it "describes" do
@@ -279,7 +315,7 @@ module RSpec::Matchers::DSL
       end
 
       it "matches" do
-        expect(@matcher.matches?(10)).to be_true
+        expect(@matcher.matches?(10)).to be_truthy
       end
 
       it "describes" do
@@ -298,7 +334,7 @@ module RSpec::Matchers::DSL
         end
       end.for_expected([1,2,3])
 
-      expect(matcher.matches?([2,3,1])).to be_true
+      expect(matcher.matches?([2,3,1])).to be_truthy
     end
 
     it "supports fluent interface" do
@@ -324,7 +360,131 @@ module RSpec::Matchers::DSL
         end
       end.for_expected(3)
 
-      expect(matcher.matches?(8)).to be_true
+      expect(matcher.matches?(8)).to be_truthy
+    end
+
+    shared_examples_for "accessing a singleton helper method" do
+      before { allow_deprecation }
+
+      it 'can access the helper method from `match`' do
+        expect([2, 3]).to matcher.for_expected(5)
+        expect([2, 3]).not_to matcher.for_expected(4)
+      end
+
+      it 'prints a deprecation warning when the helper method is accessed `match`' do
+        expect(RSpec).to receive(:deprecate).with(/sum_of/, an_instance_of(Hash))
+        matcher.for_expected(5).matches?([2, 3])
+      end
+
+      it 'includes the call site in the deprecation warning' do
+        expect_deprecation_with_call_site(__FILE__, line)
+        matcher.for_expected(5).matches?([2, 3])
+      end
+
+      it 'does not print a deprecation warning if the helper method is used as a macro' do
+        expect(RSpec).not_to receive(:deprecate)
+        matcher.for_expected(:use_as_macro).matches?([2, 3])
+      end
+    end
+
+    context "when a module of helper methods is extended" do
+      include_examples "accessing a singleton helper method" do
+        let(:matcher) do
+          RSpec::Matchers::DSL::Matcher.new(:sum_to) do |sum|
+            extend Module.new {
+              def sum_of(x, y) x + y end
+              def define_match() match {} end
+            }
+
+            if sum == :use_as_macro
+              define_match
+            else
+              match { |summands| sum_of(*summands) == sum }
+            end
+          end
+        end
+        let(:line) { __LINE__ - 4 }
+      end
+    end
+
+    context "when a helper method is defined using `self.`" do
+      include_examples "accessing a singleton helper method" do
+        let(:matcher) do
+          RSpec::Matchers::DSL::Matcher.new(:sum_to) do |sum|
+            def self.sum_of(x, y) x + y end
+            def self.define_match() match {} end
+
+            if sum == :use_as_macro
+              define_match
+            else
+              match { |summands| sum_of(*summands) == sum }
+            end
+          end
+        end
+        let(:line) { __LINE__ - 4 }
+      end
+    end
+
+    shared_examples_for "accessing an instance helper method" do
+      before { allow_deprecation }
+
+      it 'can access the helper method from `match`' do
+        expect([2, 3]).to matcher.for_expected(5)
+        expect([2, 3]).not_to matcher.for_expected(4)
+      end
+
+      it 'does not print a deprecation warning when the helper method is accessed from `match`' do
+        expect(RSpec).not_to receive(:deprecate)
+        matcher.for_expected(5).matches?([2, 3])
+      end
+
+      it 'prints a deprecation warning if the helper method is used as a macro' do
+        expect(RSpec).to receive(:deprecate).with(/define_match/, an_instance_of(Hash))
+        matcher.for_expected(:use_as_macro).matches?([2, 3])
+      end
+
+      it 'includes the call site in the deprecation warning' do
+        expect_deprecation_with_call_site(__FILE__, line)
+        matcher.for_expected(:use_as_macro).matches?([2, 3])
+      end
+    end
+
+    context "when a module of helper methods is included" do
+      include_examples "accessing an instance helper method" do
+        let(:matcher) do
+          RSpec::Matchers::DSL::Matcher.new(:sum_to) do |sum|
+            include Module.new {
+              def sum_of(x, y) x + y end
+              def define_match() match {} end
+            }
+
+            if sum == :use_as_macro
+              define_match
+            else
+              match { |summands| sum_of(*summands) == sum }
+            end
+          end
+        end
+        let(:line) { __LINE__ - 6 }
+      end
+    end
+
+    context "when a helper method is defined using `def foo`" do
+      include_examples "accessing an instance helper method" do
+        let(:matcher) do
+          RSpec::Matchers::DSL::Matcher.new(:sum_to) do |sum|
+            def sum_of(x, y) x + y end
+            def define_match() match {} end
+
+            if sum == :use_as_macro
+              define_match
+            else
+              match { |summands| sum_of(*summands) == sum }
+            end
+          end
+        end
+        let(:line) { __LINE__ - 6 }
+      end
     end
 
     context 'when multiple instances of the same matcher are used in the same example' do
@@ -377,7 +537,7 @@ module RSpec::Matchers::DSL
         let(:matcher) do
           m = mod
           RSpec::Matchers::DSL::Matcher.new :equal do |expected|
-            extend m
+            include m
             match_unless_raises UnexpectedError do
               assert_equal expected, actual
             end
@@ -386,13 +546,13 @@ module RSpec::Matchers::DSL
 
         context "with passing assertion" do
           it "passes" do
-            expect(matcher.matches?(4)).to be_true
+            expect(matcher.matches?(4)).to be_truthy
           end
         end
 
         context "with failing assertion" do
           it "fails" do
-            expect(matcher.matches?(5)).to be_false
+            expect(matcher.matches?(5)).to be_falsey
           end
 
           it "provides the raised exception" do
@@ -428,8 +588,8 @@ module RSpec::Matchers::DSL
         match { |actual| actual == @expected_value }
       end.for_expected
 
-      expect(matcher.expecting('value').matches?('value')).to be_true
-      expect(matcher.expecting('value').matches?('other value')).to be_false
+      expect(matcher.expecting('value').matches?('value')).to be_truthy
+      expect(matcher.expecting('value').matches?('other value')).to be_falsey
     end
 
     it "prevents name collisions on chainable methods from different matchers" do
@@ -445,7 +605,7 @@ module RSpec::Matchers::DSL
         "method defined in the example"
       end
 
-      it "can access methods in the running example" do
+      it "can access methods in the running example" do |example|
         RSpec::Matchers.define(:__access_running_example) do
           match do |actual|
             a_method_in_the_example == "method defined in the example"
@@ -454,7 +614,7 @@ module RSpec::Matchers::DSL
         expect(example).to __access_running_example
       end
 
-      it "raises NoMethodError for methods not in the running_example" do
+      it "raises NoMethodError for methods not in the running_example" do |example|
         RSpec::Matchers.define(:__raise_no_method_error) do
           match do |actual|
             a_method_not_in_the_example == "method defined in the example"
@@ -467,5 +627,34 @@ module RSpec::Matchers::DSL
       end
     end
 
+    describe "#matcher_execution_context" do
+      before { allow_deprecation }
+
+      let(:matcher) do
+        RSpec::Matchers::DSL::Matcher.new :foo do |expected|
+        end.for_expected(:bar)
+      end
+
+      it 'can be set' do
+        expect {
+          matcher.matcher_execution_context = :the_context
+        }.to change(matcher, :matcher_execution_context).to(:the_context)
+      end
+
+      it 'is the target of method_missing delegation' do
+        matcher.matcher_execution_context = double(:abcd => "efg")
+        expect(matcher.abcd).to eq("efg")
+      end
+
+      specify "the writer is deprecated" do
+        expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /matcher_execution_context/)
+        matcher.matcher_execution_context = :the_context
+      end
+
+      specify "the reader is deprecated" do
+        expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /matcher_execution_context/)
+        matcher.matcher_execution_context
+      end
+    end
   end
 end

data/spec/rspec/matchers/operator_matcher_spec.rb

@@ -24,7 +24,7 @@ describe "operator matchers", :uses_should do
 
     it "returns true on success" do
       subject = "apple"
-      (subject.should == "apple").should be_true
+      (subject.should == "apple").should be_truthy
     end
 
     it "fails when target.==(actual) returns false" do
@@ -44,7 +44,7 @@ describe "operator matchers", :uses_should do
       obj = Object.new
 
       myobj = MethodMissingObject.new(obj)
-      myobj.should == obj
+      (myobj.should == obj).nil? # just to avoid `useless use of == in void context` warning
       myobj.should_not == Object.new
     end
   end
@@ -84,7 +84,7 @@ describe "operator matchers", :uses_should do
 
     it "returns true on success" do
       subject = "apple"
-      (subject.should_not == "orange").should be_false
+      (subject.should_not == "orange").should be_falsey
     end
 
     it "fails when target.==(actual) returns false" do
@@ -211,21 +211,40 @@ describe "operator matchers", :uses_should do
     let(:custom_subklass) { Class.new(custom_klass) }
 
     after {
-      RSpec::Matchers::OperatorMatcher.unregister(custom_klass, "=~")
+      RSpec::Matchers::BuiltIn::OperatorMatcher.unregister(custom_klass, "=~")
     }
 
     it "allows operator matchers to be registered for types" do
-      RSpec::Matchers::OperatorMatcher.register(custom_klass, "=~", RSpec::Matchers::BuiltIn::Match)
-      expect(RSpec::Matchers::OperatorMatcher.get(custom_klass, "=~")).to eq(RSpec::Matchers::BuiltIn::Match)
+      RSpec::Matchers::BuiltIn::OperatorMatcher.register(custom_klass, "=~", RSpec::Matchers::BuiltIn::Match)
+      expect(RSpec::Matchers::BuiltIn::OperatorMatcher.get(custom_klass, "=~")).to eq(RSpec::Matchers::BuiltIn::Match)
     end
 
     it "considers ancestors when finding an operator matcher" do
-      RSpec::Matchers::OperatorMatcher.register(custom_klass, "=~", RSpec::Matchers::BuiltIn::Match)
-      expect(RSpec::Matchers::OperatorMatcher.get(custom_subklass, "=~")).to eq(RSpec::Matchers::BuiltIn::Match)
+      RSpec::Matchers::BuiltIn::OperatorMatcher.register(custom_klass, "=~", RSpec::Matchers::BuiltIn::Match)
+      expect(RSpec::Matchers::BuiltIn::OperatorMatcher.get(custom_subklass, "=~")).to eq(RSpec::Matchers::BuiltIn::Match)
     end
 
     it "returns nil if there is no matcher registered for a type" do
-      expect(RSpec::Matchers::OperatorMatcher.get(custom_klass, "=~")).to be_nil
+      expect(RSpec::Matchers::BuiltIn::OperatorMatcher.get(custom_klass, "=~")).to be_nil
+    end
+
+    context "when accessing it using the old 2.x const name" do
+      it 'returns the new constant scoped by `BuiltIn`' do
+        allow_deprecation
+        expect(RSpec::Matchers::OperatorMatcher).to be(RSpec::Matchers::BuiltIn::OperatorMatcher)
+      end
+
+      it 'issues a deprecation warning' do
+        expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /OperatorMatcher/)
+        RSpec::Matchers::OperatorMatcher
+      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
   end
 

data/spec/rspec/matchers/pretty_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+module RSpec
+  module Matchers
+    describe Pretty do
+      include Pretty
+
+      describe "#_pretty_print" do
+        it 'is deprecated' do
+          expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /_pretty_print/)
+          _pretty_print([1, 2])
+        end
+      end
+
+      describe "#expected_to_sentence" do
+        it 'is deprecated' do
+          expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /expected_to_sentence/)
+          expected_to_sentence
+        end
+      end
+    end
+  end
+end

data/spec/rspec/matchers/raise_error_spec.rb

@@ -61,7 +61,7 @@ describe "expect { ... }.to raise_error {|err| ... }" do
     expect { non_existent_method }.to raise_error {|e|
       ran = true
     }
-    expect(ran).to be_true
+    expect(ran).to be_truthy
   end
 
   it "passes the error to the block" do
@@ -409,8 +409,8 @@ describe "expect { ... }.to raise_error(NamedError, error_message) { |err| ... }
       }
     }.to fail_with(/expected: 4/m)
 
-    expect(ran).to    be_true
-    expect(passed).to be_false
+    expect(ran).to    be_truthy
+    expect(passed).to be_falsey
   end
 
   it "does NOT yield exception if no error was thrown" do

data/spec/rspec/matchers/throw_symbol_spec.rb

@@ -11,13 +11,13 @@ module RSpec::Matchers::BuiltIn
       before(:each) { @matcher = throw_symbol }
 
       it "matches if any Symbol is thrown" do
-        expect(@matcher.matches?(lambda{ throw :sym })).to be_true
+        expect(@matcher.matches?(lambda{ throw :sym })).to be_truthy
       end
       it "matches if any Symbol is thrown with an arg" do
-        expect(@matcher.matches?(lambda{ throw :sym, "argument" })).to be_true
+        expect(@matcher.matches?(lambda{ throw :sym, "argument" })).to be_truthy
       end
       it "does not match if no Symbol is thrown" do
-        expect(@matcher.matches?(lambda{ })).to be_false
+        expect(@matcher.matches?(lambda{ })).to be_falsey
       end
       it "provides a failure message" do
         @matcher.matches?(lambda{})
@@ -33,16 +33,16 @@ module RSpec::Matchers::BuiltIn
       before(:each) { @matcher = throw_symbol(:sym) }
 
       it "matches if correct Symbol is thrown" do
-        expect(@matcher.matches?(lambda{ throw :sym })).to be_true
+        expect(@matcher.matches?(lambda{ throw :sym })).to be_truthy
       end
       it "matches if correct Symbol is thrown with an arg" do
-        expect(@matcher.matches?(lambda{ throw :sym, "argument" })).to be_true
+        expect(@matcher.matches?(lambda{ throw :sym, "argument" })).to be_truthy
       end
       it "does not match if no Symbol is thrown" do
-        expect(@matcher.matches?(lambda{ })).to be_false
+        expect(@matcher.matches?(lambda{ })).to be_falsey
       end
       it "does not match if correct Symbol is thrown" do
-        expect(@matcher.matches?(lambda{ throw :other_sym })).to be_false
+        expect(@matcher.matches?(lambda{ throw :other_sym })).to be_falsey
       end
       it "provides a failure message when no Symbol is thrown" do
         @matcher.matches?(lambda{})
@@ -58,7 +58,7 @@ module RSpec::Matchers::BuiltIn
       end
       it "only matches NameErrors raised by uncaught throws" do
         expect {
-          expect(@matcher.matches?(lambda{ sym })).to be_false
+          expect(@matcher.matches?(lambda{ sym })).to be_falsey
         }.to raise_error(NameError)
       end
     end
@@ -67,19 +67,19 @@ module RSpec::Matchers::BuiltIn
       before(:each) { @matcher = throw_symbol(:sym, "a") }
 
       it "matches if correct Symbol and args are thrown" do
-        expect(@matcher.matches?(lambda{ throw :sym, "a" })).to be_true
+        expect(@matcher.matches?(lambda{ throw :sym, "a" })).to be_truthy
       end
       it "does not match if nothing is thrown" do
-        expect(@matcher.matches?(lambda{ })).to be_false
+        expect(@matcher.matches?(lambda{ })).to be_falsey
       end
       it "does not match if other Symbol is thrown" do
-        expect(@matcher.matches?(lambda{ throw :other_sym, "a" })).to be_false
+        expect(@matcher.matches?(lambda{ throw :other_sym, "a" })).to be_falsey
       end
       it "does not match if no arg is thrown" do
-        expect(@matcher.matches?(lambda{ throw :sym })).to be_false
+        expect(@matcher.matches?(lambda{ throw :sym })).to be_falsey
       end
       it "does not match if wrong arg is thrown" do
-        expect(@matcher.matches?(lambda{ throw :sym, "b" })).to be_false
+        expect(@matcher.matches?(lambda{ throw :sym, "b" })).to be_falsey
       end
       it "provides a failure message when no Symbol is thrown" do
         @matcher.matches?(lambda{})
@@ -103,7 +103,7 @@ module RSpec::Matchers::BuiltIn
       end
       it "only matches NameErrors raised by uncaught throws" do
         expect {
-          expect(@matcher.matches?(lambda{ sym })).to be_false
+          expect(@matcher.matches?(lambda{ sym })).to be_falsey
         }.to raise_error(NameError)
       end
       it "raises other errors" do

data/spec/spec_helper.rb

@@ -2,8 +2,8 @@ Dir['./spec/support/**/*'].each {|f| require f}
 
 RSpec::configure do |config|
   config.treat_symbols_as_metadata_keys_with_true_values = true
-  config.color_enabled = true
-  config.filter_run :focused
+  config.color = true
+  config.filter_run :focus
   config.run_all_when_everything_filtered = true
   config.order = :random
 
@@ -11,6 +11,8 @@ RSpec::configure do |config|
     $default_expectation_syntax = expectations.syntax
     expectations.syntax = :expect
   end
+
+  config.include DeprecationHelpers
 end
 
 shared_context "with #should enabled", :uses_should do

data/spec/support/helper_methods.rb

@@ -0,0 +1,42 @@
+module DeprecationHelpers
+
+  def expect_deprecation_with_call_site(file, line, snippet = //)
+    expect(RSpec.configuration.reporter).to receive(:deprecation) do |options|
+      matcher = include([file, line].join(':'))
+      call_site = options[:call_site] || options[:message]
+
+      unless matcher.matches?(call_site)
+        # RSpec::Expectations::ExpectationNotMetError is rescued in the `match` block
+        # of a custom matcher and returned as `false` from `matches?`. This would
+        # prevent an expectation failure here from surfacing in the test suite if
+        # it's triggered from within a `match` block, so we need to raise
+        # a different error class instead.
+        raise matcher.failure_message_for_should
+      end
+
+      deprecated = options[:deprecated] || options[:message]
+      expect(deprecated).to match(snippet)
+    end
+  end
+
+  def expect_deprecation_with_type(expression, message, type)
+    expect(RSpec).to receive(:deprecate).with(expression,
+      :replacement => message,
+      :type        => type
+    )
+  end
+
+  def expect_deprecation_with_replacement(snippet)
+    expect(RSpec).to receive(:deprecate) do |_, options|
+      expect(options[:replacement]).to match(snippet)
+    end
+  end
+
+  def allow_deprecation
+    allow(RSpec.configuration.reporter).to receive(:deprecation)
+  end
+
+  def expect_no_deprecation
+    expect(RSpec.configuration.reporter).not_to receive(:deprecation)
+  end
+end