Merge pull request #2089 from yujideveloper/fix/mark-unsafe-autocorrect-for-include_examples

Mark `RSpec/IncludeExamples` as `SafeAutoCorrect: false`

Author: ydah

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Master (Unreleased)
 
+- Mark `RSpec/IncludeExamples` as `SafeAutoCorrect: false`. ([@yujideveloper])
+
 ## 3.6.0 (2025-04-18)
 
 - Fix false positive in `RSpec/Pending`, where it would mark the default block `it` as an offense. ([@bquorning])
@@ -1073,5 +1075,6 @@ Compatibility release so users can upgrade RuboCop to 0.51.0. No new features.
 [@ydah]: https://github.com/ydah
 [@yevhene]: https://github.com/yevhene
 [@ypresto]: https://github.com/ypresto
+[@yujideveloper]: https://github.com/yujideveloper
 [@zdennis]: https://github.com/zdennis
 [@zverok]: https://github.com/zverok

config/default.yml

@@ -535,7 +535,9 @@ RSpec/ImplicitSubject:
 RSpec/IncludeExamples:
   Description: Checks for usage of `include_examples`.
   Enabled: pending
+  SafeAutoCorrect: false
   VersionAdded: '3.6'
+  VersionChanged: "<<next>>"
   Reference: https://www.rubydoc.info/gems/rubocop-rspec/RuboCop/Cop/RSpec/IncludeExamples
 
 RSpec/IndexedLet:

docs/modules/ROOT/pages/cops_rspec.adoc

@@ -2772,9 +2772,9 @@ it { expect(named_subject).to be_truthy }
 
 | Pending
 | Yes
-| Always
+| Always (Unsafe)
 | 3.6
-| -
+| <<next>>
 |===
 
 Checks for usage of `include_examples`.
@@ -2786,6 +2786,60 @@ unexpected behavior and side effects.
 
 Prefer using `it_behaves_like` instead.
 
+----
+
+[#safety-rspecincludeexamples]
+=== Safety
+
+`include_examples` and `it_behaves_like` have different scoping
+behaviors.
+Changing `include_examples` to `it_behaves_like` creates a new
+context, altering setup dependencies, which can lead to unexpected
+test failures.
+Specifically, the scope of hooks (`before`, `after`, `around`)
+changes, which may prevent expected setup from being inherited
+correctly.
+
+Additionally, `let` and `subject` are affected by scoping rules.
+When `include_examples` is used, `let` and `subject` defined within
+`shared_examples` are evaluated in the caller's context, allowing
+access to their values.
+In contrast, `it_behaves_like` creates a new context, preventing
+access to `let` or `subject` values from the caller's context.
+
+[source,ruby]
+----
+shared_examples "mock behavior" do
+  before do
+    allow(service).to receive(:call).and_return("mocked response")
+  end
+
+  it "returns mocked response" do
+    expect(service.call).to eq "mocked response"
+  end
+end
+
+context "working example with include_examples" do
+  let(:service) { double(:service) }
+
+  include_examples "mock behavior"
+
+  it "uses the mocked service" do
+    expect(service.call).to eq "mocked response" # Passes
+  end
+end
+
+context "broken example with it_behaves_like" do
+  let(:service) { double(:service) }
+
+  it_behaves_like "mock behavior"
+
+  it "unexpectedly does not use the mocked service" do
+    # Fails because `it_behaves_like` does not apply the mock setup
+    expect(service.call).to eq "mocked response"
+  end
+end
+
 [#examples-rspecincludeexamples]
 === Examples
 

lib/rubocop/cop/rspec/include_examples.rb

@@ -12,6 +12,57 @@ module RSpec
       #
       # Prefer using `it_behaves_like` instead.
       #
+      # @safety
+      #   `include_examples` and `it_behaves_like` have different scoping
+      #   behaviors.
+      #   Changing `include_examples` to `it_behaves_like` creates a new
+      #   context, altering setup dependencies, which can lead to unexpected
+      #   test failures.
+      #   Specifically, the scope of hooks (`before`, `after`, `around`)
+      #   changes, which may prevent expected setup from being inherited
+      #   correctly.
+      #
+      #   Additionally, `let` and `subject` are affected by scoping rules.
+      #   When `include_examples` is used, `let` and `subject` defined within
+      #   `shared_examples` are evaluated in the caller's context, allowing
+      #   access to their values.
+      #   In contrast, `it_behaves_like` creates a new context, preventing
+      #   access to `let` or `subject` values from the caller's context.
+      #
+      #   [source,ruby]
+      #   ----
+      #   shared_examples "mock behavior" do
+      #     before do
+      #       allow(service).to receive(:call).and_return("mocked response")
+      #     end
+      #
+      #     it "returns mocked response" do
+      #       expect(service.call).to eq "mocked response"
+      #     end
+      #   end
+      #
+      #   context "working example with include_examples" do
+      #     let(:service) { double(:service) }
+      #
+      #     include_examples "mock behavior"
+      #
+      #     it "uses the mocked service" do
+      #       expect(service.call).to eq "mocked response" # Passes
+      #     end
+      #   end
+      #
+      #   context "broken example with it_behaves_like" do
+      #     let(:service) { double(:service) }
+      #
+      #     it_behaves_like "mock behavior"
+      #
+      #     it "unexpectedly does not use the mocked service" do
+      #       # Fails because `it_behaves_like` does not apply the mock setup
+      #       expect(service.call).to eq "mocked response"
+      #     end
+      #   end
+      # ----
+      #
       # @example
       #   # bad
       #   include_examples 'examples'