Overview

7 Cleaning up an old scenario

In this chapter, the team examines an old, overly long Gherkin scenario from the WIMP application and uses it as a learning exercise rather than treating it as a finished test case. The original scenario is hard to read, mixes keywords, includes implementation details, and tries to cover too many behaviors at once. By working through it together, the team not only improves the scenario but also deepens their understanding of the customer-collection and pay-on-collection behavior in the domain.

To clean up the scenario, the team applies the BRIEF principles: use business language, use real data only when it clarifies intent, reveal the purpose of the behavior, keep only essential details, focus on a single rule, and keep the scenario brief. They rename the scenario to better describe its purpose, remove unrelated checkout steps, replace technical UI terms with business-friendly wording, and eliminate data and context that do not help explain the rule. Along the way, they see that good scenarios should read like specification, not like automated test scripts.

The chapter emphasizes that scenarios are primarily for communication and shared understanding, with automation as a useful side effect. A well-formulated scenario should help stakeholders discuss the system, clarify rules, and discover what really matters, especially when working with legacy behavior. By the end, the team has a short, intention-revealing scenario that documents the essence of the rule and is easier to maintain, review, and build on for future requirements.

Customer-collection example map
Customer-collection example map
Pay-on-collection rule
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
  • Business language (B)—the words used in a scenario should be drawn from the business domain
  • Real data (R)—examples should use concrete, real data to help reveal the scenario’s intention
  • Intention revealing (I)—scenarios should reveal the intent of what the actors in the scenario are trying to achieve, rather than describing the mechanics of how they will achieve it
  • Essential (E)—any part of a scenario that doesn’t directly contribute to illustrating the expected behavior of a rule should be removed
  • Focused (F)—illustrative scenarios should be focused on illustrating a single rule
  • BRIEF—scenarios should strive to be short, ideally five steps or fewer
  • Example mapping is structured technique for collaboratively reaching a shared understanding of a one aspect of a system’s intended behavior
  • Scenarios should be structured to act as useful documentation for 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 does the BRIEF acronym stand for in scenario formulation?BRIEF stands for Business language, Real data, Intention revealing, Essential, Focused, and Brief. These principles help scenarios stay readable, maintainable, and useful for collaboration.
Why should scenarios be treated as documentation rather than tests?Scenarios are primarily written to describe and clarify expected system behavior for stakeholders. Automated testing is a valuable side effect, but the main goal is communication, not exhaustive verification.
Why was the old “Order Test” scenario considered poor?It was long, mixed up keywords, combined multiple rules, and included implementation details. As a result, it was hard to read, hard to maintain, and did not clearly communicate the intended behavior.
Why is it important for a scenario to be focused on a single rule?A focused scenario is easier to understand and review because it illustrates one behavior at a time. If a scenario covers multiple rules, it becomes harder to see what failed and why.
What does “intention revealing” mean in a BDD scenario?It means describing what the actors are trying to achieve, rather than the mechanics of how they do it. For example, “they should be able to choose to pay on collection” is clearer than UI-specific actions like clicking buttons.
Why should incidental details be removed from a scenario?Incidental details do not directly help illustrate the rule being described. Removing them makes the scenario shorter, clearer, and less distracting for readers.
When should real data be used in a scenario?Real data should be used when it helps reveal intent, assumptions, or edge cases. If the exact value does not affect the behavior being illustrated, it is often better to use a more abstract description.
Why did the team replace “1 item” with “the customer’s basket is not empty”?The exact number of items was not important to the rule. The more meaningful business condition was simply that the basket was not empty, which better communicated the scenario’s intent.
Why did the team change “click Checkout” to “proceed to payment instructions”?“Click” describes a UI mechanism, not the user’s intention. The revised wording uses business language and expresses the outcome the customer is trying to reach.
Should scenarios always mention whether a customer is authenticated or unauthenticated?No. That distinction should only be included when it affects the behavior being described. If the behavior is the same either way, it is better to simply say “customer” and keep the scenario focused.

pro $24.99 per month

  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose one free eBook per month to keep
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime

lite $19.99 per month

  • access to all Manning books, including MEAPs!

team

5, 10 or 20 seats+ for your team - learn more


Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Effective Behavior-Driven Development Effective Behavior-Driven Development ebook for free
Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Effective Behavior-Driven Development Effective Behavior-Driven Development ebook for free