Chapter 13: Spotlight patterns for automating narrative flow
This introduction explains why automated scenario steps should work together to preserve a focused business narrative.
After this chapter you will be able to
- Cohesive scenario execution. Explain how individually executed step definitions work together to automate a connected scenario, and why sharing information between steps can avoid repetition.
- Focused business narrative. Describe how a scenario puts essential characters, situations, or entities in the spotlight to illustrate an expected behavior and outcome.
- Local Scenario Context pattern. Explain how a later step definition can use information introduced by an earlier step definition in the same class, such as an order number stored when an order is placed.
- Scenario execution isolation. Explain why an instance field does not pass data to another scenario execution, and why a static field is unsafe for this purpose.
- Cross-class scenario information. Explain when Shareable Scenario Context is needed and why a step definition’s instance field is not enough.
- Injected context lifetime. Describe how step definition classes receive a context object and how its lifetime preserves scenario isolation.
- Introduction and reference phrases. Explain how separate natural-language phrases distinguish a newly introduced entity from one already known in a scenario, and why that distinction makes the scenario clearer.
- Scenario context and narrative knowledge. Trace how a step definition can store an introduced entity in scenario context for later steps, and explain why context must reflect what the scenario text has made known.
- Pronoun step matching. Explain how a scenario step can refer to an authenticated customer as “they,” why a custom parameter type is preferable to a Cucumber Expression alternation, and what to do if custom parameter types are unavailable.
- Unambiguous generic references. Explain why a generic reference such as “it” can make a step ambiguous, and state when such references should be introduced.
- Single and named order references. Explain why “the order” is clear when a scenario focuses on one order but ambiguous when it involves two, and describe how the Given step supports both kinds of scenario.
- Business-readable entity selection. Explain why the Entity Selector pattern uses phrases such as “the earliest order” instead of order numbers when a scenario involves multiple entities. Describe how it specializes Introduce and Refer by selecting an entity through logic rather than referring to a predefined context entry.
- Selector resolution in automation. Trace how the example resolves “the earliest order received”: the placed orders are stored in scenario context, the {order} parameter type matches the step text and invokes the appropriate transformation, and the earliest order’s number reaches the step definition. State that a selector can also obtain entities from another source.
What it builds on
- Step definitions (chapter 12) · Introduces step definitions as the code associated with scenario steps.
- Document the essence of the behavior (chapter 7) · Addresses documenting the essence of a behavior in a scenario.
- Isolated scenarios (chapter 12) · Scenarios should be isolated from one another.
- Scenarios should read like a specification (chapter 7) · Scenarios should read like specifications.
- Custom parameter types (chapter 12) · Custom parameter types used in scenario automation.
- Matching steps to step definitions (chapter 12) · How steps are matched to step definitions.
Section by section
Introduction
This introduction explains why automated scenario steps should work together to preserve a focused business narrative.
- Cohesive scenario execution: Explain how individually executed step definitions work together to automate a connected scenario, and why sharing information between steps can avoid repetition.
Why it matters: Thinking of steps as parts of one flow helps keep the automation aligned with the scenario’s story. - Focused business narrative: Describe how a scenario puts essential characters, situations, or entities in the spotlight to illustrate an expected behavior and outcome.
Why it matters: Focusing on consequential details makes the intended behavior easier for readers to follow.
Key terms: step definition, scenario execution, Local Scenario Context, Shareable Scenario Context, business narrative, spotlight, essential details, expected outcome
13.1 Local Scenario Context pattern: learning to remember
This section explains how Local Scenario Context lets steps in the same glue code class remember information without repeating it in the scenario or sharing it with other executions.
- Local Scenario Context pattern: Explain how a later step definition can use information introduced by an earlier step definition in the same class, such as an order number stored when an order is placed.
Why it matters: Remembering an earlier step’s information lets the automation follow the scenario’s narrative. - Scenario execution isolation: Explain why an instance field does not pass data to another scenario execution, and why a static field is unsafe for this purpose.
Why it matters: Isolation prevents one scenario’s stored data from changing another scenario’s result. - Readable context-aware scenarios: Explain why remembering information from earlier steps can make a scenario easier to read and its steps more reusable.
Why it matters: Less repetition helps scenarios remain readable as business specifications rather than collections of self-contained steps.
Key terms: Local Scenario Context, step definition, instance field, glue code class, scenario context, scenario execution context, world, instance fields, static fields, context-independent
13.2 Shareable Scenario Context pattern: sharing data between step definitions in different classes
This section explains how Shareable Scenario Context lets step definitions in different classes share information during one scenario without leaking it into another.
- Cross-class scenario information: Explain when Shareable Scenario Context is needed and why a step definition’s instance field is not enough.
Why it matters: It lets steps tell a connected story even when their automation lives in different classes. - Injected context lifetime: Describe how step definition classes receive a context object and how its lifetime preserves scenario isolation.
Why it matters: Sharing data within a scenario must not let one scenario change another’s outcome. - Context contents and grouping: Explain what belongs in an injectable context class and when to introduce or group such classes.
Why it matters: A context stays easier to use when its data is grouped sensibly and shared only where necessary. - Derived data storage tradeoff: Distinguish storing an identifier from storing derived data in scenario context, including the tradeoff described here.
Why it matters: The choice of what to store affects both lookup cost and the reliability of later steps’ data.
Key terms: Shareable Scenario Context, step definition, context class, instance fields, scenario isolation, dependency injection, scenario lifetime scope, constructor injection, property injection, scenario context
13.3 Introduce and Refer pattern: separating introduction and reference
This section explains how the Introduce and Refer pattern keeps a scenario’s wording and automation aligned when an entity first appears and is mentioned again.
- Introduction and reference phrases: Explain how separate natural-language phrases distinguish a newly introduced entity from one already known in a scenario, and why that distinction makes the scenario clearer.
Why it matters: Clear references help readers follow the scenario without guessing which entity a step describes. - Scenario context and narrative knowledge: Trace how a step definition can store an introduced entity in scenario context for later steps, and explain why context must reflect what the scenario text has made known.
Why it matters: Keeping stored context in step with the story prevents automation from silently assuming things the scenario has not established. - Varied forms of introduction: Distinguish an entity’s introduction from the use of an indefinite article or the creation of a new domain object.
Why it matters: Recognizing introductions by meaning lets the pattern work with varied phrasing and with entities that already exist. - Flexible order reference matching: Describe how the section accommodates different phrases for the same order in step definitions, including what an {order} custom parameter type does.
Why it matters: One parameter type can support natural variations in scenario wording without repeating those variations in every step definition.
Key terms: Introduce and Refer pattern, entity, introduction, reference, scenario context, step definition, authenticated customer, indefinite article, introduction step, Cucumber Expression
13.3.1 What about “they”?
This subsection explains how to use pronouns in scenario steps while keeping step definitions matchable and unambiguous.
- Pronoun step matching: Explain how a scenario step can refer to an authenticated customer as “they,” why a custom parameter type is preferable to a Cucumber Expression alternation, and what to do if custom parameter types are unavailable.
Why it matters: This lets scenarios use readable pronouns without requiring separate automation methods for each phrasing. - Unambiguous generic references: Explain why a generic reference such as “it” can make a step ambiguous, and state when such references should be introduced.
Why it matters: A readable pronoun is useful only if the automation tool can still identify the intended step definition.
Key terms: custom parameter types, Cucumber Expression alternations, multiple expressions, they, generic reference terms, context insensitive, ambiguous, it
13.3.2 Referring to more than one entity?
Explains how a step definition can support references to one order in a single-order scenario and distinguish orders in a multi-order scenario.
- Single and named order references: Explain why “the order” is clear when a scenario focuses on one order but ambiguous when it involves two, and describe how the Given step supports both kinds of scenario.
Why it matters: It lets the same Given step work when a scenario refers to either one order or multiple orders.
Key terms: the order, the completed order, scenario context, CurrentOrder, CompletedOrder
13.4 Entity Selector pattern: selecting entities by phrases
This section explains how the Entity Selector pattern keeps scenarios readable by resolving phrases such as “the earliest order received” to an entity through selection logic.
- Business-readable entity selection: Explain why the Entity Selector pattern uses phrases such as “the earliest order” instead of order numbers when a scenario involves multiple entities. Describe how it specializes Introduce and Refer by selecting an entity through logic rather than referring to a predefined context entry.
Why it matters: The scenario can say which order matters in business terms without making readers track order numbers. - Selector resolution in automation: Trace how the example resolves “the earliest order received”: the placed orders are stored in scenario context, the {order} parameter type matches the step text and invokes the appropriate transformation, and the earliest order’s number reaches the step definition. State that a selector can also obtain entities from another source.
Why it matters: The same readable selector can be reused in steps such as cancelling the earliest order. - Readability versus correctness: Distinguish the Entity Selector pattern’s readability purpose from verification of the underlying logic, and explain the recommendation for dedicated unit tests.
Why it matters: Readable scenarios should not be mistaken for proof that the logic selecting an entity is correct.
Key terms: Entity Selector pattern, Introduce and Refer pattern, entity selectors, scenario context, {order} custom parameter type, [StepArgumentTransformation], ConvertEarliestOrder, step definition, scenario readability, dedicated unit tests
13.5 Summary
Where this is used later
- Skippable Reset pattern: do not reset database after read-only scenario executions (chapter 18) · Scenario context and the isolation concern associated with static fields.
- Automating though an outer interface (chapter 15) · Shareable scenario context makes data available across step definitions.
- Scenario Resource pattern: managing test resources (chapter 16) · Shareable scenario context for step definitions.
- Ensure pattern: managing implicit dependencies (chapter 16) · Shareable scenario context used by step definitions
- (chapter intro) (chapter 17) · Introducing and referring to entities relevant to a scenario.
- In-place Persona pattern: persona definitions in feature files (chapter 17) · Introducing an entity and referring to it later in a scenario.
Concepts explained in this chapter
- local scenario contextA scenario-execution pattern that stores information in the local context so later steps can share it without repeating it.
- introduce and refer patternA narrative pattern that distinguishes introducing a new entity from referring to an existing entity through specific natural-language phrases.
- execution contextScenario-scoped state and information available to steps during one scenario execution.
- shareable scenario context patternA scenario-execution pattern for sharing information between steps during a scenario.
- entity selector patternA pattern that uses business-readable phrases to invoke automation code applying domain logic to select an appropriate entity.
- context classA simple injectable class that groups and stores data belonging to a scenario's execution context.
- parameter typeA user-defined parameter type that matches captured text and converts it into a value for a step definition.
- test isolationThe principle that each scenario should run independently, without interference from other scenarios or shared state.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
