Specwright

BDD authoring, test execution, and traceability for playwright-bdd in VS Code.

Write Gherkin scenarios, keep them connected to their step definitions, and run or debug the exact test you are editing. Specwright brings authoring and Playwright results together in VS Code.

What you can do

Write better feature files

Use built-in Gherkin highlighting, snippets, document outline, tag suggestions, and table formatting. Specwright can identify missing or ambiguous steps, validate Scenario Outline tables, and help create a matching step definition.

Keep steps connected

Go from a Gherkin step to its TypeScript or JavaScript definition, inspect the matching pattern on hover, find every scenario that uses a definition, and spot unused definitions. Suggestions come from the step definitions in your workspace.

Run and debug the right scenario

Discover features in the Testing view and run a feature, scenario, Scenario Outline, or individual Examples row. Use CodeLens or the Testing view to target an individual scenario or row; editor and Explorer context menus provide file-level actions. Results map back to the feature file as each scenario finishes, so a long run shows useful progress immediately.

Set breakpoints in .feature files or step definitions, then use VS Code's normal Debug action. Specwright generates the necessary specs, mirrors supported feature-file breakpoints, and removes the generated breakpoints when the session ends.

Manage a growing step library

The Steps panel groups definitions by keyword, highlights unmatched and unused steps, and provides one-click generation. It can also export shareable Markdown catalogs of steps or scenarios.

Connect scenarios to Xray Cloud

Experimental. The Traceability panel maps tagged scenarios to Xray Cloud tests, shows coverage in VS Code, and supports local-run publishing workflows. It can be evaluated with an existing Jira/Xray project, including a trial tenant when the account has the required permissions. No standalone sample project is required.

The Xray guide clearly identifies actions that only change your workspace, actions that read remote data, and actions that can create, update, attach, or publish remote Jira/Xray records.

Quick start

1. Install Specwright from the VS Code Marketplace.
2. Open a workspace already configured for playwright-bdd with one or more .feature files.
3. Open the Testing view. Specwright discovers scenarios when the view resolves, when you refresh, or when you start a run.
4. Choose Run or Debug for the feature, scenario, outline, or Examples row you need.

Specwright uses your existing playwright-bdd and Playwright configuration. If you use a monorepo, another package manager, or custom step paths, follow the getting started guide.

Common tasks

Highlights

• Run, debug, cancel, and inspect results from the Testing view, CodeLens, file-level editor menus, or the Command Palette.
• Treat Scenario Outline rows as first-class tests.
• Navigate between Gherkin steps and real Given, When, and Then definitions.
• Get autocomplete, hover, references, usage counts, diagnostics, quick fixes, and typed stub generation.
• Format Gherkin data tables and promote literal values to reusable step parameters.
• Organize discovered tests by feature, tag, file, scenario type, or as a flat list.
• Export step and scenario catalogs as Markdown.
• Use experimental Xray Cloud traceability from within VS Code.

Compatibility and prerequisites

• VS Code declares 1.99.0 as its minimum host. CI tests that exact host and one pinned current target.
• A project configured for playwright-bdd and Playwright.
• TypeScript or JavaScript step-definition files.
• Single-folder, multi-root, and monorepo workspaces are supported when their step paths and working directories are configured correctly.

The compatibility record names the exact VS Code, Playwright, and legacy playwright-bdd versions represented by current evidence. Playwright JSON is a legacy compatibility boundary, not a provider protocol.

Specwright can coexist with Cucumber (Gherkin) Full Support. Overlapping authoring features default to an automatic compatibility mode to avoid duplicate suggestions and diagnostics. You can change that behavior in Settings.

Specwright writes diagnostics to a VS Code log output channel. Use Developer: Set Log Level to control its detail and Specwright: Show Test Output to open it. For a support report, run Specwright: Open Support Snapshot. It previews a redacted JSON snapshot first and copies it only when you choose Copy Snapshot.

Documentation

• Getting started
• Run and debug tests
• Author feature files and manage steps
• Xray traceability
• Settings and workspace configuration
• Troubleshooting
• Development
• Release notes
• Contributing

Install from the command line

code --install-extension upscaled-dev.specwright

Support

If Specwright saves you time, consider buying me a coffee.

Acknowledgments

Specwright stands on the work of projects and communities that make BDD development in VS Code possible.

Test runner

playwright-bdd provides the Gherkin runner on top of Playwright that Specwright targets.

Original extension foundation

Behave Test Runner is the upstream VS Code extension that Specwright was forked from. Its Test Explorer wiring, organization strategies, and CodeLens scaffolding provided the starting point.

Gherkin ecosystem

Cucumber (Gherkin) Full Support is an independent VS Code extension for Gherkin authoring. Specwright is designed to coexist with it; see the compatibility settings.

Gherkin and the VS Code Extension API provide the language and platform that make the extension possible.

License

MIT