bdd-step-library-curator

Overview

After 6 months of a BDD project, step definitions proliferate:

• Two engineers write Given a user and Given a logged-in user for the same fixture.
• Three slightly-different "I click X" steps (one for buttons, one for links, one for arbitrary elements) - all do the same thing.
• A new engineer can't find existing steps and writes a fourth variant.

The result: step library bloat → Gherkin features hard to read, step ambiguities, runtime errors, drift.

This skill builds a curation workflow.

When to use

• A BDD project's step count exceeds ~50 (proliferation threshold).
• A new engineer reports "I couldn't find a step for X."
• Quarterly: scheduled step review.
• Before adopting BDD across multiple teams (proactively design the step library shape).

How to use

Work through Steps 1-6 below in order: inventory -> detect duplicates -> recommend consolidations -> reorganize and publish the README -> gate new steps pre-merge -> repeat on a cadence.

Step 1 - Inventory step definitions

Extract every declared step pattern across the project. Each runner uses its own annotation syntax (@Given in Cucumber-JVM, @given in Behave, [Given] in Reqnroll / SpecFlow) - the per-runner extraction commands are in references/step-extraction-and-overlap.md.

The inventory produces a step audit:

Total step definitions: 142
Unique patterns: 138    (4 ambiguous duplicates already)
Per Gherkin verb:
  Given: 58
  When:  34
  Then:  47
  And:    3

Step 2 - Detect duplicates / overlaps

Two patterns are likely duplicates when:

• Same wording, different phrasing: Given a user vs Given an existing user vs Given the user.
• Same parameters, different verbs: When I click {label} vs When I press {label} vs When I tap {label}.
• Same fixture, different shape: Given a cart with {n} items vs Given a cart containing {n} items.

Normalize each pattern (lowercase, drop articles, collapse parameters) and group by the normalized form; any group of size greater than one is a candidate cluster. The overlap script that does this is in references/step-extraction-and-overlap.md.

Step 3 - Recommend consolidation

For each duplicate group:

**Duplicate group:** 4 step definitions with normalized "user is
logged in"

| Pattern                            | File / line                |
|------------------------------------|----------------------------|
| `Given a user is logged in`         | `auth_steps.py:12`         |
| `Given the user is logged in`        | `cart_steps.py:8`           |
| `Given an authenticated user`        | `checkout_steps.py:5`       |
| `Given a logged-in user`            | `profile_steps.py:14`       |

**Recommendation:** Consolidate to **`Given a logged-in user`**
(highest count of usage in current Gherkin; clearest wording).

Replace the other 3 step definitions with a single canonical one
in `shared_steps.py`. Update the Gherkin features that use the
deprecated patterns.

Verify: consolidation is destructive - it deletes step definitions and rewrites .feature files. After each group, run the full BDD suite and assert zero undefined or ambiguous steps and no orphaned scenarios before declaring the refactor complete. If a scenario reports an undefined step, a .feature file still references a deprecated pattern - fix that reference and re-run.

Step 4 - Domain organization

Group steps per domain area:

features/steps/
├── shared/                      # cross-domain (login, navigation, etc.)
│   ├── auth_steps.py
│   ├── navigation_steps.py
│   └── data_steps.py
├── checkout/                    # checkout-specific
│   ├── promo_steps.py
│   ├── payment_steps.py
│   └── cart_steps.py
├── account/                     # account-specific
│   └── profile_steps.py
└── README.md                    # step library index

The README is the discoverability artifact:

# Step library

## Shared (cross-domain)

### Auth
- `Given a logged-in user` (auth_steps.py:12) - creates and logs in a generic test user.
- `Given a logged-in admin` (auth_steps.py:25) - logged-in user with admin role.
- `Given an unauthenticated visitor` (auth_steps.py:38) - no session.

### Navigation
- `When I navigate to {path}` - go to URL.
- `When I click {label}` - click any element with this label.

## Checkout

### Cart
- `Given the cart contains {qty} of {sku} at ${price}` - seed a cart.
- `Given the cart is empty` - empty cart.

### Promo codes
- `Given promo code {code} is active` - pre-seed a promo in the admin.
- `When I enter {code} in the promo input` - type the code.
- `When I click {label}` - (uses shared step).

(...)

The README + grep is the team's "is there a step for X?" tool.

Step 5 - Pre-merge step gate

Add a CI check that flags new step definitions so no engineer adds a duplicate unknowingly. The check warns (doesn't block), forcing the author to acknowledge the new step and grep the README first. The check-new-steps.sh script is in references/step-extraction-and-overlap.md.

Scenario coverage map (pre-authoring duplicate check)

The same duplicate-prevention discipline applies one level up, at the scenario layer. When new .feature files land (typically from gherkin-from-stories), fingerprint each new scenario by its ordered, keyword-stripped step texts and diff against the existing suite's step-usage index before any test is authored:

• DUPLICATE - every step already covered under one existing scenario: do not author.
• PARTIAL - some steps overlap: author only the new step definitions, reuse the rest.
• GAP - nothing matches: author in full.

Fingerprint on the step text, not the keyword - per the Gherkin reference, "keywords are not taken into account when looking for a step definition." Prefer the Cucumber JSON report over re-parsing source .feature files when one exists, exclude Background steps from the fingerprint, and halt on an empty or tiny index (a map against an empty suite is vacuous). The full method, output templates, tag-match handling, and hard-reject conditions: references/coverage-map.md.

Step 6 - Quarterly cadence

Cadence	Trigger
Quarterly	Scheduled step library review.
New team member	Onboarding: walk the README.
Step count exceeds threshold	Triggered review.
New domain area	Add steps; update README.

Worked example

Curating a 142-step library in a mixed Behave project, end to end.

1. Inventory. The Behave extraction over features/steps/ yields the Step 1 audit: 142 step definitions, 138 unique patterns - so 4 are already ambiguous duplicates the runner would flag at match time.

2. Detect. The overlap script surfaces one cluster - the four user is logged in variants listed in Step 3's duplicate-group table.

3. Consolidate. Pick Given a logged-in user as canonical (clearest wording, most-used in current Gherkin). Move it into features/steps/shared/auth_steps.py, delete the other three definitions, and rewrite the .feature files that used the deprecated phrasings - edit the Gherkin first so no scenario is left orphaned, then run the Step 3 verification.

4. Reorganize + publish. Split the flat features/steps/ into shared/, checkout/, and account/, then regenerate the README index. The library now advertises Given a logged-in user (auth_steps.py) - creates and logs in a generic test user under Shared → Auth.

5. Gate. Add the pre-merge new-step check. The next PR that adds Given the customer is signed in trips the warning; the author greps the README, finds Given a logged-in user, and reuses it instead of adding a fifth variant.

Result: 142 → 139 step definitions, zero ambiguous duplicates, one discoverable index the whole team searches before writing a step.

Anti-patterns

Anti-pattern	Why it fails	Fix
Per-engineer step files (alice_steps.py)	Ownership without domain alignment; duplication across files.	Domain-organized files (Step 4).
Step library README missing	Discoverability nil; engineers re-implement.	README per Step 4.
Ambiguous step deletion without grep	Breaks scenarios silently.	Replace canonical → deprecated; update all Gherkin first.
Step "shared library" that's a giant helpers.py	All engineers conflict on it; merge hell.	Domain split (Step 4).
Reviewing step count quarterly only	Proliferation outpaces review; library bloats.	Pre-merge gate (Step 5).

Limitations

• Heuristic duplicate detection. Some patterns are legitimately distinct (Given a user for auth vs Given a user with profile data for profile tests).
• Domain organization is per-team. What's "shared" varies.
• Consolidation cost. Each refactor touches Gherkin + step definitions; not free.
• Doesn't fix Gherkin quality. A clean step library doesn't prevent imperative-style Gherkin scenarios. Pair with a Gherkin style review.

References

• Step extraction commands, the overlap-detection script, and the pre-merge gate: references/step-extraction-and-overlap.md.
• Scenario-level coverage map (fingerprinting, output templates, hard-reject conditions): references/coverage-map.md.
• cucumber-testing, behave-testing, reqnroll-testing - per-language runners this curator works alongside.