Add deprecation warnings for features to be removed/changed in RSpec 4

Changelog.md

@@ -13,6 +13,10 @@ Bug fixes:
 * Fix exception presenter when the root cause exception has nil backtrace.
   (Zinovyev Ivan, #2903)
 
+Deprecations:
+
+* Add RSpec 4 deprecation warnings. (Phil Pirozhkov, #2880)
+
 ### 3.10.1 / 2020-12-27
 [Full Changelog](http://github.com/rspec/rspec-core/compare/v3.10.0...v3.10.1)
 

lib/rspec/core/configuration.rb

@@ -327,7 +327,11 @@ def exclude_pattern=(value)
       # (default: `false`).
       # @deprecated Use {#filter_run_when_matching} instead for the specific
       #   filters that you want to be ignored if none match.
-      add_setting :run_all_when_everything_filtered
+      def run_all_when_everything_filtered=(value)
+        RSpec.deprecate("`run_all_when_everything_filtered` setting", :replacement => "`filter_run_when_matching :focus`")
+        @run_all_when_everything_filtered = value
+      end
+      add_read_only_setting :run_all_when_everything_filtered
 
       # @macro add_setting
       # Color to use to indicate success.  Defaults to `:green` but can be set
@@ -440,6 +444,11 @@ def shared_context_metadata_behavior=(value)
             "shared_context_metadata_behavior` to `#{value.inspect}`. Only " \
             "`:trigger_inclusion` and `:apply_to_host_groups` are valid values."
         end
+
+        if value == :trigger_inclusion
+          RSpec.deprecate("`shared_context_metadata_behavior` setting",
+                          :message => "`:apply_to_host_groups` will become the default and only option.")
+        end
       end
 
       # Record the start time of the spec suite to measure load time.
@@ -492,7 +501,12 @@ def bisect_runner=(value)
 
       # @private
       # @deprecated Use {#color_mode} = :on, instead of {#color} with {#tty}
-      add_setting :tty
+      def tty=(value)
+        RSpec.deprecate("`tty` setting", :replacement => "`color_mode`")
+        @tty = value
+      end
+      add_read_only_setting :tty
+
       # @private
       attr_writer :files_to_run
       # @private
@@ -933,8 +947,11 @@ def color_enabled?(output=output_stream)
       #
       # @deprecated No longer recommended because of complex behavior. Instead,
       #   rely on the fact that TTYs will display color by default, or set
-      #   {:color_mode} to :on to display color on a non-TTY output.
-      attr_writer :color
+      #   {#color_mode} to :on to display color on a non-TTY output.
+      def color=(value)
+        RSpec.deprecate("`color` setting", :replacement => "`color_mode`")
+        @color = value
+      end
 
       # @private
       def libs=(libs)
@@ -1217,7 +1234,13 @@ def alias_example_group_to(new_name, *args)
       def alias_it_behaves_like_to(new_name, report_label='')
         RSpec::Core::ExampleGroup.define_nested_shared_group_method(new_name, report_label)
       end
-      alias_method :alias_it_should_behave_like_to, :alias_it_behaves_like_to
+
+      # Alias for `alias_it_behaves_like_to`.
+      # @deprecated Use {#alias_it_behaves_like_to} instead.
+      def alias_it_should_behave_like_to(new_name, report_label='')
+        RSpec.deprecate("`alias_it_should_behave_like_to`", :replacement => "`alias_it_behaves_like_to`")
+        alias_it_behaves_like_to(new_name, report_label)
+      end
 
       # Adds key/value pairs to the `inclusion_filter`. If `args`
       # includes any symbols that are not part of the hash, each symbol

lib/rspec/core/dsl.rb

@@ -81,7 +81,10 @@ def self.remove_globally!
       def self.expose_example_group_alias_globally(method_name)
         change_global_dsl do
           remove_method(method_name) if method_defined?(method_name)
-          define_method(method_name) { |*a, &b| ::RSpec.__send__(method_name, *a, &b) }
+          define_method(method_name) do |*a, &b|
+            RSpec.deprecate("Globally-exposed DSL (`#{method_name}`)", :replacement => "`RSpec.#{method_name}`")
+            ::RSpec.__send__(method_name, *a, &b)
+          end
         end
       end
 

lib/rspec/core/example.rb

@@ -109,6 +109,7 @@ def location_rerun_argument
       # @note If there are multiple examples identified by this location, they will use {#id}
       #   to rerun instead, but this method will still return the location (that's why it is deprecated!).
       def rerun_argument
+        RSpec.deprecate("`rerun_argument`", :replacement => "`location_rerun_argument`")
         location_rerun_argument
       end
 

lib/rspec/core/example_group.rb

@@ -316,6 +316,8 @@ def self.define_example_group_method(name, metadata={})
       #   @see SharedExampleGroup
       def self.define_nested_shared_group_method(new_name, report_label="it should behave like")
         idempotently_define_singleton_method(new_name) do |name, *args, &customization_block|
+          yield if block_given? # to print a deprecation warning for it_should_behave_like usage
+
           # Pass :caller so the :location metadata is set properly.
           # Otherwise, it'll be set to the next line because that's
           # the block's source_location.
@@ -332,7 +334,9 @@ def self.define_nested_shared_group_method(new_name, report_label="it should beh
       define_nested_shared_group_method :it_behaves_like, "behaves like"
       # Generates a nested example group and includes the shared content
       # mapped to `name` in the nested group.
-      define_nested_shared_group_method :it_should_behave_like
+      define_nested_shared_group_method(:it_should_behave_like) do
+        RSpec.deprecate("`it_should_behave_like`", :replacement => "`it_behaves_like`")
+      end
 
       # Includes shared content mapped to `name` directly in the group in which
       # it is declared, as opposed to `it_behaves_like`, which creates a nested
@@ -517,6 +521,9 @@ def self.top_level?
       # @private
       def self.ensure_example_groups_are_configured
         unless defined?(@@example_groups_configured)
+          unless RSpec.configuration.disable_monkey_patching
+            RSpec.deprecate("Monkey-patching mode", :call_site => nil)
+          end
           RSpec.configuration.configure_mock_framework
           RSpec.configuration.configure_expectation_framework
           # rubocop:disable Style/ClassVars

lib/rspec/core/filter_manager.rb

@@ -89,6 +89,15 @@ def add_path_to_arrays_filter(filter_key, path, values)
       def prune_conditionally_filtered_examples(examples)
         examples.reject do |ex|
           meta = ex.metadata
+          if meta.key?(:if)
+            RSpec.deprecate("`:if` metadata will have no special meaning in RSpec 4 and",
+                            :replacement => "`:skip` with a negated condition",
+                            :call_site => meta[:location])
+          end
+          if meta.key?(:unless)
+            RSpec.deprecate("`:unless` metadata will have no special meaning in RSpec 4 and",
+                            :replacement => "`:skip`")
+          end
           !meta.fetch(:if, true) || meta[:unless]
         end
       end

lib/rspec/core/memoized_helpers.rb

@@ -78,6 +78,7 @@ def subject
       # @note If you are using RSpec's newer expect-based syntax you may
       #       want to use `is_expected.to` instead of `should`.
       def should(matcher=nil, message=nil)
+        RSpec.deprecate("Monkey-patching `should`", :replacement => "RSpec Expectations' `is_expected.to`")
         enforce_value_expectation(matcher, 'should')
         RSpec::Expectations::PositiveExpectationHandler.handle_matcher(subject, matcher, message)
       end
@@ -98,6 +99,7 @@ def should(matcher=nil, message=nil)
       # @note If you are using RSpec's newer expect-based syntax you may
       #       want to use `is_expected.to_not` instead of `should_not`.
       def should_not(matcher=nil, message=nil)
+        RSpec.deprecate("Monkey-patching `should_not`", :replacement => "RSpec Expectations' `is_expected.not_to`")
         enforce_value_expectation(matcher, 'should_not')
         RSpec::Expectations::NegativeExpectationHandler.handle_matcher(subject, matcher, message)
       end

spec/integration/bisect_runners_spec.rb

@@ -53,8 +53,7 @@ def with_runner(&block)
     it 'honors `run_all_when_everything_filtered`' do
       write_file 'spec/a_spec.rb', "
         RSpec.configure do |c|
-          c.filter_run :focus
-          c.run_all_when_everything_filtered = true
+          c.filter_run_when_matching :focus
         end
 
         RSpec.describe 'A group' do
@@ -98,7 +97,7 @@ def with_runner(&block)
     include_examples 'a bisect runner'
   end
 
-  RSpec.describe Bisect::ForkRunner, :if => RSpec::Support::RubyFeatures.fork_supported? do
+  RSpec.describe Bisect::ForkRunner, :skip => !RSpec::Support::RubyFeatures.fork_supported? do
     include_examples 'a bisect runner'
 
     context 'when a `--require` option has been provided' do

spec/integration/bisect_spec.rb

@@ -38,7 +38,7 @@ def bisect(cli_args, expected_status=nil)
         expect(output).to include("No failures found.")
       end
 
-      it 'does not leave zombie processes', :unless => RSpec::Support::OS.windows? do
+      it 'does not leave zombie processes', :skip => RSpec::Support::OS.windows? do
         bisect(['--format', 'json', 'spec/rspec/core/resources/blocking_pipe_bisect_spec.rb_'], 1)
 
         zombie_process = RSpecChildProcess.new(Process.pid).zombie_process

spec/rspec/core/backtrace_formatter_spec.rb

@@ -21,7 +21,7 @@ def make_backtrace_formatter(exclusion_patterns=nil, inclusion_patterns=nil)
         expect(make_backtrace_formatter.exclude?("exe/rspec")).to be true
       end
 
-      it "excludes java files (for JRuby)", :if => (RUBY_PLATFORM == 'java')  do
+      it "excludes java files (for JRuby)", :skip => RUBY_PLATFORM != 'java'  do
         expect(make_backtrace_formatter.exclude?("org/jruby/RubyArray.java:2336")).to be true
       end
 
@@ -172,7 +172,7 @@ def make_backtrace_formatter(exclusion_patterns=nil, inclusion_patterns=nil)
       end
 
       context "when rspec is installed in the current working directory" do
-        it "excludes lines from rspec libs by default", :unless => RSpec::Support::OS.windows? do
+        it "excludes lines from rspec libs by default", :skip => RSpec::Support::OS.windows? do
           backtrace = [
             "#{Dir.getwd}/.bundle/path/to/rspec-expectations/lib/rspec/expectations/foo.rb:37",
             "#{Dir.getwd}/.bundle/path/to/rspec-expectations/lib/rspec/matchers/foo.rb:37",

spec/rspec/core/configuration_options_spec.rb

@@ -6,7 +6,7 @@
 
   # On Ruby 2.4, `File.expand("~")` works even if `ENV['HOME']` is not set.
   # But on earlier versions, it fails.
-  it "warns when HOME env var is not set", :unless => (RUBY_PLATFORM == 'java' || RSpec::Support::OS.windows? || RUBY_VERSION >= '2.4') do
+  it "warns when HOME env var is not set", :skip => (RUBY_PLATFORM == 'java' || RSpec::Support::OS.windows? || RUBY_VERSION >= '2.4') do
     without_env_vars 'HOME' do
       expect_warning_with_call_site(__FILE__, __LINE__ + 1)
       RSpec::Core::ConfigurationOptions.new([]).options

spec/rspec/core/configuration_spec.rb

@@ -611,12 +611,12 @@ def stub_expectation_adapters
           expect(config.files_to_run).to contain_files("spec/rspec/core/resources/a_spec.rb", "spec/rspec/core/resources/acceptance/foo_spec.rb")
         end
 
-        it "loads files in Windows", :if => RSpec::Support::OS.windows? do
+        it "loads files in Windows", :skip => !RSpec::Support::OS.windows? do
           assign_files_or_directories_to_run "C:\\path\\to\\project\\spec\\sub\\foo_spec.rb"
           expect(config.files_to_run).to contain_files("C:/path/to/project/spec/sub/foo_spec.rb")
         end
 
-        it "loads files in Windows when directory is specified", :failing_on_windows_ci, :if => RSpec::Support::OS.windows? do
+        it "loads files in Windows when directory is specified", :failing_on_windows_ci, :skip => !RSpec::Support::OS.windows? do
           assign_files_or_directories_to_run "spec\\rspec\\core\\resources"
           expect(config.files_to_run).to contain_files("spec/rspec/core/resources/a_spec.rb")
         end
@@ -1233,7 +1233,7 @@ def metadata_hash(*args)
       end
     end
 
-    describe "#prepend", :if => RSpec::Support::RubyFeatures.module_prepends_supported? do
+    describe "#prepend", :skip => !RSpec::Support::RubyFeatures.module_prepends_supported? do
       include_examples "warning of deprecated `:example_group` during filtering configuration", :prepend, Enumerable
 
       module SomeRandomMod
@@ -1306,6 +1306,18 @@ def metadata_hash(*args)
         config.run_all_when_everything_filtered = true
         expect(config.run_all_when_everything_filtered?).to be(true)
       end
+
+      it "emits a deprecation message when set" do
+        expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /run_all_when_everything_filtered/)
+        config.run_all_when_everything_filtered = true
+      end
+    end
+
+    describe "#tty=" do
+      it "emits a deprecation message when set" do
+        expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /tty/)
+        config.tty = true
+      end
     end
 
     describe "#color_mode" do
@@ -1400,6 +1412,11 @@ def metadata_hash(*args)
     describe "#color=" do
       before { config.color_mode = :automatic }
 
+      it "emits a deprecation message when set" do
+        expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /color/)
+        config.color = true
+      end
+
       context "given false" do
         before { config.color = false }
 
@@ -2337,7 +2354,7 @@ def self.prepended(host)
       end
 
       it "doesn't prepend a module when already present in ancestor chain",
-        :if => RSpec::Support::RubyFeatures.module_prepends_supported? do
+        :skip => !RSpec::Support::RubyFeatures.module_prepends_supported? do
         config.prepend(IncludeExtendOrPrependMeOnce, :foo => :bar)
 
         group = RSpec.describe("group", :foo => :bar)
@@ -2369,6 +2386,13 @@ class << self
         end
       end
 
+      describe '#alias_it_should_behave_like_to' do
+        it "emits a deprecation message when used" do
+          expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /alias_it_should_behave_like_to/)
+          config.alias_it_should_behave_like_to :it_should_have_behaved_like
+        end
+      end
+
       it_behaves_like "metadata hash builder" do
         def metadata_hash(*args)
           config.alias_example_group_to :my_group_method, *args
@@ -2904,6 +2928,16 @@ def emulate_not_configured_expectation_framework
           ":another_value", ":trigger_inclusion", ":apply_to_host_groups"
         ))
       end
+
+      it "emits a deprecation message when set to :trigger_inclusion" do
+        expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /shared_context_metadata_behavior/)
+        config.shared_context_metadata_behavior = :trigger_inclusion
+      end
+
+      it "does not emit a deprecation message when set to :apply_to_host_groups" do
+        expect_no_deprecation
+        config.shared_context_metadata_behavior = :apply_to_host_groups
+      end
     end
 
     # assigns files_or_directories_to_run and triggers post-processing

spec/rspec/core/did_you_mean_spec.rb

@@ -23,7 +23,7 @@ module Core
             end
           end
         end
-        context "when `DidYouMean::SpellChecker` is not available", :unless => defined?(::DidYouMean::SpellChecker) do
+        context "when `DidYouMean::SpellChecker` is not available", :skip => defined?(::DidYouMean::SpellChecker) do
           describe 'Success' do
             let(:name) { './spec/rspec/core/did_you_mean_spec.rb' }
             it 'returns a hint' do

spec/rspec/core/drb_spec.rb

@@ -1,6 +1,6 @@
 require 'rspec/core/drb'
 
-RSpec.describe RSpec::Core::DRbRunner, :isolated_directory => true, :isolated_home => true, :type => :drb, :unless => RUBY_PLATFORM == 'java' do
+RSpec.describe RSpec::Core::DRbRunner, :isolated_directory => true, :isolated_home => true, :type => :drb, :skip => RUBY_PLATFORM == 'java' do
   let(:config) { RSpec::Core::Configuration.new }
   let(:out)    { StringIO.new }
   let(:err)    { StringIO.new }

spec/rspec/core/dsl_spec.rb

@@ -27,6 +27,21 @@ def enable
           expect(Object.new).not_to respond_to(*method_names)
         end
       end
+
+      it 'emits a deprecation warning' do
+        in_sub_process do
+          expect_deprecation_with_call_site(__FILE__, __LINE__ + 6, /Globally-exposed DSL \(`describe`\)/)
+          changing_expose_dsl_globally do
+            RSpec.configuration.expose_dsl_globally = true
+            expect(RSpec.configuration.expose_dsl_globally?).to eq true
+
+            Module.new do
+              describe 'monkey' do
+              end
+            end
+          end
+        end
+      end
     end
 
     context "when expose_dsl_globally is disabled" do