The chapter shows how a long, technical, test-oriented scenario can be transformed into a concise piece of living documentation. Using the WIMP team’s old customer-collection example, it demonstrates that scenarios written for automation often accumulate irrelevant details, mixed rules, and implementation language, making them hard to read, hard to maintain, and poor at supporting shared understanding. The cleanup process becomes a collaborative learning exercise that helps the team better understand the domain as they refine the scenario.
To guide the rewrite, the chapter introduces the BRIEF principles: use business language, use real data when it clarifies intent, make the scenario intention revealing, keep only essential details, focus each scenario on a single rule, and keep it brief. The team first renames the scenario to express its purpose, then trims away unrelated order-finalization steps and incidental information like URLs, timestamps, and UI-specific labels. They replace technical terms and actions with business-oriented descriptions, turning mechanical instructions into statements of user intent.
The chapter’s main message is that scenarios should primarily communicate behavior, not test mechanics. Automation is valuable, but it is a secondary benefit; the primary goal is to produce readable, illustrative scenarios that stakeholders can discuss and evolve together. By simplifying the example and aligning it with the underlying business rule, the team creates a scenario that is easier to understand, more resilient to change, and more useful for future collaboration.
Customer-collection example map
Pay-on-collection rule
Summary
Long, complex Gherkin scenarios are common in the industry, but they are hard to read, understand, and maintain
The BRIEF acronym reminds us of six properties that a good scenario should exhibit
Example mapping is a great way of gaining a deep understanding of one aspect of a system’s behavior
We should strive to ensure that scenarios act as useful documentation to the whole team
The details included in a scenario should clarify the specification, not distract the reader
Even though scenarios are used as automated tests, they should be written with stakeholder collaboration in mind
FAQ
What is the main problem with the old scenario in this chapter?The old scenario is long, complex, and hard to read. It mixes multiple rules, includes implementation details, and creates maintenance problems instead of helping the team share understanding.What does the BRIEF acronym stand for?BRIEF stands for Business language, Real data, Intention revealing, Essential, and Focused. The chapter also emphasizes that scenarios should be Brief.Why should scenarios be treated as documentation rather than tests?Because their primary purpose is to describe and clarify expected system behavior for all stakeholders, not to exhaustively test everything. Automated testing is a useful side effect, but not the main goal.How does an example map help improve an old scenario?An example map helps the team rediscover the relevant business rules and identify which parts of the scenario matter. It provides focus so they can split, rename, or simplify the scenario based on the real behavior being illustrated.Why was “Order Test” a poor scenario name?It did not reveal the scenario’s intention. A good scenario name should describe the business behavior being illustrated, such as a customer choosing to pay on collection.What kind of details were removed because they were not essential?The team removed the URL, the time of day, the search and basket steps, and other order-finalization details that did not directly illustrate the pay-on-collection rule.Why should technical terms like BasketItemCount be avoided?Because they are implementation details from the solution domain, not business language. Replacing them with terms like “the customer has 1 item in their basket” makes the scenario easier for business and delivery teams to understand.Why is “click” considered a problem in a scenario?“Click” describes how the user interacts with the UI, which is a mechanism detail. Scenarios should reveal intent, such as “proceed to payment instructions,” instead of prescribing the interface behavior.When is it helpful to use real data in a scenario?Real data is helpful when it reveals assumptions or edge cases. If the exact value does not change the behavior, it should be replaced with a clearer, more abstract description.Why did the team change “unauthenticated customer” to just “customer”?Because the scenario’s behavior was the same regardless of authentication status. Since authentication was not relevant to the rule being illustrated, using just “customer” kept the scenario focused and communication-oriented.
pro $24.99 per month
access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
Effective Behavior-Driven Development ebook for free
