Playwright + BDD: Building an End-to-End Test Automation Framework from Scratch

A practical guide to building a maintainable E2E test suite with Playwright, TypeScript and Gherkin.

Why this article? As a QA Engineer, I often hear that test automation is "just clicking buttons with code." In this post I walk through a production-ready approach: a BDD-driven E2E framework that is readable by devs/POs/QAs, easy to maintain, and green in CI — built with Playwright, TypeScript and playwright-bdd (Gherkin in Portuguese, the Belgium of the project's origin, but the pattern applies to any language).

This is a write-up of a portfolio project — the full, runnable source is on GitHub.

The stack

Project structure

├── features/            # BDD scenarios (Gherkin)
│   ├── login.feature
│   ├── inventory.feature
│   └── checkout.feature
├── steps/               # Step definitions (bridge Gherkin to code)
├── fixtures/            # Extended fixtures + injected Page Objects
├── src/pages/           # Page Objects
├── support/             # Environment config (.env)
└── playwright.config.ts # Playwright + playwright-bdd config

1. BDD-first: write the feature, then the code

The beauty of BDD is the conversation. Scenarios are written in plain language, so Product Owners, Devs and QAs share the same understanding:

Feature: Login
  Scenario: Login with valid credentials
    Given I am on the login page
    When I fill in the valid credentials
    Then I am taken to the products page

2. Bind Gherkin to code with step definitions

Each Given/When/Then maps to a step definition that uses fixtures to inject Page Objects:

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

When('I fill in the valid credentials', async ({ loginPage }) => {
  await loginPage.login(STANDARD_USER, PASSWORD);
});

Then('I am taken to the products page', async ({ inventoryPage }) => {
  await inventoryPage.expectVisible();
});

3. Page Objects: keep selectors in one place

A Page Object encapsulates the page's elements and actions, so the framework stays maintainable when the UI changes:

export class LoginPage {
  constructor(readonly page: Page) {
    this.username = page.locator('#user-name');
    this.password = page.locator('#password');
    this.submit = page.locator('#login-button');
  }

  async login(user: string, pass: string) {
    await this.page.goto('/');
    await this.username.fill(user);
    await this.password.fill(pass);
    await this.submit.click();
  }
}

4. Pluggable fixtures make steps concise

Using test.extend() + createBdd(), the Page Objects are injected into every step — no globals, no setup duplication.

5. Report & CI

• Allure gives a rich, visual report; the CI publishes it on GitHub Pages (a live, navigable link in your README).
• Robustness is a feature: workers: 1 + navigation retries tame flaky network access to public demo apps — the same lesson applies to single-session systems.

Takeaways

• BDD is a collaboration tool, not just syntax.
• Page Objects + typed fixtures = the difference between a script that breaks and a framework that scales.
• Green CI with published reports is what makes a portfolio credible.

Want the full code? Check out the open-source project linked on my GitHub, where all 7 scenarios run green in CI with an Allure report deployed to GitHub Pages.

Jessica Sales — QA Engineer, focused on end-to-end automation, API testing and applying AI to the QA lifecycle.