playwright-bdd

Run BDD tests with Playwright runner

🚀 Getting Started 📚 Documentation ▶️ Example 📝 Changelog

BDD in the Era of AI

Behavior-Driven Development (BDD) describes product requirements as Given / When / Then scenarios written in .feature files. These scenarios are valuable artifacts for AI agents because they are both:

readable: you can easily refine them during planning to give the agent a clear goal.
executable: once the code is written, the agent runs the same scenarios as tests to verify the implementation.

Unlike plain markdown specs, BDD does not just describe the feature; it makes the spec live and keeps it aligned with the codebase.

Install the playwright-bdd skill and check out the blog post on using BDD in agentic workflows.

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

Why Playwright Runner?

Playwright 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

How It Works

Extras

Playwright-BDD has several unique features:

🔥 Advanced tagging by path and special tags
🎩 Step decorators for class methods
🎯 Scoped step definitions
✨ Exporting steps for AI
♻️ Re-usable step functions

Documentation

Check out the documentation website.

Demos

Check out examples folder
Clone the fully working repo: playwright-bdd-example

Playwright Versions Support

playwright-bdd supports all non-deprecated versions of Playwright. To check which Playwright versions are currently deprecated, run:

npm show @playwright/test@1 deprecated

Changelog

Check out the latest changes in the CHANGELOG.md.

💖 Sponsors

Great thanks to the amazing people and companies already supporting Playwright-BDD! Your help keeps the project alive and growing:

If you find Playwright-BDD useful in your personal or work projects, consider becoming a sponsor. 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:

Contributing

Your contributions are welcome! Please review CONTRIBUTING.md for the details.

My Other Playwright tools

playwright-timeline-reporter - Interactive timeline report for Playwright test runs.
@global-cache/playwright - Key-value cache for sharing data between parallel workers.
request-mocking-protocol - Mock server-side API calls in Playwright.
playwright-network-cache - Speed up Playwright tests by caching network requests on the filesystem.
playwright-magic-steps - Auto-transform JavaScript comments into Playwright steps.

License

This project is licensed under the MIT License, allowing you to use, modify, and share the code freely, even for commercial purposes. Enjoy building something amazing! 🎉