In RSpec, when should a spec use it_behaves_like rather than include_examples, and how does shared_context differ from shared_examples?

## Stored blocks, evaluated on inclusion A **shared group** is a named block that RSpec stores when it is defined and evaluates later, inside whichever example group includes it. Nothing in it runs at definition time. ```ruby RSpec.shared_examples "a list that deduplicates" do |item| let(:entry) { item } it "keeps one #{item}" do 2.times { list.add(entry) } expect(list.items.count(entry)).to eq(1) end end RSpec.describe ShoppingList do let(:list) { ShoppingList.new } it_behaves_like "a list that deduplicates", "milk" it_behaves_like "a list that deduplicates", "eggs" end ``` The shared block reads `list` from the including group: the host provides the context, the shared group provides the behaviour. ## The ways to include one | Call | Where the block is evaluated | Typical content | |---|---|---| | `it_behaves_like name, *args` | a **new nested group**, described "behaves like name" | examples | | `it_should_behave_like name, *args` | a new nested group, described "it should behave like name" | examples | | `include_examples name, *args` | the **current** group | examples | | `include_context name, *args` | the **current** group | `let`, hooks, helper methods | All four accept extra arguments, passed to the block's parameters, and an optional block that is evaluated in the target group after the shared content, which lets the caller override a `let` for that inclusion only. ## Why include_examples twice goes wrong Because `include_examples` evaluates the block in the current group, every `let` it defines becomes a method **of that group**. Including the same parameterized examples twice defines `let(:entry)` twice in one class: 1. The first inclusion defines `entry` as "milk" and adds an example titled "keeps one milk". 2. The second defines `entry` again as "eggs" and adds "keeps one eggs". 3. Methods on one class have one definition, so the second wins; the example titled "keeps one milk" now actually tests eggs. Interpolated titles still come from the block parameter, so the output looks right while the first example checks the wrong value. `it_behaves_like` avoids this: each call builds its own nested subclass, so each has its own `entry`. ## shared_context versus shared_examples In rspec-core, `shared_context` and `shared_examples_for` are **aliases** of `shared_examples`. The name signals intent: - A **shared context** carries setup: `let` definitions, `before` hooks, helper `def`s. It is included with `include_context`, so the setup lands in the current group and its own examples use it directly. - **Shared examples** carry examples, usually included with `it_behaves_like` so each set gets its own group in the output. Shared contexts can also be attached automatically to every group with matching metadata; that wiring belongs to runner configuration rather than to the group DSL. ## Parameters and customization blocks Shared groups can be written two ways, and the choice changes how readable the inclusion site is: - **Block parameters**: `shared_examples "a list that deduplicates" do |item|` receives the extra arguments of `it_behaves_like`. Everything the shared group needs is visible at the call site. - **Host `let`s**: the shared block calls `list` and trusts the including group to define it. This is shorter but hides a dependency; a group that forgets the `let` fails with `NameError` from inside the shared file. - **Customization block**: `it_behaves_like "a list that deduplicates", "milk" do let(:list) { ShoppingList.new(limit: 5) } end` evaluates the block in the nested group after the shared content, overriding that `let` for this inclusion only. ## Scoping and loading - A shared group defined at the top level (`RSpec.shared_examples`) is visible everywhere. One defined inside an example group is visible to that group and its descendants, not to parents or siblings. - RSpec does not autoload shared groups. The file defining them must be loaded before the spec that uses them, typically from a support directory required in the helper file. - Including a name RSpec cannot find raises `ArgumentError` ("Could not find shared examples"), so a typo fails loudly at load time. ## Common misuse - Shared examples that silently depend on a dozen host `let`s nobody documented. Pass what they need as parameters, or fail fast with a clear message. - Using shared examples to avoid writing two lines twice. Duplication in specs is cheaper than indirection a reader must chase across files. - Choosing `include_examples` for parameterized examples included more than once in the same group.