Playwright Cucumber Support

Gherkin formatting, Ctrl+Click/F12 navigation, Run/Debug CodeLens and Test Explorer for projects that call Playwright from TypeScript or JavaScript Cucumber steps.

Extension ID: CorpRideConnect.playwright-cucumber-support
Language ID: cucumber
Host: VS Code 1.96+ on desktop, remote workspaces and VS Code for the Web. Fixtures use Node 20 and @cucumber/cucumber 11.3.0. On a Node.js host, this extension launches Cucumber; your step definitions control Playwright and browser lifecycle.

Installation

Run Extensions: Install from VSIX… in VS Code and choose artifacts/playwright-cucumber-support-0.1.5.vsix, or:

code --install-extension artifacts/playwright-cucumber-support-0.1.5.vsix

Install Cucumber and your chosen transpiler in the test project using your team's normal dependency workflow. Editor dependencies are bundled. The extension never installs project packages.

VS Code for the Web

The same extension package includes a browser entry point for vscode.dev and github.dev. Browser editor features use VS Code's workspace filesystem API, including virtual repositories and folders with spaces.

Use Format Document or Playwright Cucumber: Format Document, and Ctrl+Click/F12 on a Gherkin step. Set playwrightCucumber.features, stepDefinitions, hooks and cwd as relative paths in virtual workspaces. Unsaved edits and filesystem changes update navigation. Workspace code is parsed without execution; regular expressions run in a separate browser worker with a timeout.

Browser hosts hide Run/Debug actions because they cannot start Node.js or Playwright processes. A browser connected to a remote Node host can use the desktop entry point for execution. See VS Code's web extension host limitations.

Marketplace availability requires publishing this version. For development, use Run Web Extension in this repository's launch configurations or follow VS Code's sideloading instructions.

Automatic detection

Open a project folder and a .feature file. Each workspace folder gets its own configuration, index and Test Explorer branch. Config discovery checks cucumber.json, cucumber.yaml, cucumber.yml, cucumber.js, cucumber.cjs, and cucumber.mjs, starting at the configured working directory and continuing through its parents within the workspace folder.

JSON/YAML are parsed as data. JavaScript is scanned statically for literals, constants, exports, profiles and legacy CLI-string profiles. No config or step module is executed in the extension host. Computed values produce a warning with settings/folder-selection actions. paths, require, import and requireModule are recognized; package scripts provide fallback hints. Conventional feature and support directories are used when paths cannot be inferred.

A CommonJS project needs no extension path settings:

// cucumber.js
module.exports = {
  default: {
    paths: ['features/**/*.feature'],
    requireModule: ['ts-node/register'],
    require: ['features/steps/**/*.ts', 'features/support/**/*.ts'],
    format: ['progress']
  }
};

For ESM, follow your installed Cucumber version's export convention. The tested Cucumber 11 form is:

// cucumber.mjs
export default {
  paths: ['features/**/*.feature'],
  import: ['features/steps/**/*.mts'],
  loader: ['ts-node/esm']
};

Configure Paths and settings

Run Playwright Cucumber: Configure Paths. Choose a workspace folder, inspect the detected config/profile/cwd/globs, then accept detection, select feature/step/hook folders, or enter JSON arrays of globs. Choose Workspace or Workspace Folder scope when saving. Only extension-owned settings are updated; unrelated settings are preserved. Test Explorer refreshes immediately.

Globs are relative to playwrightCucumber.cwd; cwd is relative to the workspace folder. Absolute globs are also supported. For monorepos, add independent packages as separate workspace folders or set cwd to the package being tested.

Folder settings override workspace and user settings. Explicit globs are retained in merge mode. autoDetect: false also limits discovery to configured paths. Dependency folders, Git metadata, build outputs, generated files, reports and coverage are excluded. Boolean files.exclude and search.exclude settings are respected.

Example .vscode/settings.json for a nonstandard layout:

{
  "playwrightCucumber.discoveryMode": "settings",
  "playwrightCucumber.features": ["acceptance/**/*.feature"],
  "playwrightCucumber.stepDefinitions": ["test-glue/steps/**/*.ts"],
  "playwrightCucumber.hooks": ["test-glue/support/**/*.ts"],
  "playwrightCucumber.profile": "default",
  "[cucumber]": {
    "editor.defaultFormatter": "CorpRideConnect.playwright-cucumber-support",
    "editor.formatOnSave": true
  }
}

The standalone grammar includes the official Gherkin dialect keywords. Providers also match *.feature when another extension supplies the language association. Your default formatter is not changed automatically. Disable overlapping CodeLens or diagnostics in other extensions if you see duplicates.

All setting names below have the playwrightCucumber. prefix:

Run and Debug

Use Run Feature / Debug Feature above a Feature, and Run Scenario / Debug Scenario above a Scenario or Scenario Outline. Editor and Explorer context menus provide the same commands. Command Palette scenario actions use the cursor position. Editor run commands save dirty indexed feature/support documents in that project so CLI line selectors match the saved source.

Test Explorer shows workspace folder → file → Feature → Scenario/Outline → Examples → Row, with Rules grouped and Backgrounds marked as shared setup. Run and Debug profiles support all tests, selected branches, individual rows, exclusions, cancellation, output and source navigation. Backgrounds are not independently runnable. Tag/profile-filtered items are skipped.

Feature selections use their file path. Scenarios and rows use file.feature:line; duplicate names and regex characters in names are safe. Resolution prefers an explicit executable, then a local/ancestor Cucumber JS CLI, then non-installing package-manager execution for a declared Cucumber dependency. Windows .cmd, .bat and PowerShell shims are rejected as explicit executables; select node_modules/@cucumber/cucumber/bin/cucumber.js instead.

Cucumber combines profile feature paths with CLI paths. To isolate the requested scope, execution creates a temporary .playwright-cucumber-* directory in cwd. Its config adapter calls the project's Cucumber API inside the trusted child process, preserves the selected profile's runtime settings, and clears only its discovery paths before CLI selections are applied. The adapter and message report are deleted afterward. Existing project configuration is not rewritten. Cwd must be writable, and the runtime must expose @cucumber/cucumber/api (as Cucumber 11 does).

Output is sent to Test Explorer and the Playwright Cucumber Output channel. Structured Cucumber messages provide per-scenario status, duration and retry results. Debug launches the local CLI directly using pwa-node, with output in the Debug Console and child-process attachment enabled. Source maps loaded at runtime are supported, including inline maps in TypeScript steps, hooks and page helpers. Set breakpoints on executable lines in your original source. Cucumber config controls loaders, transpilation, hooks, World and Playwright lifecycle; no TypeScript loader is guessed or injected. Debug runs do not load terminal shell profiles; use playwrightCucumber.environment for environment overrides.

Navigation and formatting

Ctrl+Click/F12 resolves Given, When, Then and defineStep, including imported aliases, CommonJS destructuring and namespace imports. Literal Cucumber Expressions, JS regexes/flags and statically recognizable custom parameter types are supported. Outline placeholders use Examples values. All matching locations are returned by default. Computed registrations or parameter types may need simpler static declarations for navigation.

Undefined-step diagnostics appear after indexing completes. Matching runs in a worker with a timeout so a pathological project regex cannot freeze the extension host. Indexing is bounded to 5,000 files per folder by default, 2 MB per source file and 500 undefined-step diagnostics.

Format Document uses the official Gherkin AST. It normalizes leading/trailing blank lines, section/step spacing, indentation and aligned tables, while preserving comments, tags, descriptions, paragraph breaks, localized keywords, escaped cells and meaningful doc-string whitespace. LF/CRLF is preserved. Formatting twice produces no second change. Invalid Gherkin must be fixed before formatting.

Given, When and Then align beneath the scenario. And and But indent one additional level (also for localized keywords), with data tables and doc strings indented beneath their step:

@CreateReferrals
Feature: Create Referrals

  @TC484
  Scenario: Create Referrals with valid data
    Given user click on "Login"
      And user register with API
    When user click on "Referrals"
      And user click on "submit"
    Then user sees the confirmation

Single- and double-quoted step parameters use the same syntax color as data tables. The active theme determines that color; ordinary step text keeps its default foreground.

Commands, all prefixed with playwrightCucumber.: runFeature, debugFeature, runScenario, debugScenario, refreshTests, configurePaths, formatDocument, showOutput.

Workspace Trust and privacy

Restricted Mode supports safe discovery, navigation and formatting. Run/Debug check Workspace Trust before resolving or executing workspace code. Execution uses argument arrays with shell: false. Cancellation terminates owned process trees; workspace removal and deactivation cancel runs and debug sessions. Version 1 collects no telemetry.

Troubleshooting

• No tests/definitions: Run Refresh Tests, then Configure Paths. Check cwd, profile, globs and exclusions. Use settings mode for computed configs. Inspect the Output channel.
• Cannot launch: Install the project's dependencies, check nodeExecutable, and point cucumberExecutable at the actual JS entry. The extension never downloads a missing Cucumber runtime.
• Unknown TS extension or unbound breakpoint: Enable VS Code's built-in JavaScript Debugger and use Debug Scenario or Debug Feature. Set the breakpoint on an executable statement inside the selected step. Verify the same Cucumber config works in a terminal and configures the appropriate requireModule or import/loader. For precompiled TypeScript, enable compilerOptions.sourceMap in the test project's tsconfig.json and rebuild. While the session is active, run Debug: Diagnose Breakpoint Problems for details. CodeLens and Test Explorer generate their own launch configuration; editing .vscode/launch.json does not change those launches.
• Configuration/hook error: Inspect output. An aborted runtime is reported as an error. Check cwd write access if the temporary selection config cannot be created.
• No formatting: Fix syntax errors, check format.enable, and select this extension through Configure Default Formatter.
• Matching timeout: Simplify nested regex quantifiers or use Cucumber Expressions. Computed parameter types cannot be inferred safely.

Development and packaging

npm ci
npm run compile
npm run lint
npm test
npm run build
npm run test:web
npm run test:integration
npm run package

Integration tests use copied fixtures and a fresh VS Code profile. They verify real editor providers, Cucumber runs, Windows paths with spaces and JavaScript/TypeScript breakpoints. Set VSCODE_EXECUTABLE_PATH for a custom desktop executable; Windows defaults to the usual user installation. Other platforms use @vscode/test-electron to obtain VS Code. CUCUMBER_TEST_RESTRICTED=1 selects Restricted Mode tests. Reports are retained under .vscode-test/.

npm run test:web runs the browser bundle in VS Code's real web extension host. It checks virtual repository URIs, ancestor configuration/cwd, formatting, TypeScript navigation, Scenario Outline/custom parameters, multiple repositories, file changes, test discovery and worker timeout/recovery. npm run build also rejects unexpected external dependencies in the browser bundle.

The VSIX includes both desktop and browser production bundles, the matcher worker, grammar and documentation. No development dependencies are needed after installation. No binary icon is included; before Marketplace publication, optionally add an original 128×128 PNG and the manifest icon field. Publication is a separate maintainer action.

References: VS Code Testing API, Cucumber configuration, source filtering, message formatters.