Scenario Suite Maintenance

## The two halves of a scenario suite A plain-language scenario suite is made of two artefacts that must stay in step. One is the set of scenarios themselves: sentences a business reader can follow, describing context, an event and an expected outcome. The other is the **glue layer** — for every distinct sentence the runner encounters there must be a registered piece of code that matches that sentence and carries it out. The sentences are the readable half; the glue is the half that costs money to own. **Step-definition sprawl** is the failure mode in which the glue layer grows in proportion to the number of *sentences that have been typed* rather than the number of *behaviours the product has*. A suite with three hundred scenarios covering forty business rules should not need eight hundred definitions; when it does, most of those definitions are near-copies of each other. ## Why it happens, even to careful teams Nobody decides to sprawl. Four ordinary forces produce it: - **The path of least resistance.** An author writes a new sentence, the run fails with "no matching definition", and the cheapest repair is to copy the nearest existing definition and edit the copy. - **Search cost.** Once the library is large, checking whether a sentence for "the member's balance is 240 points" already exists takes longer than writing a fresh one. The economics quietly favour duplication. - **Phrasing entropy.** "the member has 240 points", "the account holds 240 points" and "the balance is 240 points" are one fact in three costumes. Natural language invites variation; the runner matches text, so each costume needs its own code. - **No audience.** The scenario files have business readers and get read in review. The glue has no audience outside the team, so it is skimmed rather than reviewed, and duplication is never called. ## What it actually costs **Change amplification.** A rule changes in one place in the product and in many places in the glue. Every missed copy is a scenario that keeps asserting the old rule — passing, and therefore silent. **Onboarding and authoring cost.** New joiners cannot tell which sentence to reuse, so they add more. The ratio worsens monotonically unless somebody is accountable for it. **Ambiguity.** Two patterns that both match one sentence produce either a hard failure or, in the worse case, a match against the wrong definition, so the scenario tests something nobody wrote. **Dead glue.** Definitions no live scenario references still compile, still get refactored, still appear in searches, and still mislead the next reader about what the suite covers. **Erosion of the readability payoff.** The suite justified its translation layer on the claim that the files read as one language. Twelve dialects of the same sentence is exactly the claim failing. ## A concrete shape An eleven-person team owns a loyalty-points ledger. Their suite carries 340 scenarios and 812 step definitions — roughly 2.4 definitions per scenario, and rising quarter over quarter. A rule change ("points are awarded once per settled order, not once per settlement attempt") touched nine definitions that all expressed the same award step. Eight were updated. The ninth, reachable only from two older scenarios, kept the old behaviour, and the mismatch let a retried settlement produce a **duplicated side effect**: points credited twice on the same order, in scenarios that stayed green because they asserted the stale rule. The defect was not in the business logic; it was in a copy of the glue that had drifted out of sight. ## Seeing it before it hurts Useful signals, all cheap to compute: - **Definitions per scenario, tracked as a trend.** The absolute number means little across teams; a ratio climbing over two quarters means the library is outgrowing the behaviour set. - **Definitions never matched during a full run** — the dead-glue count. - **Near-duplicate clusters.** Normalise sentence text (lower-case, replace numbers and quoted values with placeholders) and cluster; the clusters are your consolidation backlog. - **Ambiguity failures per month**, which rise as overlapping patterns accumulate. - **The healthiest signal of all:** how often a new scenario can be written entirely from sentences that already exist. A team that adds scenarios without adding glue has a vocabulary, not a vocabulary problem. ## What you do about it At suite level the levers are ownership and vocabulary rather than cleverness. Give the glue layer a named owner and review it as production code. Agree a phrase vocabulary — a short, readable index of the sentences the suite already speaks — and make consulting it part of writing a scenario. Consolidate on touch instead of scheduling a big cleanup that never gets funded. Delete dead definitions the moment the report names them, and wire the dead-glue and ambiguity checks into the build so the count cannot silently climb again. How an individual binding should be shaped is its own subject; what the suite owner controls is whether the library grows per sentence or per behaviour, and whether anyone is watching the trend.