13 Spotlight patterns for automating narrative flow

BDD scenarios are presented as cohesive business narratives, not as isolated technical steps, so the chapter focuses on automation patterns that preserve readability while allowing steps to share knowledge. The main idea is to keep the important entities, actions, and outcomes “in the spotlight” so the scenario stays concise, natural, and focused on the behavior being demonstrated. Rather than forcing every step to be self-contained, the automation should reflect the flow of the story and support reuse of step definitions as building blocks.

To achieve this, the chapter first introduces scenario context as a temporary memory that exists only for the lifetime of one scenario execution. A simple form of this is storing data in instance fields of a step definition class, which works when related steps live in the same class, while avoiding static fields that would break isolation and cause flaky tests. When multiple step definition classes need access to the same information, a shared context object can be injected through dependency injection, allowing data such as the logged-in customer to be passed safely between classes without compromising scenario independence.

The chapter then expands the idea of narrative flow with explicit language for introducing and referring to entities. It recommends using different phrases for newly introduced entities versus already known ones, and shows how custom parameter types can support flexible references like “the order,” “the placed order,” or even “they” when the meaning is unambiguous. For more complex cases, where a scenario must choose one item from a collection, the Entity Selector pattern lets business language trigger domain logic such as selecting the earliest order, making scenarios more readable and step definitions more reusable while keeping the automation aligned with the story the scenario tells.

Class diagram showing constructor injection of shared context class

• Step definitions are expected to be reusable in many scenarios.
• Step definitions are not expected to be context independent. They should be designed to rely on knowledge already present in the scenario’s execution context.
• BDD execution frameworks provide mechanisms for ensuring that the scenario’s execution context is started afresh at the beginning of each scenario execution. Without this guarantee of isolation the outcome of a scenario might depend on the order that the scenarios are run in.
• The Shareable scenario context and Local scenario context patterns help automate context-aware steps by providing standardized ways to share and interact with the scenario execution context.
• Scenarios specify the expected behavior by describing how actors perform their tasks by interacting with various elements of the domain. We use the generic term, entity, to refer to any actor or domain element in a scenario.
• The Introduce and refer pattern helps keep scenarios readable by suggesting phrases that distinguish between a new entity being introduced and an existing entity being referred to.
• The Entity selector pattern is used to extend custom parameter type definitions to support relevant domain phrases (e.g., “latest order”). These phrases are resolved by querying the scenario context or other data sources.

FAQ