Shared Examples: it_behaves_like vs include_examples context limits

Direct answer

it_behaves_like creates a nested example group; include_examples evaluates the shared example in the host group without nesting.

How let resolution differs

• it_behaves_like: The shared block runs inside a nested group. Its let definitions are scoped to that nested group and shadow any identically named let from the host group for examples inside the shared block. The host group’s lets remain accessible via super() if needed.
• include_examples: The shared block is evaluated in the host group’s context. Any let defined in the shared block becomes a host‑group let. If the host already defines a let with the same name, the later definition wins (typically the shared block’s because include_examples is called after the host’s lets). This merges the scopes and can cause unexpected overrides or silent shadowing across the entire host group.

Failure traceability implications

Because include_examples does not introduce a nested group, RSpec’s formatter attributes failures to the shared example’s file and line, not to the specific including example group. In large suites where the same shared example is included in many groups, failures are grouped under a single shared‑example entry, making it harder to pinpoint the exact failing context.

Verification steps (minimal reproducible example)

# spec/shared_examples_spec.rb
RSpec.shared_examples 'a counter' do
  let(:start) { 0 }
  it 'starts at zero' do
    expect(start).to eq(0)
  end
end

RSpec.describe 'using it_behaves_like' do
  let(:start) { 5 }
  it_behaves_like 'a counter'   # nested group → shared let(:start) shadows host → start = 0, passes
end

RSpec.describe 'using include_examples' do
  let(:start) { 5 }
  include_examples 'a counter'   # host group → shared let(:start) overrides host → start = 0, passes
end

Run with rspec --format documentation. Observe:

• Both examples pass because the shared let(:start) { 0 } takes effect in each case (nested group shadows, flat inclusion overrides).
• Change the shared example to expect(start).to eq(5) to see the difference: the nested group will fail (sees 0), the flat inclusion will also fail (sees 0) because the shared let overrides the host let. To observe isolation, add a host‑only example that checks start; it will see 5 in the first group but 0 in the second.
• Failure backtraces for include_examples point to the shared example file, while it_behaves_like adds an extra group level in the output, making the hierarchy clearer.

When to prefer each

• Use it_behaves_like when you want isolation and clear hierarchical output.
• Use include_examples only when you intentionally want the shared code to merge with the host scope (e.g., sharing before hooks that should run in the same context) and you are confident no name clashes exist.