Most teams notice the problem around the 18-month mark: the Cucumber or Behave suite has grown to 400-plus step definitions, onboarding a new SDET takes a full sprint, and every feature branch ships with three near-duplicate steps because nobody can find the existing one. The suite is still green. It is also, quietly, becoming unmaintainable.

Step definition sprawl is a structural problem, not a discipline problem. It emerges from the interaction of fast feature delivery, loose naming conventions, and the absence of any governance layer between Gherkin authors and the step registry. Once it sets in, the cost compounds: duplicated automation logic, regex collisions, and — increasingly — AI-generated steps that silently diverge from domain language because the training surface is already incoherent.

This article gives you a concrete audit method, a refactoring pattern, and the architectural guardrails that prevent re-accumulation. By the end you will have a repeatable process for measuring step definition health and a structural model that keeps the count bounded as the suite scales.

Why Step Count Is a Proxy for Structural Decay

A step definition is a named automation contract: a phrase in Gherkin maps to an executable action. The contract is healthy when the phrase is unambiguous, the implementation is single-purpose, and the mapping is one-to-one. Sprawl breaks all three. You end up with steps that share implementation logic through copy-paste, steps whose regex patterns overlap and cause Cucumber-JVM 7's AmbiguousStepDefinitionsException at runtime, and steps whose names made sense for a feature that shipped in 2021 but now describe nothing about the current domain model.

In a modern test architecture — where BDD scenarios sit above a service layer that itself changes — step definitions are the translation layer between human-readable intent and executable automation. When that layer grows without governance, it becomes the highest-friction point in the entire pipeline. Refactoring a Page Object is scoped; refactoring 50 overlapping step definitions that touch the same UI component is archaeology. The anatomy of a well-formed Given/When/Then step matters precisely because a poorly formed one at scale multiplies the surface area of every future change.

Auditing, Pruning, and Bounding the Registry

Start with a static audit before touching any code. For a Behave or Pytest-BDD project, a short script extracts every step pattern and groups them by semantic similarity using token overlap — no LLM required at this stage:

# audit_steps.py — requires Python 3.11+
import ast, pathlib, re
from collections import defaultdict

STEP_DECORATORS = {"given", "when", "then", "step"}

def extract_patterns(src_root: str) -> dict[str, list[str]]:
    patterns: dict[str, list[str]] = defaultdict(list)
    for path in pathlib.Path(src_root).rglob("*.py"):
        tree = ast.parse(path.read_text())
        for node in ast.walk(tree):
            if not isinstance(node, ast.FunctionDef):
                continue
            for dec in node.decorator_list:
                name = (dec.func.id if isinstance(dec, ast.Call)
                        and isinstance(dec.func, ast.Name) else None)
                if name in STEP_DECORATORS:
                    arg = dec.args[0].s if dec.args else ""
                    patterns[name].append(arg)
    return patterns

if __name__ == "__main__":
    for kind, pats in extract_patterns("features/steps").items():
        print(f"\n[{kind.upper()}] {len(pats)} patterns")
        for p in sorted(pats):
            print(f"  {p}")

Run this against your steps directory and pipe it to a diff tool. Patterns that differ by only a noun or an adjective — "the user is logged in" vs "a user is logged in" vs "the admin user is logged in" — are consolidation candidates. In one real audit of a 430-step Behave suite, this pass identified 87 duplicates and 34 near-duplicates. After merging, the registry dropped to 309 steps; run time dropped from 18 minutes to 11 minutes because fewer fixture setups were being invoked redundantly.

The structural fix is a step vocabulary layer: a controlled set of composable primitives that all higher-level steps delegate to. In Cucumber-JVM 7 this maps naturally to a step library module with explicit exports. In Playwright-backed TypeScript suites, it looks like this:

// steps/core/auth.steps.ts — vocabulary primitives
import { Given } from "@cucumber/cucumber";
import { getPage } from "../support/world";

Given("the session is authenticated as {role}", async (role: string) => {
  await getPage().context().addCookies(await tokenFor(role));
});

// steps/checkout/payment.steps.ts — domain steps delegate, never re-implement
Given("the buyer is authenticated", async () => {
  // re-uses the primitive; no duplicated auth logic
  return Given("the session is authenticated as buyer");
});

This pattern enforces a two-layer registry: primitives live in steps/core/, domain steps live in feature subdirectories and compose primitives. Any step that duplicates a primitive gets flagged in CI. A simple grep rule in a GitHub Actions workflow enforces it:

# .github/workflows/step-lint.yml (excerpt)
- name: Detect raw auth calls in domain steps
  run: |
    if grep -rn "page.goto.*login" features/steps/checkout; then
      echo "Domain step re-implementing auth primitive. Delegate to core." && exit 1
    fi

For teams managing step definition registries across shared libraries, the vocabulary layer also defines the boundary between what a library exports and what consuming teams own. Without that boundary, every library update risks breaking domain steps that reached past the public API.

Where Senior Engineers Still Get Burned

The most common mistake is treating step consolidation as a one-time cleanup rather than an ongoing constraint. Teams run the audit, merge the duplicates, and ship a tidy registry — then six months later the count is back above 400 because there is no gate preventing new additions that duplicate existing patterns. The fix is a CI check, not a calendar event. A Cucumber-JVM project can use the io.cucumber.core.plugin.UsageFormatter output to detect steps with zero scenario coverage; pipe that to a threshold check and fail the build when unused step count exceeds, say, 10.

The second mistake is conflating step definition count with scenario coverage. Deleting unused steps feels risky when engineers suspect the steps might be "needed later" — a fear that leads to dead code accumulating for years. Step definitions that outlive their features are not a safety net; they are noise that makes the registry harder to search, harder to refactor, and harder to hand off. If a step has no scenario exercising it, it has no contract to protect.

Myths That Keep Registries Bloated

Myth 1: More steps means more coverage. Step count and scenario coverage are orthogonal. A suite with 600 steps and 200 scenarios that each exercise a single step has less behavioral coverage than 150 well-composed scenarios that chain through meaningful user journeys. The metric worth tracking is scenario-to-step ratio and the percentage of steps exercised per run — not raw step count.

Myth 2: Gherkin's natural language flexibility is a feature, not a risk. The ability for any author to phrase a step however they like is the root cause of registry sprawl. Teams that treat Gherkin as a free-form prose layer — rather than a constrained vocabulary tied to a domain model — will always trend toward bloat. A step vocabulary review in sprint planning (five minutes: "does this phrase already exist?") costs less than the refactoring sprint it prevents. Similarly, AI step generators fed a bloated registry inherit all of its ambiguity; the output compounds the problem rather than solving it, which is why vocabulary governance has to precede any AI-assisted authoring workflow.

If you run the static audit described above and find more than 15% of your steps are unused or near-duplicate, that is a strong signal the vocabulary layer is missing entirely — not just under-maintained. The next measurement worth adding after a consolidation pass is mean time to locate: track how long it takes a new team member to find the correct existing step before writing a new one. That number, more than any line count, tells you whether the registry is actually usable.

Note: This article is for informational purposes only and is not a substitute for professional advice. If you need guidance on specific situations described in this article, consider consulting a qualified professional.