Cucumber BDD With Playwright: Gherkin Scenarios to Executable TypeScript Tests

BDD bridges business and engineering. Cucumber scenarios in Gherkin syntax let stakeholders define acceptance criteria that become executable Playwright tests.

🎭 Want to master this with real projects? Join the Playwright Automation Mastery course at The Testing Academy.

Setup: Playwright + Cucumber

npm install -D @cucumber/cucumber @playwright/test ts-node

Feature File

# features/login.feature
Feature: User Login

  Scenario: Successful login with valid credentials
    Given I am on the login page
    When I enter email "admin@test.com"
    And I enter password "password123"
    And I click the sign in button
    Then I should be redirected to the dashboard
    And I should see the welcome message

  Scenario: Failed login with wrong password
    Given I am on the login page
    When I enter email "admin@test.com"
    And I enter password "wrong"
    And I click the sign in button
    Then I should see an error message "Invalid credentials"

Step Definitions

// steps/login.steps.ts
import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';
import { page } from '../support/world';

Given('I am on the login page', async () => {
  await page.goto('/login');
});

When('I enter email {string}', async (email: string) => {
  await page.getByLabel('Email').fill(email);
});

When('I enter password {string}', async (password: string) => {
  await page.getByLabel('Password').fill(password);
});

When('I click the sign in button', async () => {
  await page.getByRole('button', { name: 'Sign in' }).click();
});

Then('I should be redirected to the dashboard', async () => {
  await expect(page).toHaveURL(/dashboard/);
});

Then('I should see the welcome message', async () => {
  await expect(page.getByText('Welcome')).toBeVisible();
});

Then('I should see an error message {string}', async (message: string) => {
  await expect(page.getByRole('alert')).toContainText(message);
});

When BDD Adds Value vs Overhead

Use BDD When	Skip BDD When
Business stakeholders read/write scenarios	Only developers write and read tests
Acceptance criteria drive development	Requirements are purely technical
Regulatory compliance needs readable specs	Speed of execution matters more
Multiple teams need shared understanding	Small team with tight communication

Scenario Outline: Data-Driven BDD

Scenario Outline: Login validation
  Given I am on the login page
  When I enter email "<email>"
  And I enter password "<password>"
  And I click the sign in button
  Then I should see "<result>"

  Examples:
    | email            | password  | result              |
    | admin@test.com   | pass123   | Dashboard           |
    | admin@test.com   | wrong     | Invalid credentials |
    | invalid-email    | pass123   | Invalid email       |
    |                  | pass123   | Email required      |