<div align="center">
<a href="https://vitalets.github.io/playwright-bdd">
<img width="128" alt="playwright-bdd" src="./docs/logo.svg">
</a>
</div>
<h2 align="center">Playwright-BDD</h2>
<div align="center">
Run BDD tests with Playwright runner
</div>
<div align="center">
[](https://github.com/vitalets/playwright-bdd/actions/workflows/lint.yaml)
[](https://github.com/vitalets/playwright-bdd/actions/workflows/test.yaml)
[](https://www.npmjs.com/package/playwright-bdd)
[](https://www.npmjs.com/package/playwright-bdd)
[](https://github.com/vitalets/playwright-bdd/blob/main/LICENSE)
</div>
<p align="center">
🚀 <a href="https://vitalets.github.io/playwright-bdd/#/getting-started/index">Getting Started</a>
📚 <a href="https://vitalets.github.io/playwright-bdd/">Documentation</a>
▶️ <a href="https://github.com/vitalets/playwright-bdd-example">Example</a>
📝 <a href="https://github.com/vitalets/playwright-bdd/blob/main/CHANGELOG.md">Changelog</a>
</p>
## BDD in the Era of AI
[Behavior-Driven Development (BDD)](https://cucumber.io/docs/bdd/) describes product requirements as `Given / When / Then` scenarios written in plain-text files:
```feature
Feature: Buying a product
Scenario: Complete a purchase
Given I am on the "iPhone 18" page
When I click "Add to cart"
And I proceed to checkout
And I complete the payment
Then I see an order confirmation containing "iPhone 18"
```
In the AI era, these scenarios become valuable artifacts for agents because they are both:
* ✅ **Readable**: You can easily draft and refine scenarios with an agent to clearly define the behavior.
* ✅ **Executable**: The same scenarios can be executed as automated tests to verify the implementation.
Unlike plain Markdown specs, BDD does not just describe a feature; it makes the spec live and keeps it aligned with the codebase.
Watch the <img src="https://cdn.simpleicons.org/youtube/FF0000" align="absmiddle" width="24" height="24" alt="YouTube"> [1-minute workflow overview](https://www.youtube.com/watch?v=hDL9j23EDNs) or read the [blog post](https://vitalets.github.io/posts/bdd-agentic-workflow/) to see agentic BDD in action. The ultimate goal: **review only feature files** and let automated guardrails check code quality and scenario compliance.
To bring this workflow to your project, [set up Playwright-BDD](https://vitalets.github.io/playwright-bdd/#/getting-started/index) and add the [playwright-bdd skill](https://vitalets.github.io/playwright-bdd/#/getting-started/agent-skill) for your AI coding agent.
## Why Playwright Runner?
[Playwright](https://playwright.dev/) provides both browser automation APIs and a powerful test runner. Playwright-BDD converts `.feature` files into native Playwright tests, so you can use all Playwright runner capabilities:
- 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
- Playwright fixtures
- [...and more](https://playwright.dev/docs/library#key-differences)
## How It Works
<img align="center" src="https://raw.githubusercontent.com/vitalets/playwright-bdd/refs/heads/main/docs/_media/schema.png"/>
## Extras
Playwright-BDD has several unique features:
- 🔥 Advanced tagging [by path](https://vitalets.github.io/playwright-bdd/#/writing-features/tags-from-path) and [special tags](https://vitalets.github.io/playwright-bdd/#/writing-features/special-tags)
- 🎩 [Step decorators](https://vitalets.github.io/playwright-bdd/#/writing-steps/decorators) for class methods
- 🎯 [Scoped step definitions](https://vitalets.github.io/playwright-bdd/#/writing-steps/scoped)
- ✨ [Exporting steps](https://vitalets.github.io/playwright-bdd/#/writing-features/chatgpt) for AI
- ♻️ [Re-usable step functions](https://vitalets.github.io/playwright-bdd/#/writing-steps/reusing-step-fn)
## Documentation
Check out the [documentation website](https://vitalets.github.io/playwright-bdd/#/).
## Demos
- Check out [`examples`](/examples) folder
- Clone the fully working repo: [playwright-bdd-example](https://github.com/vitalets/playwright-bdd-example)
## Playwright Versions Support
`playwright-bdd` supports the latest stable Playwright release and the **10 previous releases**.
## Changelog
Check out the latest changes in the [CHANGELOG.md](https://github.com/vitalets/playwright-bdd/blob/main/CHANGELOG.md).
## 💖 Sponsors
Great thanks to the **amazing people and companies** already supporting Playwright-BDD! Your help keeps the project alive and growing:
<p align="center">
<a href="https://currents.dev/" target="_blank">
<img src="./docs/_media/sponsors/currents.svg" alt="Currents" width="300" />
</a>
</p>
<p align="center">
<a href="https://www.testmuai.com/?utm_medium=sponsor&utm_source=playwright-bdd" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./docs/_media/sponsors/testmu-ai-white.svg" />
<source media="(prefers-color-scheme: light)" srcset="./docs/_media/sponsors/testmu-ai-black.svg" />
<img src="./docs/_media/sponsors/testmu-ai-black.svg" alt="TestMu AI" width="300">
</picture>
</a>
</p>
<p align="center">
<!-- sponsors --><a href="https://github.com/alescinskis"><img src="https://github.com/alescinskis.png" width="60px" alt="User avatar: Arturs Leščinskis" /></a><a href="https://github.com/alexhvastovich"><img src="https://github.com/alexhvastovich.png" width="60px" alt="User avatar: " /></a><!-- sponsors -->
</p>
If you find Playwright-BDD useful in your personal or work projects, consider [becoming a sponsor](https://github.com/sponsors/vitalets). Even small contributions help me dedicate more time to maintenance, new features, and community support.
## Feedback & Community
Feel free to report a bug, propose a feature or share your experience:
* [GitHub issues](https://github.com/vitalets/playwright-bdd/issues)
* [Playwright-BDD Discord](https://discord.gg/5rwa7TAGUr)
## Contributing
Your contributions are welcome! Please review [CONTRIBUTING.md](https://github.com/vitalets/playwright-bdd/blob/main/.github/CONTRIBUTING.md) for the details.
## My Other Playwright tools
* [playwright-timeline-reporter](https://github.com/vitalets/playwright-timeline-reporter) - Interactive timeline report for Playwright test runs.
* [@global-cache/playwright](https://github.com/vitalets/global-cache) - Key-value cache for sharing data between parallel workers.
* [request-mocking-protocol](https://github.com/vitalets/request-mocking-protocol) - Mock server-side API calls in Playwright.
* [playwright-network-cache](https://github.com/vitalets/playwright-network-cache) - Speed up Playwright tests by caching network requests on the filesystem.
* [playwright-webext](https://github.com/vitalets/playwright-webext) - Testing browser extensions with Playwright.
## License
This project is licensed under the [MIT License](https://github.com/vitalets/playwright-bdd/blob/main/LICENSE), allowing you to use, modify, and share the code freely, even for commercial purposes. Enjoy building something amazing! 🎉