Specification Refactoring (Gherkin Smells)
You've learned the grammar, the structure, the parameterization tricks. Now comes the harder skill: reading a scenario someone else wrote — usually under deadline pressure — and knowing exactly which lines are rotting from the inside.
What Is a "Gherkin Smell"?
Borrowed from the "code smell" idea in software engineering: a smell isn't necessarily a bug. The scenario might run fine, the automation might pass. But a smell is a sign that something deeper is wrong with how the specification was built — and left alone, it quietly erodes the one thing Gherkin exists to protect: a spec that a non-technical reader can trust as documentation.
A scenario riddled with smells still "works." It just stops being useful as a shared source of truth. That's the real cost.
The Three Smells This Module Covers
Conjunction steps. A single step that crams two or three actions into one line, usually stitched together with commas: "When the user enters their email, enters their password, and clicks submit." It reads fine at a glance, but it hides which action actually matters, can't be reused or reordered, and buries the exact location of a defect if the step ever fails.
Scenarios over ~10 lines. Once a scenario stretches past roughly ten lines, it's almost always testing more than one business rule at a time. Long scenarios are hard to review, harder to maintain, and often signal that two (or three) scenarios got welded into one.
Vague or missing expected outcomes. A scenario that never states what "success" looks like in its Then step isn't a specification — it's a suggestion. "Then the request is processed" tells a reviewer nothing. A real outcome is observable and specific.
Why This Matters More at the Intermediate Level
Beginners learn to write a clean scenario from scratch. Intermediate practitioners inherit other people's scenarios — in a legacy suite, in a rushed sprint, in a feature file nobody has touched in a year. Smelling out the rot and refactoring it without breaking the scenario's actual intent is a distinct skill, and it's the one this module builds.
Your Practice Challenge
After the lessons, you'll take on The Spec Auditor — a messy, real-world login scenario riddled with smells: technical noise, a redundant click-and-wait step, a cosmetic UI detail, a second scenario glued onto this one, and a stray developer comment. You check the lines that should be struck out, leaving only a clean, declarative three-step scenario behind. Be careful: strike a line the scenario actually needs (a Given, When, or Then) and you'll break it — that's its own outcome to discover. Get the sweep exactly right, or leave exactly one smell behind, to find all 7 outcomes.