Merge pull request #2066 from rubocop/include-examples

Add new `RSpec/IncludeExamples` cop to prefer `it_behaves_like` over `include_examples`

Author: pirj

.rubocop.yml

@@ -289,3 +289,7 @@ Performance/StringIdentifierArgument: {Enabled: true}
 Performance/StringInclude: {Enabled: true}
 Performance/Sum: {Enabled: true}
 Performance/ZipWithoutBlock: {Enabled: true}
+
+# Enable our own pending cops.
+
+RSpec/IncludeExamples: {Enabled: true}

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Fix false positive in `RSpec/Pending`, where it would mark the default block `it` as an offense. ([@bquorning])
 - Fix issue when `Style/ContextWording` is configured with a Prefix being interpreted as a boolean, like `on`. ([@sakuro])
+- Add new `RSpec/IncludeExamples` cop to enforce using `it_behaves_like` over `include_examples`. ([@dvandersluis])
 
 ## 3.5.0 (2025-02-16)
 

config/default.yml

@@ -532,6 +532,12 @@ RSpec/ImplicitSubject:
   VersionChanged: '2.13'
   Reference: https://www.rubydoc.info/gems/rubocop-rspec/RuboCop/Cop/RSpec/ImplicitSubject
 
+RSpec/IncludeExamples:
+  Description: Checks for usage of `include_examples`.
+  Enabled: pending
+  VersionAdded: "<<next>>"
+  Reference: https://www.rubydoc.info/gems/rubocop-rspec/RuboCop/Cop/RSpec/IncludeExamples
+
 RSpec/IndexedLet:
   Description: Do not set up test data using indexes (e.g., `item_1`, `item_2`).
   Enabled: true

docs/modules/ROOT/pages/cops.adoc

@@ -50,6 +50,7 @@
 * xref:cops_rspec.adoc#rspecimplicitblockexpectation[RSpec/ImplicitBlockExpectation]
 * xref:cops_rspec.adoc#rspecimplicitexpect[RSpec/ImplicitExpect]
 * xref:cops_rspec.adoc#rspecimplicitsubject[RSpec/ImplicitSubject]
+* xref:cops_rspec.adoc#rspecincludeexamples[RSpec/IncludeExamples]
 * xref:cops_rspec.adoc#rspecindexedlet[RSpec/IndexedLet]
 * xref:cops_rspec.adoc#rspecinstancespy[RSpec/InstanceSpy]
 * xref:cops_rspec.adoc#rspecinstancevariable[RSpec/InstanceVariable]

docs/modules/ROOT/pages/cops_rspec.adoc

@@ -2743,6 +2743,45 @@ it { expect(named_subject).to be_truthy }
 
 * https://www.rubydoc.info/gems/rubocop-rspec/RuboCop/Cop/RSpec/ImplicitSubject
 
+[#rspecincludeexamples]
+== RSpec/IncludeExamples
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Pending
+| Yes
+| Always
+| <<next>>
+| -
+|===
+
+Checks for usage of `include_examples`.
+
+`include_examples`, unlike `it_behaves_like`, does not create its
+own context. As such, using `subject`, `let`, `before`/`after`, etc.
+within shared examples included with `include_examples` can have
+unexpected behavior and side effects.
+
+Prefer using `it_behaves_like` instead.
+
+[#examples-rspecincludeexamples]
+=== Examples
+
+[source,ruby]
+----
+# bad
+include_examples 'examples'
+
+# good
+it_behaves_like 'examples'
+----
+
+[#references-rspecincludeexamples]
+=== References
+
+* https://www.rubydoc.info/gems/rubocop-rspec/RuboCop/Cop/RSpec/IncludeExamples
+
 [#rspecindexedlet]
 == RSpec/IndexedLet
 

lib/rubocop/cop/rspec/include_examples.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module RSpec
+      # Checks for usage of `include_examples`.
+      #
+      # `include_examples`, unlike `it_behaves_like`, does not create its
+      # own context. As such, using `subject`, `let`, `before`/`after`, etc.
+      # within shared examples included with `include_examples` can have
+      # unexpected behavior and side effects.
+      #
+      # Prefer using `it_behaves_like` instead.
+      #
+      # @example
+      #   # bad
+      #   include_examples 'examples'
+      #
+      #   # good
+      #   it_behaves_like 'examples'
+      #
+      class IncludeExamples < Base
+        extend AutoCorrector
+
+        MSG = 'Prefer `it_behaves_like` over `include_examples`.'
+
+        RESTRICT_ON_SEND = %i[include_examples].freeze
+
+        def on_send(node)
+          selector = node.loc.selector
+
+          add_offense(selector) do |corrector|
+            corrector.replace(selector, 'it_behaves_like')
+          end
+        end
+      end
+    end
+  end
+end

lib/rubocop/cop/rspec_cops.rb

@@ -48,6 +48,7 @@
 require_relative 'rspec/implicit_block_expectation'
 require_relative 'rspec/implicit_expect'
 require_relative 'rspec/implicit_subject'
+require_relative 'rspec/include_examples'
 require_relative 'rspec/indexed_let'
 require_relative 'rspec/instance_spy'
 require_relative 'rspec/instance_variable'

spec/rubocop/cop/rspec/base_spec.rb

@@ -113,7 +113,7 @@ def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
         RUBY
       end
 
-      include_examples 'it detects `describe`'
+      it_behaves_like 'it detects `describe`'
     end
 
     context 'when `epic` is set as an alias to example group' do
@@ -133,7 +133,7 @@ def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
         RUBY
       end
 
-      include_examples 'it detects `describe`'
+      it_behaves_like 'it detects `describe`'
     end
   end
 end

spec/rubocop/cop/rspec/empty_line_after_hook_spec.rb

@@ -310,8 +310,8 @@
   end
 
   context 'when AllowConsecutiveOneLiners option has default value `true`' do
-    include_examples 'always require empty line after hook groups'
-    include_examples 'never allows consecutive multiline blocks'
+    it_behaves_like 'always require empty line after hook groups'
+    it_behaves_like 'never allows consecutive multiline blocks'
 
     it 'allows multiple one-liner blocks' do
       expect_offense(<<~RUBY)
@@ -381,8 +381,8 @@
   context 'when AllowConsecutiveOneLiners option `false`' do
     let(:cop_config) { { 'AllowConsecutiveOneLiners' => false } }
 
-    include_examples 'always require empty line after hook groups'
-    include_examples 'never allows consecutive multiline blocks'
+    it_behaves_like 'always require empty line after hook groups'
+    it_behaves_like 'never allows consecutive multiline blocks'
 
     it 'registers an offense for multiple one-liner same hook blocks' do
       expect_offense(<<~RUBY)

spec/rubocop/cop/rspec/hook_argument_spec.rb

@@ -29,10 +29,10 @@
   end
 
   shared_examples 'an example hook' do
-    include_examples 'ignored hooks'
-    include_examples 'detects style', 'before(:each) { foo }', 'each'
-    include_examples 'detects style', 'before(:example) { foo }', 'example'
-    include_examples 'detects style', 'before { foo }', 'implicit'
+    it_behaves_like 'ignored hooks'
+    it_behaves_like 'detects style', 'before(:each) { foo }', 'each'
+    it_behaves_like 'detects style', 'before(:example) { foo }', 'example'
+    it_behaves_like 'detects style', 'before { foo }', 'implicit'
   end
 
   context 'when EnforcedStyle is :implicit' do
@@ -87,7 +87,7 @@
       RUBY
     end
 
-    include_examples 'an example hook'
+    it_behaves_like 'an example hook'
 
     context 'when Ruby 2.7', :ruby27 do
       it 'detects :each for hooks' do
@@ -172,7 +172,7 @@
       RUBY
     end
 
-    include_examples 'an example hook'
+    it_behaves_like 'an example hook'
 
     context 'when Ruby 2.7', :ruby27 do
       it 'does not flag :each for hooks' do
@@ -257,7 +257,7 @@
       RUBY
     end
 
-    include_examples 'an example hook'
+    it_behaves_like 'an example hook'
 
     context 'when Ruby 2.7', :ruby27 do
       it 'does not flag :example for hooks' do

spec/rubocop/cop/rspec/implicit_expect_spec.rb

@@ -40,7 +40,7 @@
       expect_no_offenses('it { is_expected.not_to be_truthy }')
     end
 
-    include_examples 'detects style', 'it { should be_truthy }', 'should'
+    it_behaves_like 'detects style', 'it { should be_truthy }', 'should'
   end
 
   context 'when EnforcedStyle is should' do
@@ -89,12 +89,12 @@
       expect_no_offenses('it { should_not be_truthy }')
     end
 
-    include_examples 'detects style',
-                     'it { is_expected.to be_truthy }',
-                     'is_expected'
+    it_behaves_like 'detects style',
+                    'it { is_expected.to be_truthy }',
+                    'is_expected'
 
-    include_examples 'detects style',
-                     'it { should be_truthy }',
-                     'should'
+    it_behaves_like 'detects style',
+                    'it { should be_truthy }',
+                    'should'
   end
 end

spec/rubocop/cop/rspec/include_examples_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+RSpec.describe RuboCop::Cop::RSpec::IncludeExamples, :config do
+  it 'registers an offense and corrects for `include_examples`' do
+    expect_offense(<<~RUBY)
+      include_examples 'examples'
+      ^^^^^^^^^^^^^^^^ Prefer `it_behaves_like` over `include_examples`.
+    RUBY
+
+    expect_correction(<<~RUBY)
+      it_behaves_like 'examples'
+    RUBY
+  end
+
+  it 'does not register an offense for `it_behaves_like`' do
+    expect_no_offenses(<<~RUBY)
+      it_behaves_like 'examples'
+    RUBY
+  end
+
+  it 'does not register an offense for `it_should_behave_like`' do
+    expect_no_offenses(<<~RUBY)
+      it_should_behave_like 'examples'
+    RUBY
+  end
+
+  it 'does not register an offense for `include_context`' do
+    expect_no_offenses(<<~RUBY)
+      include_context 'context'
+    RUBY
+  end
+end

spec/rubocop/cop/rspec/message_expectation_spec.rb

@@ -17,8 +17,8 @@
       expect_no_offenses('allow(foo).to receive(:bar)')
     end
 
-    include_examples 'detects style', 'allow(foo).to receive(:bar)',  'allow'
-    include_examples 'detects style', 'expect(foo).to receive(:bar)', 'expect'
+    it_behaves_like 'detects style', 'allow(foo).to receive(:bar)',  'allow'
+    it_behaves_like 'detects style', 'expect(foo).to receive(:bar)', 'expect'
   end
 
   context 'when EnforcedStyle is expect' do
@@ -37,7 +37,7 @@
       expect_no_offenses('expect(foo).to receive(:bar)')
     end
 
-    include_examples 'detects style', 'expect(foo).to receive(:bar)', 'expect'
-    include_examples 'detects style', 'allow(foo).to receive(:bar)',  'allow'
+    it_behaves_like 'detects style', 'expect(foo).to receive(:bar)', 'expect'
+    it_behaves_like 'detects style', 'allow(foo).to receive(:bar)',  'allow'
   end
 end

spec/rubocop/cop/rspec/message_spies_spec.rb

@@ -67,11 +67,11 @@
       expect_no_offenses('expect(foo).to have_received(:bar)')
     end
 
-    include_examples 'detects style', 'expect(foo).to receive(:bar)', 'receive'
+    it_behaves_like 'detects style', 'expect(foo).to receive(:bar)', 'receive'
 
-    include_examples 'detects style',
-                     'expect(foo).to have_received(:bar)',
-                     'have_received'
+    it_behaves_like 'detects style',
+                    'expect(foo).to have_received(:bar)',
+                    'have_received'
   end
 
   context 'when EnforcedStyle is receive' do
@@ -140,10 +140,10 @@
       expect_no_offenses('expect(foo).to receive(:bar)')
     end
 
-    include_examples 'detects style', 'expect(foo).to receive(:bar)', 'receive'
+    it_behaves_like 'detects style', 'expect(foo).to receive(:bar)', 'receive'
 
-    include_examples 'detects style',
-                     'expect(foo).to have_received(:bar)',
-                     'have_received'
+    it_behaves_like 'detects style',
+                    'expect(foo).to have_received(:bar)',
+                    'have_received'
   end
 end

spec/rubocop/cop/rspec/predicate_matcher_spec.rb

@@ -186,7 +186,7 @@
     context 'when strict is true' do
       let(:strict) { true }
 
-      include_examples 'inflected common'
+      it_behaves_like 'inflected common'
 
       it 'accepts strict checking boolean matcher' do
         expect_no_offenses(<<~RUBY)
@@ -203,7 +203,7 @@
     context 'when strict is false' do
       let(:strict) { false }
 
-      include_examples 'inflected common'
+      it_behaves_like 'inflected common'
 
       it 'registers an offense for a predicate method in actual' do
         expect_offense(<<~RUBY)
@@ -489,13 +489,13 @@
     context 'when strict is true' do
       let(:strict) { true }
 
-      include_examples 'explicit', 'be(true)', 'be(false)'
+      it_behaves_like 'explicit', 'be(true)', 'be(false)'
     end
 
     context 'when strict is false' do
       let(:strict) { false }
 
-      include_examples 'explicit', 'be_truthy', 'be_falsey'
+      it_behaves_like 'explicit', 'be_truthy', 'be_falsey'
     end
   end
 end

spec/rubocop/cop/rspec/subject_declaration_spec.rb

@@ -51,10 +51,10 @@
     end
   end
 
-  include_examples 'flag unclear subject declaration', :subject
-  include_examples 'flag unclear subject declaration', 'subject'
-  include_examples 'flag unclear subject declaration', :subject!
-  include_examples 'flag unclear subject declaration', 'subject!'
+  it_behaves_like 'flag unclear subject declaration', :subject
+  it_behaves_like 'flag unclear subject declaration', 'subject'
+  it_behaves_like 'flag unclear subject declaration', :subject!
+  it_behaves_like 'flag unclear subject declaration', 'subject!'
 
   context 'when subject helper is used directly' do
     it 'does not register an offense on named subject' do

spec/rubocop/rspec/hook_spec.rb

@@ -64,14 +64,14 @@ def hook(source)
       end
     end
 
-    include_examples 'standardizes scope', 'before(:each) { }',    :each
-    include_examples 'standardizes scope', 'around(:example) { }', :each
-    include_examples 'standardizes scope', 'after { }',            :each
+    it_behaves_like 'standardizes scope', 'before(:each) { }',    :each
+    it_behaves_like 'standardizes scope', 'around(:example) { }', :each
+    it_behaves_like 'standardizes scope', 'after { }',            :each
 
-    include_examples 'standardizes scope', 'before(:all) { }',     :context
-    include_examples 'standardizes scope', 'around(:context) { }', :context
+    it_behaves_like 'standardizes scope', 'before(:all) { }',     :context
+    it_behaves_like 'standardizes scope', 'around(:context) { }', :context
 
-    include_examples 'standardizes scope', 'after(:suite) { }', :suite
+    it_behaves_like 'standardizes scope', 'after(:suite) { }', :suite
   end
 
   describe '#metadata' do