Gherkin Smells

Learning Objectives

By the end of this lesson you will be able to:

Explain the "code smell" analogy as it applies to Gherkin specifications
Name and recognize seven common Gherkin smells
Understand why a scenario can "pass" and still be a bad specification

Borrowing "Smell" From Code

In software engineering, a "code smell" is a surface pattern that hints at a deeper design problem, without being an outright bug. Duplicated logic, a function with ten parameters, a class that does everything — none of these crash the program, but all of them make it harder to trust and maintain.

Gherkin has the exact same category of problem. A scenario can execute successfully, its automation can go green in CI, and it can still be a bad specification — one that misleads a reader, hides its actual intent, or simply isn't documentation anyone would want to rely on. That's a Gherkin smell.

The Taxonomy

This lesson is the map. The next two lessons zoom into the two smells worth a deep dive; the capstone lesson shows them all being cleaned up together in one real scenario.

Conjunction steps. A step that does two or three things at once, glued together with commas: "When the user enters their email, enters their password, and clicks submit." Covered in depth next lesson.

Overly long scenarios (10+ lines). A scenario that keeps growing usually means it's testing more than one business rule. Covered in depth in the lesson after that.

Vague or missing expected outcomes. A Then step that never says what success actually looks like — "Then the request is processed" — leaves the reader to guess. A specification that doesn't specify has failed at its one job.

UI-click language. A callback to your first course: steps written in terms of clicks, fields, and buttons ("When the user clicks the blue Submit button") instead of the business action they represent. This ties the spec to a specific UI that will change.

Technical noise. Assertions unrelated to business behavior sneaking into a Then step — "Then no errors appear in the browser console." That's a valid thing to check, but it belongs in a technical test, not a business-readable scenario.

Scenario mixing. Gluing a second, unrelated case — often a negative one — onto a positive scenario with a trailing But. It looks efficient. It actually means neither case gets tested cleanly, and a failure won't tell you which one broke.

Stray comments. A # comment left behind from drafting — a developer's aside, a TODO, a half-formed thought — that never got cleaned out before the scenario was considered "done."

Why the Overview Matters

You don't need to memorize seven definitions. You need to build the instinct: when you read a scenario, does something feel off, even if it technically runs? That instinct is what the rest of this module trains.

Pro Tip: The fastest way to catch a smell is to read a scenario out loud to someone who has never seen the feature. If they get confused or ask "wait, what's actually being tested here?" — you've found a smell.

Key Takeaways