Gherkin Flow

Debug Gherkin tests 5× faster — without leaving VS Code.

Built for QA Automation Engineers and BDD teams who write Cucumber scenarios daily and want their editor to actively support their workflow — not just display files.

Supports Java (Maven / Gradle), JavaScript / TypeScript (cucumber-js), and Python (Behave) out of the box — zero configuration required.

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

That's not a test workflow. That's a context-switch tax.

GherkinFlow eliminates every one of those switches. Run, inspect, navigate, and fix — 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

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.

🔧 Zero-Config Build Detection

Automatically detects your build tool — no configuration file needed:

Quick Start

1. Open any workspace containing .feature files — the extension activates automatically
2. Click ▶ Run Scenario above any scenario
3. Watch results appear step-by-step in the Testing panel (flask icon in the Activity Bar)
4. Click a failed step to read the error and stack trace
5. Ctrl+click any step to jump to its implementation

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

0.9.31

Fix: Python / Behave stub generation now produces valid, runnable stubs. Previously the generator used Cucumber Expression syntax ({string}, {int}) which Behave does not understand, and produced duplicate parameter names (e.g. def func(context, string, string)) that are invalid Python. Stubs now use Behave's parse format — quoted strings become "{argN}", integers {argN:d}, floats {argN:f} — with unique parameter names and function names derived from the step text rather than the literal values. The step file picker now only shows .py files for Behave projects (previously showed Java/TS/JS files alongside Python ones).

0.9.30

Debug mode — a $(debug-alt) Debug button now appears above every scenario. Click it to run the scenario with the debugger attached: set a breakpoint in any step definition and step through it interactively without leaving VS Code. Works across all supported stacks:

• Node.js (cucumber-js): spawns with --inspect-brk and auto-attaches VS Code's Node debugger
• Java (Maven): runs with -Dmaven.surefire.debug (suspends on port 5005) and attaches the Java debugger
• Java (Gradle): runs with --debug-jvm (suspends on port 5005) and attaches the Java debugger
• Python (Behave): runs via python -m debugpy --listen 5678 --wait-for-client and attaches the Python debugger

No launch.json configuration required — GherkinFlow attaches automatically after the process is ready.

0.9.29

Fix: scenario runs on cucumber-js projects with parallel: N configured in cucumber.js no longer throw "instance not running (PENDING)". The root cause: --name "scenario" filter forces the parallel coordinator to scan support files to match scenario names, but does so before reset() initialises the Cucumber instance. GherkinFlow now uses the features/file.feature:LINE line-number addressing format instead of --name, which lets cucumber-js filter scenarios directly from the Gherkin AST without touching support code. Falls back to --name only when no line number is available (rare fallback path).

0.9.28

Fix: removed the --parallel 0 flag that was silently breaking projects using playwright-bdd and similar cucumber-js setups. In certain cucumber-js v11 configurations, passing --parallel 0 triggers an internal coordinator code path that imports support modules before the Cucumber instance is initialised (status: PENDING), causing setDefaultTimeout() and setWorldConstructor() to throw even though the same command works fine from a terminal. Also strip ELECTRON_RUN_AS_NODE from the child process environment to prevent VS Code's Electron runtime from leaking into spawned Node processes.

0.9.27

Fix: scenario and feature runs now pass --parallel 0 to override any parallel: N set in cucumber.js. With parallel workers enabled, support files (e.g. hooks.ts, world.ts) were loaded inside worker processes before startWrappingMethods() initialised the Cucumber instance, causing module-level calls like setDefaultTimeout() and setWorldConstructor() to throw "instance not running (PENDING)". Serial mode (--parallel 0) guarantees the correct initialisation order. Tag runs keep the project's parallel setting.

0.9.26

Fix: never fall back to npx cucumber-js — if @cucumber/cucumber is not installed locally, print a clear error telling the user to run npm install instead of downloading the security-placeholder package from npm.

0.9.25

Fix: Node.js Cucumber projects now invoke node node_modules/@cucumber/cucumber/bin/cucumber-js directly when the local binary is installed, instead of relying on npx cucumber-js. Previously, when node_modules was absent or cucumber-js was not locally installed, npx would fall back to downloading the npm package named cucumber-js — which is a security placeholder, not the actual runner — producing a confusing error. The local binary is now preferred; npx is only used as a last resort.

0.9.24

Fix: Playwright + cucumber-js projects now work correctly. Previously, the presence of a cucumber.js config file caused GherkinFlow to assume JSON reporting was already configured and skip adding the --format json: arg. Playwright projects always have cucumber.js for TypeScript/fixture setup but rarely include JSON output — so the report file was never written and Test Explorer stayed empty. GherkinFlow now reads the config to check whether a json: formatter is actually declared. If not, it appends one automatically. If it is, the declared path is used as the report location.

0.9.23

Real-time step progress — Test Explorer now updates step-by-step as tests run instead of waiting for the full suite to finish. Steps turn green (✓) or red (✗) the moment they complete. Supports Cucumber JVM (pretty formatter), Behave, and cucumber-js. Final results from the JSON report are applied after the run and remain the authoritative source.

0.9.22

Python / Behave support — GherkinFlow now works with Python BDD projects using Behave. Auto-detected via behave.ini, features/steps/ directory, or behave in requirements.txt. Run buttons execute behave with JSON output automatically appended. Step definitions in .py files are indexed for Ctrl+click navigation, autocomplete, missing step detection, and stub generation. Behave JSON duration (seconds) is correctly converted to milliseconds in Test Explorer.

0.9.21

Scenario history — after each run, pass/fail and duration are persisted in workspace state (up to 10 runs per scenario). A history CodeLens appears above the scenario once it has been run at least once, showing the last 5 results as ✓ ✓ ✗ ✓ ✓. Mixed results are flagged as ⚡ Flaky ✓ ✗ ✓. Click the lens to see a full timestamped history in a popup. History survives VS Code restarts.

0.9.20

README and Marketplace description updated to clearly show JavaScript/TypeScript (cucumber-js) support alongside Java. Added cucumber-js, javascript, typescript, and nodejs keywords for Marketplace discoverability.

0.9.19

Parallel run support — after each run, GherkinFlow scans for sibling report files alongside the primary report (e.g. cucumber-report-1.json, cucumber-report-2.json) and a parallel reports directory (e.g. target/cucumber-reports/*.json). All found reports are merged before applying results to Test Explorer, so parallel Cucumber executions show correct pass/fail per scenario without any configuration.

0.9.18

README update — Features section and comparison table updated to document Watch mode, Tags sidebar, Parameter type hints, and Step usage heatmap. Roadmap cleaned up (Tags sidebar marked shipped).

0.9.17

Fix: tag runs (▶ @smoke) now go through the tracked execution path instead of the terminal fallback. Results appear in Test Explorer and the Gherkin Tags sidebar shows pass/fail counts immediately after the run.

0.9.16

• Tags sidebar — a Gherkin Tags panel appears in the Testing side bar listing every @tag in the workspace. Expand a tag to see all scenarios under it; click any scenario to jump to it. Pass/fail icons update automatically after each run: green tick when all scenarios for a tag passed, red circle when any failed.
• Step usage heatmap — a $(references) Used in N steps CodeLens appears above every @Given/@When/@Then annotation in your Java/TypeScript/JavaScript step definition files. $(warning) Unused step flags definitions that no feature file references.

0.9.15

• Watch mode — click 👁 Watch above any scenario to auto-rerun it on save. Saving the feature file re-runs it immediately; saving a step definition file re-runs all watched scenarios (with a short debounce). Click 👁 Watching to stop.
• Inlay type hints — parameter types (string, int, float, word) appear as inline grey annotations after each matched value in a step, e.g. Given I enter "admin": string. Powered by the VS Code Inlay Hints API.

0.9.14

Fix: dry run (and tag runs) sent Maven/Gradle system property args (e.g. -Dcucumber.features=...) to the terminal without quoting. PowerShell/cmd.exe split these at the ., causing Maven to receive .features=... as an unknown lifecycle phase. Args starting with -D or -P are now quoted before being sent to the terminal.

0.9.13

• Monorepo support — build tool is now detected by walking up from each feature file's directory instead of always using the workspace root. Maven, Gradle, and Node.js sub-projects in a multi-module repo each use their own pom.xml / gradlew / package.json as the working directory
• Background step misalignment fix — some Cucumber JSON reporters omit background steps from scenario elements; step results now align correctly by detecting the offset rather than silently decorating the wrong lines
• rerunFailed scope fix — running a single scenario no longer overwrites the failure list for the whole feature; failures are merged per scenario so Re-run always targets the correct set
• Dry run — ⚡ Dry Run CodeLens on every Feature line; runs Cucumber with --dry-run / -Dcucumber.filter.dryRun=true to validate step bindings instantly without executing tests

0.9.12

Fix: scenario names containing double quotes (") now run correctly — quotes are replaced with . (regex wildcard) in the Cucumber filter value, which matches correctly and avoids cmd.exe shell quoting issues on Windows.

0.9.11

Fix: Scenario Outline names (and any scenario name) containing spaces now run correctly — args with spaces are quoted before being passed to the shell, so Maven/Gradle no longer interprets words after the first space as extra lifecycle phases.

0.9.10

Fix: tests not running on Windows — shell: false prevented batch-script executables (mvn.cmd, npx.cmd, gradlew.bat) from being found. Reverted to shell: true while keeping the args-array structure. Added proc.on('error') handler so a failed spawn always resolves cleanly instead of hanging the cancel button indefinitely.

0.9.9

Fix: stop button now appears for runs triggered from the Test Explorer gutter/panel as well as from CodeLens buttons — the run profile callback now fires the running state event in both paths.

0.9.8

Fix: clicking a run button while a test is already running now cancels the active run before starting the new one — no more two processes running simultaneously. A $(stop-circle) Stop GherkinFlow button appears in the status bar during any run and cancels it immediately when clicked.

0.9.7

• Format Document (Shift+Alt+F) fixes Gherkin indentation in one shot — Feature at 0, Scenario/Background at 2, steps at 4, Examples table rows at 6; works with Format on Save
• Run single Examples row — each data row in a Scenario Outline Examples table gets its own ▶ Run | col1 | col2 | CodeLens so you can test one row without commenting out the others
• Duplicate scenario name warning — flags both occurrences inline and in the Problems panel when two scenarios in the same feature file share a name
• Shell injection fix — scenario and tag names are now passed as separate args to spawn with shell: false instead of interpolated into a shell command string
• Async step file reads — _reloadFile now uses vscode.workspace.fs.readFile instead of blocking fs.readFileSync

0.9.6

Quality improvements: autocomplete now matches mid-string (type any word in a step and suggestions appear); diagnostics re-evaluation after step file changes is debounced to 300 ms to avoid redundant passes during rapid edits; diagnostics provider now reacts to the step index's own change event instead of maintaining a separate FileSystemWatcher.

0.9.5

Internal quality fixes: map leaks on feature file reload, CancellationTokenSource disposed after each run, GherkinFlow terminal reused across tag runs, warning shown when Cucumber JSON report is missing after a run, decoration types properly disposed on deactivation, dead code removed.

0.9.4

Fix: Ctrl+click on a step again opens the step definition in a new permanent tab. The DocumentLinkProvider is restored for navigation; a textDecoration: none decoration is applied over matched step text to cancel the underline VS Code would otherwise show.

0.9.3

• Fix: step text in feature file is no longer underlined (removed DocumentLinkProvider; Ctrl+click via DefinitionProvider is unaffected)
• Fix: steps in Test Explorer now appear in the same order as the feature file — sortText set on all test items using their file position index
• Fix: 🔄 Re-run button now appears on the specific scenario that failed, not at the top of the feature file

0.9.2

• Ctrl+click on a step now opens the step definition in a new permanent tab instead of reusing the current editor
• Hover tooltip now correctly renders Javadoc/JSDoc HTML tags (<br>, <ul>, <li>, <b>, etc.)
• 🔄 Re-run Failed (N) CodeLens appears on the Feature line after any run that had failures — re-runs only the failed scenarios

0.9.1

README overhaul — new headline, pain-to-solution hook, Why GherkinFlow comparison table, benefit-driven feature descriptions, roadmap section, and demo GIF.

0.9.0

Step hover tooltip — hovering any Gherkin step shows the matched Cucumber pattern, the step definition file and line number, and the Javadoc/JSDoc comment if one is present above the method.

0.8.2

Fix: the light bulb quick fix now correctly includes DataTable/DocString parameters — previously only the CodeLens path detected them; the quick fix path rebuilt the step without checking the following lines.

0.8.1

Fix: generated step definitions now include the correct extra parameter when a step is followed by a DataTable (io.cucumber.datatable.DataTable for Java, DataTable for TypeScript) or a DocString (String / string).

0.8.0

Generate Step Definitions — ⚡ Generate Missing Steps (N) CodeLens appears on the Feature line when unmatched steps exist. Click to generate all stubs at once into a chosen step definition file. A light bulb quick fix on each underlined step offers single-step or bulk generation. Supports Java, TypeScript, and JavaScript with correct annotations, types, and file headers.

0.7.4

Fix: clicking a step in Test Explorer now shows System.out.println and log output captured during that step — parsed from the output field in the Cucumber JSON report.

0.7.3

Fix: scenario names containing double quotes (") no longer break the run command — quotes are replaced with . (regex wildcard) in the Cucumber filter, which matches correctly without shell quoting issues.

0.7.2

Fix: scenario run command now includes feature file path (-Dcucumber.features) so projects with Maven runner class configuration work correctly.

0.7.1

Added Marketplace screenshots showcasing all key features.

0.7.0

JavaScript/TypeScript Cucumber support — auto-detects @cucumber/cucumber projects, runs via npx cucumber-js, scans .ts/.js step definitions for jump, autocomplete, and missing step detection.

0.6.0

Gherkin syntax highlighting — proper TextMate grammar with coloured keywords, tags, strings, table cells, docstrings, and outline parameters.

0.5.0

Inline failure decoration — failed steps highlighted with red background and inline error text.

0.4.0

Gherkin autocomplete — step definition suggestions while typing in .feature files.

0.3.0

Missing step detection — warning underlines for steps with no matching Java definition.

0.2.0

Step Definition Jump (Ctrl+click), Tag Filtering CodeLens buttons, GitHub Actions CI/CD.

0.1.0

Initial release with CodeLens, Test Explorer integration, Scenario Outline support, and step-level results.