Question
Difference between it_behaves_like and include_examples for shared examples
Sky Vale
0 reputation · 07 Apr 2021, 02:18 UTC
27.9K views1
Loading…
0 reputation · 07 Apr 2021, 02:18 UTC
When implementing DRY test suites in RSpec, shared examples can be integrated into a spec using either it_behaves_like or include_examples. While both methods allow for the reuse of common expectations, they handle the execution context and documentation output differently.
The primary goal is to determine the optimal method for maintaining clean failure traces and readable documentation without sacrificing state isolation. There is uncertainty regarding how the lack of a nested context in include_examples impacts the visibility of the subject and the resulting output in the RSpec documentation formatter.
include_examples impact the isolation of the test state compared to the nested group created by it_behaves_like?subject defined in the parent context?34775 reputation · 07 Apr 2021, 10:47 UTC
State isolation is identical for both methods. Neither creates a new example instance or resets let/subject memoization; they only differ in documentation nesting. Use it_behaves_like when you want the shared behavior to appear as a named sub-group in documentation output (making dependencies on parent subject explicit). Use include_examples for a flat example list when the shared examples are implementation details that don't warrant a separate heading.
rspec
rubyit_behaves_like "shared name" wraps the shared examples in a nested example group. The documentation formatter (rspec --format documentation) shows them indented under a descriptive header.include_examples "shared name" injects examples directly into the current example group. Output is flat with no additional nesting level.subject defined in the parent context if that subject exists before the inclusion call. Neither provides stronger isolation—before/after hooks and memoized let values share the same outer context.it_behaves_like when:subject and you want that dependency visible in the documentation hierarchy.include_examples when:Run these commands in your spec directory to observe the difference:
# Compare documentation output
rspec --format documentation spec/your_spec.rb
# Confirm identical example count
rspec --format progress spec/your_spec.rb
# Test subject resolution: temporarily comment out the parent subject
# and verify both inclusion styles fail with the same error
shared_examples DSL. Behavior may differ in RSpec 2.x or future 4.x releases.subject is defined after the inclusion call or inside a nested context not visible to the shared examples. This applies equally to both methods.let memoization and hook ordering follow the outer example group.If your shared examples reference a subject that is defined in a before(:context) hook or lazily via let(:subject), confirm whether that definition runs before the inclusion point. The resolution behavior is the same for both methods, but the failure mode differs only in output formatting.
Use comments to ask for clarification. Post a solution as an answer.
5,540 reputation · 07 Apr 2021, 07:57 UTC
In RSpec 3.4+ include_examples is an alias for it_behaves_like that skips the automatic nested group. The shared examples still run in the same example instance, so let and subject memoization are identical. The only visible difference is the formatter output: it_behaves_like creates a child describe block titled by the shared example name, while include_examples injects the examples directly into the current group, flattening the hierarchy. Both helpers expose the parent subject if it is defined before the inclusion call.
When a shared example relies on a subject defined deeper in the hierarchy, using include_examples inside a context that overrides that subject can lead to confusing failures, because the override is inherited by the inline examples. In such cases it_behaves_like makes the dependency explicit by nesting the examples.