Chapter 7: Cleaning up an old scenario
The introduction explains why cleaning up long, complex, unreadable scenarios is worthwhile.
After this chapter you will be able to
- Value of cleaning up scenarios. Explain why a team should clean up a long, complex, unreadable scenario.
- Old scenario maintenance problems. Explain why the team's single customer-collection scenario is difficult to read and maintain: it is long, covers many rules rather than illustrating one, and makes failures hard to diagnose.
- Gherkin fluency and practice. Explain why being able to learn Gherkin quickly does not mean someone can immediately write good scenarios.
- Descriptive Scenario Documentation. Explain why scenarios are written as documentation that illustrates and clarifies expected behavior, rather than as exhaustive tests.
- Shared Scenario Understanding. Explain how scenarios should support collaboration between business and delivery by being understandable to everyone contributing to the system.
- Change Resilient Scenarios. Explain why a scenario illustrating one specific behavior should remain unchanged when unrelated behavior changes.
- Business language in scenarios. Explain why scenarios should use terminology from the business domain rather than language unfamiliar to business stakeholders.
- Real data for clarity. Explain when real data belongs in a scenario and what concrete examples can reveal.
- Intention revealing scenario wording. Describe how a scenario’s name and lines should express what its actors aim to achieve rather than how they achieve it.
- Essential details of a rule. Explain which details to retain in a scenario and how to treat details or scenarios that do not clarify its rule.
- Single rule scenario focus. Explain what a focused illustrative scenario should show and how workshop examples can help achieve that focus.
- Brief scenario length. State the suggested length for most scenarios and explain its benefit.
- Example mapping for focus. Explain why the team creates an example map before editing the old customer-collection scenario, and how it helps them decide what matters in that scenario.
- Single rule and outcome. Trace how the team refocuses the scenario on the pay-on-collection rule by identifying its expected outcome and removing unrelated finalization steps.
- Essential scenario context. Explain why the team removes the pizza-search and basket steps, application URL, and time of day from the scenario.
- Business concepts over technical names. Explain why a scenario should name business concepts rather than implementation elements, using BasketItemCount as an example.
- User intentions over interface mechanics. Explain why scenario steps should describe what the user intends rather than mechanics such as clicking, and how that keeps the specification independent of the UI.
- Relevant real data. Explain when actual data helps a scenario and when to replace it with a descriptive term.
- Implicit basket context. Explain why the team removes the basket precondition from the pay-on-collection scenario.
- Documentation over test coverage. Explain why the team accepts a scenario that does not explicitly test both authenticated and unauthenticated customers: its main purpose is to document the shared behavior, not to serve as a test of every variation.
- Authentication status in wording. Describe when the scenario should say “customer” rather than specify an authenticated or unauthenticated customer, and distinguish that wording from the choice automation code will still have to make.
- Stakeholder collaboration through scenarios. Explain why scenarios are written in natural language and why readability matters more than their ability to become automated tests.
- Single rule illustrative scenarios. Describe how a concrete example gives an illustrative scenario its focus and makes its importance clear.
- Brevity through domain abstractions. Explain why illustrative scenarios should be brief and how business domain abstractions help keep them maintainable.
What it builds on
- Rules vs. examples (chapter 3) · The distinction between rules and examples.
- Gherkin overview (chapter 6) · An overview of Gherkin scenario language.
- Living documentation (chapter 6) · The idea of scenarios as living documentation.
- Shared understanding (chapter 6) · The importance of shared understanding.
- How hard is concrete? (chapter 3) · The earlier discussion of concrete examples.
- Example Mapping in a nutshell (chapter 2) · The earlier introduction to Example Mapping.
- Deliberate discovery (chapter 2) · The idea of deliberate discovery.
Section by section
Introduction
The introduction explains why cleaning up long, complex, unreadable scenarios is worthwhile.
- Value of cleaning up scenarios: Explain why a team should clean up a long, complex, unreadable scenario.
Why it matters: The point of improving a scenario is not just to shorten it, but to make it more useful to the team.
Key terms: shared understanding, maintenance efforts, domain
7.1 The old scenario
The section introduces an old customer-collection scenario and explains why its test-focused, hard-to-read form makes it a poor aid to collaboration.
- Old scenario maintenance problems: Explain why the team's single customer-collection scenario is difficult to read and maintain: it is long, covers many rules rather than illustrating one, and makes failures hard to diagnose.
Why it matters: Recognizing what makes the old scenario unhelpful gives the team a reason to improve it. - Scenario keywords and readability: Distinguish what mattered to the automation tool from why the team uses Given, When, Then, and And: the tool makes little distinction between those keywords, but their use should help people read the scenario.
Why it matters: A scenario can run as an automated test yet still be difficult for people to read.
Key terms: scenario, rule, customer-collection, Given, When, Then, And, automated regression test
7.2 Keep your scenarios BRIEF
This introduction distinguishes how easy Gherkin is to learn from the practice needed to write scenarios well.
- Gherkin fluency and practice: Explain why being able to learn Gherkin quickly does not mean someone can immediately write good scenarios.
Why it matters: Knowing the syntax is a starting point, not the same as writing effective scenarios.
Key terms: Gherkin, scenarios
7.2.1 The goals
This section sets three goals for scenarios: clarify expected behavior, support collaboration, and remain useful as the product evolves.
- Descriptive Scenario Documentation: Explain why scenarios are written as documentation that illustrates and clarifies expected behavior, rather than as exhaustive tests.
Why it matters: This purpose helps keep scenarios focused on communicating behavior. - Shared Scenario Understanding: Explain how scenarios should support collaboration between business and delivery by being understandable to everyone contributing to the system.
Why it matters: A scenario that contributors can understand gives them a shared basis for discussing behavior. - Change Resilient Scenarios: Explain why a scenario illustrating one specific behavior should remain unchanged when unrelated behavior changes.
Why it matters: Keeping a scenario tied to the behavior it illustrates prevents unrelated product changes from making its documentation needlessly unstable.
Key terms: documentation, expected behavior, descriptive, not exhaustive, collaboration, business and delivery, evolution of the product, specific behavior, unrelated behavior
7.2.2 The principles
This section explains six BRIEF principles for writing scenarios that communicate business behavior clearly and concisely.
- Business language in scenarios: Explain why scenarios should use terminology from the business domain rather than language unfamiliar to business stakeholders.
Why it matters: Shared language makes scenarios useful to the whole delivery team. - Real data for clarity: Explain when real data belongs in a scenario and what concrete examples can reveal.
Why it matters: Concrete data can make an intended behavior clearer and reveal assumptions before they cause problems. - Intention revealing scenario wording: Describe how a scenario’s name and lines should express what its actors aim to achieve rather than how they achieve it.
Why it matters: Readers can understand the behavior without having to decipher the steps used to implement it. - Essential details of a rule: Explain which details to retain in a scenario and how to treat details or scenarios that do not clarify its rule.
Why it matters: Removing incidental material helps stakeholders see the rule the scenario is meant to illustrate. - Single rule scenario focus: Explain what a focused illustrative scenario should show and how workshop examples can help achieve that focus.
Why it matters: A single-rule focus makes it clearer what behavior each scenario illustrates. - Brief scenario length: State the suggested length for most scenarios and explain its benefit.
Why it matters: Short scenarios are easier for readers to follow and discuss.
Key terms: Business language, business domain, Real data, boundary conditions, underlying assumptions, Intention revealing, intent, mechanics, Essential, incidental
7.3 Using example maps to provide focus
The section shows how an example map helps a team rediscover existing behavior and refocus an old scenario on one clearly named rule and outcome.
- Example mapping for focus: Explain why the team creates an example map before editing the old customer-collection scenario, and how it helps them decide what matters in that scenario.
Why it matters: Checking what the system actually does gives the team a sound basis for deciding what the scenario should illustrate. - Intention revealing scenario name: Describe how the team chooses a name that expresses the scenario’s intention in language familiar to business colleagues.
Why it matters: A name that says what the example is about makes the scenario easier for business colleagues to read and discuss. - Single rule and outcome: Trace how the team refocuses the scenario on the pay-on-collection rule by identifying its expected outcome and removing unrelated finalization steps.
Why it matters: Keeping only the steps that illustrate the rule makes the scenario’s point easier to see.
Key terms: example map, customer collections, lift and shift, intention revealing, business language, authenticated, unauthenticated, pay-on-collection rule, expected outcome, Then
7.4 Document the essence of the behavior
The team trims an old scenario to highlight the pay-on-collection rule and prioritizes clear documentation over preserving its existing automation.
- Essential scenario context: Explain why the team removes the pizza-search and basket steps, application URL, and time of day from the scenario.
Why it matters: A short scenario gives readers a clearer basis for discussing the behavior it specifies. - Documentation before automation repair: Explain why the team accepts that the edit will break existing automation and postpones fixing it.
Why it matters: Existing automation need not dictate the wording of a scenario being improved for readers.
Key terms: Essential, Brief, incidental details, pay-on-collection rule, existing automation, essence of the expected behavior
7.5 Scenarios should read like a specification
The section shows how to make a scenario read like a specification by replacing implementation details with business language and descriptions of user intent.
- Business concepts over technical names: Explain why a scenario should name business concepts rather than implementation elements, using BasketItemCount as an example.
Why it matters: Business language lets readers understand the behavior without knowing how the interface is built. - User intentions over interface mechanics: Explain why scenario steps should describe what the user intends rather than mechanics such as clicking, and how that keeps the specification independent of the UI.
Why it matters: Describing intent keeps the scenario useful even if the interface or checkout flow changes.
Key terms: business language, solution domain, problem domain, BasketItemCount, intention revealing, click, UI, pay-on-collection rule
7.6 Use real data when it provides clarity
The section shows how to make a scenario clearer by replacing irrelevant real data and removing context already implied by the remaining steps.
- Relevant real data: Explain when actual data helps a scenario and when to replace it with a descriptive term.
Why it matters: Readers should be able to see which details clarify the rule rather than hunt for significance in incidental numbers. - Implicit basket context: Explain why the team removes the basket precondition from the pay-on-collection scenario.
Why it matters: Removing an implied step keeps attention on the rule this scenario is meant to communicate.
Key terms: real data, actual data, abstract, descriptive term, payment instructions, pay-on-collection rule, implicit statement, Given
7.7 Communication, not testing
The team revises a customer-collection scenario to communicate the behavior it illustrates without specifying an authentication status that does not affect that behavior.
- Documentation over test coverage: Explain why the team accepts a scenario that does not explicitly test both authenticated and unauthenticated customers: its main purpose is to document the shared behavior, not to serve as a test of every variation.
Why it matters: This distinction helps keep a scenario focused on what readers need to understand about the behavior. - Authentication status in wording: Describe when the scenario should say “customer” rather than specify an authenticated or unauthenticated customer, and distinguish that wording from the choice automation code will still have to make.
Why it matters: Naming only distinctions that affect behavior makes the scenario’s intention clearer without prematurely settling automation details.
Key terms: scenario, document behavior, authenticated customer, unauthenticated customer, customer, automation code
7.8 Illustrative scenarios
The section explains how illustrative scenarios support stakeholder collaboration and learning, and how to keep them focused and maintainable while using AI as an aid rather than a substitute for human formulation.
- Stakeholder collaboration through scenarios: Explain why scenarios are written in natural language and why readability matters more than their ability to become automated tests.
Why it matters: A scenario is most useful when everyone involved can discuss what it means. - Single rule illustrative scenarios: Describe how a concrete example gives an illustrative scenario its focus and makes its importance clear.
Why it matters: A focused example helps reviewers see the behavior the scenario is there to illustrate. - Brevity through domain abstractions: Explain why illustrative scenarios should be brief and how business domain abstractions help keep them maintainable.
Why it matters: Brief, domain-focused scenarios are easier to review and less likely to need rewriting when implementation details change. - AI assistance with human formulation: Describe useful ways AI can assist with formulation and explain why the team should not hand it the entire task of generating scenarios.
Why it matters: Using AI for feedback preserves the human learning and scrutiny that formulation provides. - Learning from scenario refinement: Justify spending time refining one scenario even when producing that scenario seems slow.
Why it matters: Time spent clarifying one scenario can improve the team's understanding and speed up the next ones.
Key terms: natural language, stakeholders, scenario automation tools, concrete example, single rule, illustrative scenarios, brevity, business domain abstractions, implementation details, AI
7.9 Summary
Where this is used later
- Keywords (chapter 8) · The discussion of Gherkin keywords builds on their role in readable scenarios.
- Conflicting goals (chapter 11) · The BRIEF principles for illustrative scenarios
- Shortcuts (chapter 12) · The BRIEF principles for concise, intention-revealing scenarios
- (chapter intro) (chapter 14) · The BRIEF essential principle for keeping scenarios focused.
- Keeping context essential (chapter 8) · The BRIEF principle of including only essential detail.
- A sample feature file (chapter 8) · The example map used to focus the replacement scenarios.
- Rules (chapter 8) · The association between rules and illustrative examples in an example map.
- BDD on legacy projects (chapter 11) · The earlier use of example maps to focus scenarios.
Concepts explained in this chapter
- ubiquitous languageA shared vocabulary used by domain experts and software practitioners to describe business concepts and system behavior consistently.
- BRIEFA mnemonic framework of principles for writing clear, maintainable behavior scenarios.
- scenarioA business-readable description of an example system behavior and its expected outcome.
- example mapAn example map is a visual arrangement of examples and their associated rules for examining how a system should behave in different situations.
- illustrative scenarioA concrete narrative describing a representative situation, context, and expected behavior for a business requirement.
- collaborationCollaboration is a cooperative working relationship in which relevant participants jointly discover, formulate, and refine software behavior.
- documentationDocumentation is recorded information describing a system and its behavior for reference and maintenance.
- incidental detailInformation in a scenario that is unnecessary to convey the behavior or rule being illustrated.
- essential principleA scenario-writing principle that removes details that do not contribute directly to illustrating the behavior of a rule.
- concrete dataConcrete values representing the entities, states, or inputs involved in a scenario rather than abstract placeholders or general description.
- business ruleA business constraint governing payment when a customer collects an order.
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.
