Gherkin Step Lens

A VS Code extension for BDD teams writing Gherkin .feature files.
Colours every step by its match state, highlights captured & Examples parameters, flags undefined / ambiguous / wrong-keyword steps and undeclared placeholders, auto-aligns Examples tables, and provides Go-to-Definition.
Works with Reqnroll · SpecFlow · Cucumber-JVM · Cucumber.js · behave — zero setup for the common layout, fully configurable for the rest.

📸 Screenshots

Images live in images/ and render on the Marketplace via absolute raw-GitHub URLs.

Colouring & match states	Undeclared placeholder detection

Go-to-Definition & hover	Examples table auto-alignment

✨ Features at a glance

🎨 1 · Gherkin Keyword Colouring

Every structural keyword is coloured to visually separate scenario shape from step content.

Feature: Letter Builder Sanity Scenarios

  Background:
    Given I navigate to LetterBuilder application

  Scenario Outline: Verify profile and login history
    Given I login with valid <username>
    When  I click on the login button
    Then  I should be logged in to the application
    And   I verify the profile icon is displayed

  Examples:
    | username                  |
    | [email protected]  |

🟠 2 · Parameter Value Highlighting

Values captured by (.*) groups (or Cucumber Expression tokens) are highlighted in bold orange — so you see exactly which parts of the step are data.

C# step definition:

[When("I navigate to (.*) page under settings option")]
public async Task NavigateToPage(string option) { ... }

Feature file — matched value lights up orange:

When  I navigate to merge fields page under settings option

Multiple capture groups on one step are all highlighted:

Then I verify that Browser, IP Address, Login Date, and Logout Date are in the table header

🩷 3 · Scenario Outline Placeholders

<placeholder> tokens are highlighted in bold pink — distinct from orange — so you always know which values come from the Examples: data table.

Scenario Outline: Login verification
  Given I login with valid <username> without DBConnection
  When  I click on the login button
  Then  I should be logged in to the application

  Examples:
    | username                  |
    | [email protected]  |

🩷 Pink placeholder in step → 🩷 Pink header cell in Examples: → 🟠 Orange data cell in each row
Pink always wins — even if a (.*) pattern could also match the placeholder text.

📊 4 · Examples Table Colouring & Auto-Format

Every |-delimited row is coloured by role. As you type into a cell, the table is automatically aligned to the widest value in each column.

  Examples:
    | username                  | role   |   ← 🩷 header row (pink)
    | [email protected]  | admin  |   ← 🟠 data rows (orange)
    | [email protected]      | user   |

🔴 5 · Step Match States — 4 Colours, Instantly Understood

Every step is classified into one of four states, each with its own colour:

All four states in one file:

Feature: Demonstrate every step state

  Scenario: All four colour states

    When  I navigate to merge fields page under settings option
        ✅ MATCHED — single def found, captured value is orange

    Then  I see the dashboard with all the widgets
        ⚠️ AMBIGUOUS — 2 patterns both match this step

    Given I click the green submit button at the bottom
        ❌ UNDEFINED — no definition anywhere matches

    When  I navigate to merge fields page under settings option
        ⚠️ WRONG KEYWORD — text exists under [Given], not [When]

Hover over any step to see a rich tooltip:

• ✅ Matched → clickable link → jumps to the C# method
• ⚠️ Ambiguous → lists every matching definition with file + line links
• ❌ Undefined → shows a ready-to-paste C# stub to create the definition
• ⚠️ Wrong Keyword → tells you which keyword the definition actually uses

💡 Keyword-aware matching — a [When("…")] definition only matches When steps (and And/But that follow a When). A broad [Then("I (.*)")] pattern will never accidentally highlight your When step yellow.

🔍 6 · Go to Definition — F12

Press F12 (or right-click → Go to Definition) on any step line to jump straight to the matching C# method.

── feature file ─────────────────────────────────────
When I click on the profile icon   ← press F12 here

── jumps to C# ──────────────────────────────────────
[When("I click on the profile icon")]
public async Task WhenIClickOnTheProfileIcon()
{
    await _page.ClickOnProfileButtonOnHeader();
}

🎯 Smart disambiguation — when two patterns both match, the one that captures the fewest characters wins, so you always land on the most specific definition.

🔄 7 · Automatic Step Reload

The extension watches **/Steps/**/*.cs. When you add, edit, or delete a step definition, colours and Go-to-Definition update immediately — no reload, no restart required.

⚡ 8 · Performance — Built for Large Projects

⚙️ Supported C# Step Attribute Formats

[Given("...")]   [When("...")]   [Then("...")]   [And("...")]   [But("...")]

// Multiple attributes on one method — both are indexed
[When("I click on the (.*) button")]
[When("I click on the (.*) option")]
public async Task ClickButton(string name) { ... }

// Verbatim strings with literal parentheses — fully supported
[Then(@"the column \(s\) (.*) exist")]

🥒 Cucumber Expression Tokens

🎨 Colour Reference

⚙️ Recommended Workspace Settings

{
  "cucumberautocomplete.steps": ["CP.Automation.Tests/Steps/**/*.cs"],
  "cucumberautocomplete.gherkinDefinitionPart": "\\[?(Given|When|Then|And|But)\\s*\\(\"",
  "cucumberautocomplete.stepRegExSymbol": "\"",
  "files.associations": { "*.feature": "feature" }
}