playwright-bdd

Playwright-BDD allows you to run Behavior-Driven Development (BDD) scenarios (written in .feature files using Given / When / Then syntax) directly using the Playwright test runner.

By converting BDD scenarios into native Playwright tests, you gain access to all standard Playwright runner features, including:

• 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

Beyond standard BDD support, Playwright-BDD provides several advanced capabilities to enhance the testing experience:

• Advanced Tagging: Support for tagging scenarios by file path or using special reserved tags.
• Step Decorators: Use decorators on class methods to define step definitions.
• Scoped Step Definitions: Restrict the scope of step definitions.
• Exporting Steps: Capability to export steps to facilitate AI-driven development (e.g., for ChatGPT).
• Re-usable Step Functions: Ability to reuse step logic across different scenarios.

When you run bddgen, Playwright-BDD generates standard Playwright spec files in a .features-gen directory. These generated files wrap your Gherkin scenarios into test.describe and test blocks. Inside the test body, the steps are called as functions (e.g., await Given('...')), which internally look up the implementation you provided in your step files.

// Example of a generated file in .features-gen/sample.feature.spec.js
import { test } from 'playwright-bdd';

test.describe('Playwright site', () => {
  test('Check get started link', async ({ Given, When, Then }) => {
    await Given('I am on home page');
    await When('I click link "Get started"');
    await Then('I see in title "Installation"');
  });
});

Playwright-BDD decouples test generation from test execution. Instead of running BDD scenarios on-the-fly, it generates standard Playwright test files. This allows you to leverage the full Playwright ecosystem, including:

• Running single tests via the VS Code extension.
• Debugging and setting breakpoints on specific BDD steps.
• Using Playwright's --ui mode to watch for changes.
• Using all standard Playwright tooling and features.

This approach avoids issues with circular dependencies in watch mode and excessive re-generation caused by the Playwright config being executed multiple times by different sources (workers, UI mode, etc.).

Each step is defined with a pattern that matches the Gherkin step text. You can use two types of patterns:

1. Cucumber expressions: String patterns using typed parameters like {string}, {int}, or {float}.
2. Regular expressions: Used for complex matching. Capture groups in the regex are passed as step parameters to the function.

Cucumber expression example

Given('I open url {string}', async ({ page }, url: string) => {
  await page.goto(url);
});

Regular expression example

Then(/I should see (success|error) message/, async ({ page }, status: string) => {
  await expect(page.getByRole('alert')).toHaveText(status);
});

While arrow functions are preferred in Playwright-style, you can use the this context (the Default World) for migration from CucumberJS. To do this, you must use regular functions instead of arrow functions.

Playwright-BDD provides an empty object {} as the default world.

Given('step 1', async function ({ page }) {
  this.foo = 'bar';
});

Then('step 2', async function () {
  expect(this.foo).toEqual('bar');
});

You can apply multiple step decorators (e.g., multiple @When or a mix of @Given and @When) to the same method. This allows a single implementation to support different natural language phrasings or different step keywords without duplicating code.

Each decorator registers a separate step definition that points to the same underlying method implementation.

export @Fixture('todoPage') class TodoPage {
  @When('a item {string} exists')
  @When('a item called {string} is added')
  async addItem(itemName: string) {
    await this.inputField.fill(itemName);
    await this.addItemButton.click();
  }

  @Then('result is {int}')
  @Then('I see result {int}')
  async checkResult(value: number) {
    await expect(this.resultElement).toHaveText(String(value));
  }
}

When Page Object Models use inheritance, Playwright-BDD automatically attempts to resolve steps using a single fixture. If a scenario uses a step from a parent class and a step from a child class, Playwright-BDD will use the child class's fixture for both steps to avoid creating multiple separate fixtures.

Important: Ensure that both the parent and child POMs are covered by the steps pattern defined in your playwright.config.ts.

Forcing a specific fixture

If you want to override the automatic resolution and force a specific fixture to be used for a scenario or feature, use the @fixture:%name% tag in your Gherkin file.

@fixture:adminTodoPage
Feature: Some feature

    Background: 
      Given I am on todo page # <- will use AdminTodoPage

    Scenario: Adding todos
      When I add todo "foo"   # <- will use AdminTodoPage