gherkin-scenario-coverage-map

Overview

After acceptance-criteria-extractor turns a story into .feature files, the next question is whether any of those scenarios already exist. Authoring a test that a step definition already covers wastes effort and inflates the suite. This skill maps new Gherkin scenarios to existing step-definition coverage before a single new test file is created.

Cucumber's Gherkin reference makes the step text - not the keyword - the stable identity unit: "Keywords are not taken into account when looking for a step definition. This means you cannot have a Given, When, Then, And or But step with the same text as another step." (cucumber.io/docs/gherkin/reference) Fingerprint on the text.

When to use

• A story has been processed by acceptance-criteria-extractor and one or more .feature files exist in a working branch.
• The team is about to write new step definitions or wire up existing ones.
• A sprint review finds test counts rising faster than feature count, and the team suspects duplicate coverage.

Do not use this skill as a substitute for running the suite. It detects structural duplicates and coverage gaps in the step layer; it does not execute assertions or report pass/fail.

How to use

1. Collect the new scenarios - read each .feature file; capture title, keyword-stripped step texts, and tags (Step 1).
2. Build the step-usage index from the existing suite, or load the Cucumber JSON report when present (Step 2).
3. Fingerprint each new scenario as the ordered tuple of its normalized step texts (Step 3).
4. Classify each scenario DUPLICATE, PARTIAL, or GAP against the index, then resolve tag matches (Steps 3-4).
5. Emit the coverage map - duplicates, partial overlaps, gaps, and a summary header (Step 5).
6. Halt on a hard-reject condition - empty suite, unparseable Gherkin, or an index too small to be meaningful (Step 6).

Step 1 - Collect the new scenarios

Read every .feature file produced by acceptance-criteria-extractor (or identified by the user). For each Scenario and Scenario Outline, collect:

• The scenario title.
• The full ordered list of step texts, stripped of their keyword prefix (Given, When, Then, And, But). Per gherkin-ref, keywords are cosmetic; the text is what step definitions match.
• Any @tags declared on the scenario or inherited from the Feature block. Tags use the @name prefix syntax and are space-separated on the line above the keyword (cucumber.io/docs/cucumber/api).
• For Scenario Outline, note the parameter names from the Examples: table as a suffix to each step text placeholder (e.g., "<status>").

Output: a new-scenario list of { id, title, tags[], steps[] } objects.

Step 2 - Build the step-usage index from the existing suite

Glob all .feature files in the existing suite (excluding the new ones from Step 1). For each file, extract every step text using the same keyword-strip rule as Step 1. Normalize whitespace and lower-case each text.

Build a step-usage index: a map of normalized_step_text -> [{ feature_file, scenario_title, line_number }].

If the project uses Cucumber's json report format (cucumber.io/docs/cucumber/reporting: built-in plugins include json, html, junit, message), prefer loading the report over re-parsing .feature files. The JSON report contains every executed step with its text, status, and parent scenario, making the index cheaper to build and guaranteed to reflect the last run.

To generate a fresh JSON report (Cucumber-JS example):

npx cucumber-js --format json:reports/cucumber.json

For JVM (Maven):

mvn test -Dcucumber.plugin="json:target/cucumber.json"

Step 3 - Fingerprint each new scenario

For each new scenario from Step 1, compute a scenario fingerprint: the ordered tuple of its normalized step texts. Two scenarios are exact duplicates when their fingerprints are identical.

Two scenarios are partial overlaps when their step sets share a strict subset (at least two steps in common but not all).

A scenario is a genuine gap when none of its steps appear in the step-usage index.

Assign each new scenario one of three coverage statuses:

Step 4 - Resolve tag coverage

Tags declared on a new scenario may correspond to existing test runs. Per cucumber-api, tag filtering uses boolean expressions such as @smoke and @fast or not @wip. Check the step-usage index entries for matching tags. A scenario tagged @smoke that maps to a PARTIAL overlap may already be executed as part of a @smoke run; flag this explicitly in the output as a PARTIAL (tag match) variant.

Step 5 - Emit the coverage map

Produce a structured report with four parts:

• Duplicates - a table pairing each DUPLICATE scenario with the existing scenario it mirrors and its file:line. Marked "do not author".
• Partial overlaps - per PARTIAL scenario, the already-covered steps and the new steps to author, with a reuse recommendation.
• Gaps - each GAP scenario listed in full, marked ready for new test authoring.
• Summary header - counts of scenarios evaluated, duplicates, partials, gaps, and what the step-usage index was built from.

The exact markdown templates for each part live in references/coverage-map-output-format.md; the Worked example below shows a filled-in map.

Step 6 - Hard-reject conditions

Do not emit a coverage map if any of the following conditions hold. Halt and report the blocker instead:

• No existing .feature files and no Cucumber JSON report are found. A coverage map against an empty suite is vacuous; all new scenarios would be GAP by definition and the map adds no signal.
• The new .feature files contain unparseable Gherkin (missing Feature: keyword, unclosed Examples: table, illegal step keyword). Fix the syntax first; use acceptance-criteria-extractor to regenerate if needed.
• The step-usage index contains fewer than 5 distinct step texts. A suite this small has not yet established coverage baselines; the map would mislead rather than inform.

Emit a BLOCKED message that names the condition and the remediation step.

Anti-patterns

Worked example

Input: acceptance-criteria-extractor produced password-reset.feature with three scenarios:

1. "User requests password reset" (4 steps)
2. "Reset link expires after 24 hours" (3 steps)
3. "User resets password with valid token" (5 steps)

Existing suite index (from auth/login.feature and auth/session.feature): Steps 1-4 from scenario 1 are all present in auth/login.feature:32. Steps 1-2 from scenario 3 are in auth/session.feature:18; steps 3-5 are new. Scenario 2 has no matching steps.

Coverage map output:

## Coverage map for `AUTH-42` - 2026-06-04

**New scenarios evaluated:** 3
**Exact duplicates:** 1 (skip these)
**Partial overlaps:** 1 (extend step definitions only)
**Genuine gaps:** 1 (author full scenarios)
**Step-usage index built from:** 2 existing .feature files

### Duplicates (do not author)
| New Scenario | Existing Scenario | File |
|---|---|---|
| "User requests password reset" | "User initiates reset flow" | `auth/login.feature:32` |

### Partial overlaps
**Scenario: "User resets password with valid token"**
- Already covered (2): "the user has a valid reset token", "the user navigates to /reset"
- New steps required (3): "they enter a new password", "they confirm the password", "a success banner appears"
- Recommendation: add 3 step definitions; reuse 2 existing.

### Gaps (author full scenario)
- "Reset link expires after 24 hours" - 0 of 3 steps covered

References

• gherkin-ref - Cucumber Gherkin reference: step keywords, step text identity rule ("keywords are not taken into account when looking for a step definition"), Feature / Background / Scenario / Scenario Outline.
• cucumber-api - Cucumber API reference: tag syntax (@name, space-separated), tag expressions (and, or, not), tag inheritance from Feature to Scenario, CLI filtering via --tags and cucumber.filter.tags property.
• cucumber-reporting - Cucumber reporting reference: built-in reporter plugins (json, html, junit, message, progress, rerun); JSON report as the canonical executed-step record.
• references/coverage-map-output-format.md - the full markdown templates for the Step 5 coverage-map output.
• acceptance-criteria-extractor - upstream skill that produces the .feature files this skill consumes.
• non-functional-requirement-extractor - sibling for non-functional requirements; scenarios it produces are out of scope for BDD-suite coverage mapping.