# playwright-bdd: Gherkin scenarios compiled into native Playwright tests

> playwright-bdd is an MIT licensed TypeScript package that converts .feature files into native Playwright tests, so a Given, When, Then suite runs on the Playwright runner with its fixtures, parallelism, traces and reports, and the same scenarios can be drafted and reviewed with a coding agent. It suits a team whose product spec already lives in Gherkin, and it is a poor fit if your team writes its specs in plain Markdown and has no interest in the Cucumber vocabulary.

**vitalets/playwright-bdd** — BDD testing with Playwright runner

- Repository: https://github.com/vitalets/playwright-bdd
- Website: https://vitalets.github.io/playwright-bdd/
- Stars: 816 · Forks: 96
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/vitalets-playwright-bdd

## The feature file is the artifact a person and an agent share

Playwright-BDD runs BDD tests with the Playwright runner, and the README's first section explains why that matters now.

Behaviour-Driven Development describes product requirements as Given, When, Then scenarios written in plain text files. In the AI era, the README argues, these scenarios become valuable artifacts for agents because they are readable, so you can easily draft and refine scenarios with an agent to clearly define the behaviour, and they are executable, so the same scenarios can be run as automated tests to verify the implementation.

The argument the README makes against plain Markdown is the interesting part. Unlike plain Markdown specs, BDD does not just describe a feature, it makes the spec live and keeps it aligned with the codebase.

That is the whole pitch, and it is aimed at teams where an agent writes the implementation. The README shows the change in the form of a diff on a feature file.

```diff
Feature: Agentic development

  Scenario: Implement a new feature
    Given business requirements
    When a human defines the behavior as BDD steps
-   Then the human implements the feature and verifies it with tests
+   Then the agent implements the feature and verifies it with tests
```

And it states the ultimate goal in one line: review only feature files and let automations check code quality and scenario compliance.

That is a specific workflow, and it is worth noticing that it does not need the agent to understand the test framework. The agent writes code and runs the suite. The human reads the feature files.

## Feature files are converted into native Playwright tests

The Why Playwright Runner section explains the choice of runner, and it is a list of what you inherit rather than a list of what the package adds.

Playwright provides both browser automation APIs and a powerful test runner, and Playwright-BDD converts .feature files into native Playwright tests, so you can use all Playwright runner capabilities.

The capabilities named are automatic browser setup and cleanup, auto-waiting for page elements, auto-capture of screenshots, videos and traces, parallel execution and sharding, built-in reports and visual comparison testing, and Playwright fixtures.

The word native is doing the work in that sentence. The output is a Playwright test file, not a script for a different runner, which means the fixtures, the reporters, the parallelism model and the trace viewer are the ones your team already uses. That is the difference between a BDD layer that is another thing to configure and one that disappears into an existing pipeline.

The trade-off is that you inherit the Playwright runner's model rather than the Cucumber one. There is no world where a .feature file and the Playwright config are the same kind of artifact, and the mapping between them is done by this package rather than by Playwright itself.

The repository root shows a project that takes the surrounding work seriously. There is an eslint config, a knip config for unused dependency analysis, a lint-staged config, separate tsconfig files for the build and the tests, a .nvmrc and an .npmrc, an AGENTS.md, and separate scripts for building, running the examples and validating the documentation.

## Tagging, scoping and decorators are where the control lives

The Extras section is a short list, and each item solves a problem that appears once a feature directory grows.

Advanced tagging by path and special tags means you can select which scenarios run from the command line based on where the feature file lives, and the documentation links separate pages for tags from path and for special tags. In practice this is what makes a large suite usable, because a developer working on one screen should not have to run the entire suite to check their change.

Step decorators for class methods let you attach behaviour to a method rather than repeating it at every call site, and scoped step definitions limit where a definition applies, which is the mechanism that stops two features from both defining a step called when the user logs in.

Exporting steps for AI is the feature that connects back to the agent workflow described at the top of the README. The idea is that the set of step definitions is exported in a form an agent can read, so the agent knows what vocabulary the scenarios use rather than inventing step names that do not exist.

Re-usable step functions is the smaller one, and it is the ordinary version of the same idea: a helper that several steps share, defined once.

Together these are the things a BDD layer needs once it is more than a demo. The documentation site is organised around exactly these topics, with pages for writing features, writing steps, decorators, scoping, reusing step functions and an agent skill.

## bddgen, the skill and the examples folder

The package ships a console script and a separate skill, and the README points at both as the entry points.

The package manifest names the binary bddgen, mapped to dist/cli/index.js, and the npm scripts show two of its commands.

```json
  "bin": {
    "bddgen": "dist/cli/index.js"
  },
  "engines": {
    "node": ">=20"
  },
  "peerDependencies": {
    "@playwright/test": ">=1.53"
  },
```

```json
    "help": "npx tsx src/cli -h",
    "env": "npx tsx src/cli env",
```

So there is a command line tool, reachable both as an installed binary and through the source with tsx, with a help output and an env subcommand that reports the environment the CLI expects.

Alongside it there is a skill, and the README tells you to install the playwright-bdd skill to get started. The repository has a skills directory for it, and the getting started documentation has a page for the agent skill. That is the AI workflow of the project expressed as an installable unit rather than as prose.

The examples directory is unusually well populated and is the fastest way to see the shape of the thing. It contains ai, api-testing, auth-in-steps, auth, basic-cjs, basic-esm, cucumber-style and decorators, plus a package.json for the examples themselves. The presence of both basic-cjs and basic-esm is a hint about the module format, since the package declares type commonjs while the examples cover both module systems. There is also a separate fully working repository, playwright-bdd-example, which you can clone instead of reading the examples in place.

## Eleven Playwright releases is the support window

The README has one short section on version support, and it is a hard number.

playwright-bdd supports the latest stable Playwright release and the 10 previous releases.

That is a wide window by the standards of a tool that depends on another project's internals, and it is the sort of statement that only means something if you know the cost of being wrong about it. This package generates Playwright test code, so it is coupled to how Playwright structures its runner, its fixtures and its test discovery. A Playwright upgrade can break the generated output in ways that are not visible until the suite runs.

The peer dependency requirement in the package manifest is @playwright/test at 1.53 or later, and the engine requirement is Node 20 or later. So the floor for the Playwright side is fixed and reasonably modern.

The release history of the package itself is regular. The listed releases are v9.2.1 on 2026-09-06, v9.2.0 on 2026-06-18 and v9.1.0 on 2026-06-13, and the last push to the repository was on 2026-10-19. The version in the package manifest is a next prerelease, 9.3.0-next.1, which is consistent with a project that cuts a prerelease from main and publishes a tagged release from it.

The maintenance model is visible in the sponsors section, which thanks Currents and TestMu AI among others, and the README asks readers to consider becoming a sponsor, saying that even small contributions help the author dedicate more time to maintenance, new features and community support.

## Conclusion

playwright-bdd suits a team that has already decided that behaviour is described in Gherkin and wants those scenarios to run as part of an ordinary Playwright suite, since the conversion produces native tests rather than a parallel framework, and the tag and scoping features make it practical to keep a large feature directory manageable. It does not suit a team that writes Markdown specifications and likes them that way, because the point of the package is that the spec stays executable rather than drifting from the code. Before you adopt it, read the writing steps and tagging documentation, decide whether the step definitions you already have can be reused or need rewriting, and check the compatibility line, since the package supports the latest stable Playwright release and the ten before it, so a project on an older Playwright will need to plan an upgrade.

## FAQ

### What does playwright-bdd do?

It converts .feature files into native Playwright tests, so a Given, When, Then suite runs on the Playwright runner and can use its fixtures, parallel execution, traces, reports and visual comparison testing.

### Why use the Playwright runner for BDD tests?

Because the generated output is a native Playwright test rather than a separate framework, so automatic browser setup and cleanup, auto-waiting for elements, screenshot, video and trace capture, parallelism, sharding, built-in reports and Playwright fixtures all work as they do in an ordinary Playwright project.

### Which Playwright versions does playwright-bdd support?

The README states that it supports the latest stable Playwright release and the 10 previous releases, and the package manifest declares a peer dependency on @playwright/test of 1.53 or later and requires Node 20 or later.

### What extras does playwright-bdd provide beyond converting feature files?

Advanced tagging by path and special tags, step decorators for class methods, scoped step definitions, exporting steps for AI, and re-usable step functions, with a separate playground-bdd skill that the README tells you to install to get started.

### How do I install playwright-bdd?

The package is published to npm as playwright-bdd, and the repository also ships a console script named bddgen mapped to dist/cli/index.js. The README points to the getting started documentation and to an examples folder plus a separate fully working playwright-bdd-example repository.

## Sources

- [License: MIT](https://github.com/vitalets/playwright-bdd/blob/main/LICENSE)
- [Project website](https://vitalets.github.io/playwright-bdd/)
- [README](https://github.com/vitalets/playwright-bdd/blob/main/README.md)
- [Releases](https://github.com/vitalets/playwright-bdd/releases)
- [vitalets/playwright-bdd on GitHub](https://github.com/vitalets/playwright-bdd)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vitalets-playwright-bdd