Gherkin Flow

The AI-powered BDD toolkit for VS Code.

Write better scenarios, run faster, debug instantly — without leaving your feature file.

Describe a requirement in plain English and watch GherkinFlow generate a complete .feature file. Run any scenario with one click, step through failures in the debugger, and let the AI-driven quality linter catch bad BDD before your team review.

Supports Java (Maven / Gradle), JavaScript / TypeScript (cucumber-js), and Python (Behave) — JavaScript and Python need zero configuration; Java needs one reporter line.

The Problem

Your Gherkin test fails. Now what?

1. Scroll through 300 lines of Maven / npm / behave output to find which step broke
2. Copy the error, manually search across Java / TypeScript / JavaScript / Python files
3. Open the file, fix the step, switch back to the terminal
4. Re-run the entire suite and wait again
5. Repeat — ten times a day

And before it even runs: you spent 20 minutes writing scenarios from scratch, duplicated three step definitions that already existed, and shipped scenarios with no Then assertion that nobody caught in review.

That's not a test workflow. That's a context-switch tax — plus a quality problem.

GherkinFlow eliminates every one of those switches and brings AI into your BDD loop: generate scenarios, catch quality issues, debug step-by-step, and know instantly when your code changes break existing tests — all from the feature file.

Screenshots

▶ One-Click Run Run buttons appear inline above every scenario — no terminal needed	▶ Run Feature File Run all scenarios including Scenario Outline examples
🧪 Step-by-Step Results See exactly which step passed or failed — with timing	🔴 Failure Right in Your File Error message shown as inline ghost text on the failed step
⚠️ Missing Step Detection Undefined steps underlined before you even run — with autocomplete

Supported Stacks

GherkinFlow detects your project automatically — no settings.json changes required.

Monorepo / multi-project: GherkinFlow walks up from each feature file's directory to the nearest build root, so sub-projects each use their own runner and working directory.

CI pipelines: Command palette → GherkinFlow: Generate CI Workflow scaffolds a ready-to-commit GitHub Actions, GitLab CI, or Jenkinsfile for the detected stack.

Quick Start

1 — Prerequisites by stack

JavaScript / TypeScript (zero config)

• VS Code 1.80+
• @cucumber/cucumber installed locally (npm install --save-dev @cucumber/cucumber)
• Feature files in any directory the workspace can see

Python / Behave (zero config)

• VS Code 1.80+
• pip install behave
• Step definitions in features/steps/*.py

Java / Maven or Gradle (one reporter line)

• VS Code 1.80+
• Cucumber JVM 7+ on the classpath
• Add the JSON reporter to your runner class (see below) — GherkinFlow reads this file for step-by-step results

// Maven / Gradle runner class
@CucumberOptions(
    plugin = { "json:target/cucumber-report.json" }
)
public class RunCucumberTest {}

2 — First run (all stacks)

1. Open a workspace that contains .feature files — the extension activates automatically (look for the flask icon in the Activity Bar)
2. Open any .feature file — ▶ Run Scenario and ▶ Run Feature buttons appear above every scenario
3. Click ▶ Run Scenario on one scenario — the Testing panel opens and shows live step progress
4. After the run, check:
   • ✓ green / ✗ red icons next to each step in the Testing panel
   • Failed steps show the error message as inline ghost text directly on the failing line
5. Ctrl+click any step to jump to its implementation

Troubleshooting: If buttons don't appear, confirm that a build file (pom.xml, package.json, build.gradle, or behave.ini) exists somewhere above your feature files. If the Testing panel shows steps as skipped after a Java run, add the JSON reporter line shown above.

3 — Try the AI features

Generate a feature file from a description:

1. Open the Command Palette (Ctrl+Shift+P)
2. Run GherkinFlow: Generate Scenarios from Description
3. Type a plain-English requirement — e.g. "User resets their password via email link"
4. A complete .feature file streams into a new editor tab

Generate missing step stubs:

1. Write a new step — it will be underlined in yellow if no implementation exists
2. Click the ⚡ Generate Missing Steps (N) button on the Feature line
3. Pick an existing step file — runnable stubs are inserted with correct annotations and types

Why GherkinFlow?

Features

▶ One-Click Run — No Terminal Needed

Clickable ▶ Run Scenario and ▶️ Run Feature buttons appear inline above every scenario. Tag buttons appear automatically for tagged scenarios — run @smoke or @regression directly from the file.

@smoke @regression
▶ Run Scenario  ▶ @smoke  ▶ @regression
Scenario: Admin login

You can also right-click anywhere in a feature file:

• Run Scenario (GherkinFlow) — runs the scenario at your cursor
• Run Feature File (GherkinFlow) — runs all scenarios in the file

🧪 Know Exactly Which Step Failed

The VS Code Testing panel shows a full hierarchical tree with pass ✓ / fail ✗ per step and execution time. Click any failed step to see the full error message, stack trace, and System.out.println / log output captured during that step.

▼ Feature: Login
  ▼ ✗ Scenario: Admin login         (320ms)
      ✓ Given I am on the login page
      ✓ When I enter admin credentials
      ✗ Then I see the dashboard     ← AssertionError: expected 'Login' but was 'Dashboard'
  ▼ Scenario Outline: Login as <role>
    ▼ ✓ Login as admin
        ✓ Given I log in as "admin"

🔴 See the Error Without Leaving the File

After a run, failed steps are highlighted with a red background and the error message is shown as inline ghost text — right on the line that broke. No switching windows, no scrolling logs.

  ✓ Given I am on the login page
  ✓ When I enter admin credentials
  ✗ Then I see the dashboard   ← AssertionError: expected 'Login' but was 'Dashboard'

Decorations clear automatically on the next run.

💬 Hover to Inspect Any Step

Hover any Gherkin step to see the matched Cucumber expression, the source file and line number, and the Javadoc/JSDoc comment if one exists above the method.

@Given("I enter {string} in {string}")
LoginSteps.java:42

---
Enters text into a named input field.
@param value  the text to type
@param field  the field label

🔗 Ctrl+Click to Jump to the Definition

Ctrl+click any step to jump directly to the matching Java, TypeScript, or JavaScript step definition. Supports both Cucumber Expressions ({string}, {int}) and regex patterns. Updates automatically when your step files change.

💡 Autocomplete from Your Own Codebase

Type Given , When , Then and get inline suggestions pulled from your existing step definitions — with snippet placeholders for parameters.

Given I enter |
              ↓
  ✦ I enter {string} in {string}
  ✦ I enter {int} items

⚠️ Catch Missing Steps Before Running

Steps with no matching definition are underlined with a warning as you write them — not after a failed run. Hover the underline to see the message. All unmatched steps also appear in the Problems panel (Ctrl+Shift+M).

⚡ Generate All Missing Stubs in One Click

A ⚡ Generate Missing Steps (N) button appears on the Feature line when unmatched steps exist. Click it to generate all stubs at once — pick an existing step file or create a new one. A light bulb quick fix on each underlined step also offers single or bulk generation.

Generated stubs include correct annotations, parameter types (including DataTable and DocString), and file headers for Java, TypeScript, and JavaScript:

@Given("I enter {string} in {string}")
public void iEnterInField(String arg0, String arg1) {
    // TODO: implement
    throw new io.cucumber.java.PendingException();
}

👁 Watch Mode — Auto-Rerun on Save

Click 👁 Watch above any scenario to start watching it. Every time you save the feature file that scenario reruns automatically — no manual click needed. Click 👁 Watching to stop.

🏷 Tags Sidebar

A Gherkin Tags panel in the Testing activity bar lists every @tag across your workspace. Expand a tag to see all scenarios under it. After a run the tag shows 3 passed · 1 failed with a green/red icon. Click any scenario to navigate directly to it.

🔢 Parameter Type Hints

Inline grey annotations appear after matched parameter values in your feature file:

When I enter "admin": string in "username": string
Given I add 3: int items to the cart

These are editor overlays — not real text — powered by the VS Code Inlay Hints API.

📊 Step Usage Heatmap

Open any Java/TypeScript/JavaScript step definition file. Each @Given/@When/@Then annotation shows a CodeLens with its usage count across all feature files:

$(references) Used in 5 steps
@Given("I enter {string} in {string}")

$(warning) Unused step flags definitions that no feature file references — helping you find dead code before it accumulates.

🚀 Generate CI Workflow

Command palette → GherkinFlow: Generate CI Workflow. Pick GitHub Actions, GitLab CI, or a Jenkinsfile and GherkinFlow scaffolds a ready-to-commit pipeline using the same stack detection that powers local runs — correct runtime setup, install/test commands, working directory (including monorepo subdirectories), and the report file wired up as a build artifact:

- name: Run Cucumber tests
  working-directory: services/checkout
  run: mvn test

- name: Upload Cucumber report
  uses: actions/upload-artifact@v4
  with:
    path: services/checkout/target/cucumber-report.json

You'll be prompted before anything overwrites an existing pipeline file.

🔧 Zero-Config Build Detection

Automatically detects your build tool — no configuration file needed:

Requirements

Java (Maven / Gradle)

• Cucumber JVM 7+
• Maven or Gradle as the build tool
• A Cucumber JSON reporter writing to target/cucumber-report.json

Add the JSON reporter to your runner if not already present:

@CucumberOptions(
    plugin = { "json:target/cucumber-report.json" }
)

JavaScript / TypeScript

• @cucumber/cucumber in package.json
• The extension auto-detects and runs via npx cucumber-js
• JSON output written to reports/cucumber.json (configured automatically if no cucumber.js config file is found)

Python (Behave)

• behave installed (pip install behave)
• Detected automatically via behave.ini, a features/steps/ directory, or behave in requirements.txt
• JSON output written to reports/behave.json (appended automatically — no manual configuration needed)
• Step definitions in features/steps/*.py are indexed for jump, autocomplete, and missing step detection

Roadmap

Have a feature request or found a bug? Open an issue on GitHub — contributions welcome.

Release Notes

See CHANGELOG.md for the full version history.