Playwright Page Object Model Guide
PDF Downloads

Playwright in brief

Playwright is an open-source end-to-end testing framework from Microsoft that drives Chromium, Firefox and WebKit browsers through a single API, with bindings for JavaScript and TypeScript, Python, Java and .NET. Two features shape how tests are written. First, auto-waiting: before performing an action, Playwright waits for the element to be attached, visible, stable and enabled, which removes most manual waits. Second, web-first assertions, such as expect(locator).toBeVisible(), which retry until the condition is met or a timeout expires. The built-in test runner adds parallel execution, fixtures, retries, tracing and HTML reports. This page uses the TypeScript test runner.

Playwright compared with Selenium at a glance

Why page objects still help

Auto-waiting and good locators make Playwright tests more stable, but the maintenance argument for page objects is unchanged. If twenty tests each contain page.getByLabel('Email').fill(...), a label change touches twenty files. A page class puts each locator and action in one place and lets tests read as user stories. Keep the pattern lightweight: Playwright locators are already descriptive, so page classes need only wrap repeated flows and elements.

A login page object in TypeScript

Illustrative structure for Playwright Test. Replace the URL path and labels with your application's.

// pages/login.page.ts
import { Page, Locator, expect } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly email: Locator;
  readonly password: Locator;
  readonly submit: Locator;
  readonly error: Locator;

  constructor(page: Page) {
    this.page = page;
    this.email = page.getByLabel('Email');
    this.password = page.getByLabel('Password');
    this.submit = page.getByRole('button', { name: 'Log in' });
    this.error = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async loginAs(user: string, pass: string) {
    await this.email.fill(user);
    await this.password.fill(pass);
    await this.submit.click();
  }

  async expectError(message: string) {
    await expect(this.error).toContainText(message);
  }
}

Using the page object in tests, with a fixture

A fixture creates the page object for each test, so tests receive it as a parameter.

// fixtures.ts
import { test as base } from '@playwright/test';
import { LoginPage } from './pages/login.page';

export const test = base.extend<{ loginPage: LoginPage }>({
  loginPage: async ({ page }, use) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await use(loginPage);
  }
});

export { expect } from '@playwright/test';

// tests/login.spec.ts
import { test, expect } from './fixtures';

test('valid user reaches the dashboard', async ({ loginPage, page }) => {
  await loginPage.loginAs('test.user@example.com', process.env.TEST_PASSWORD!);
});

Locator choices in Playwright

Good practice

• → Prefer role, label and test-id locators over CSS and XPath.
• → Use web-first assertions that retry, not manual checks of values read once.
• → Keep page objects thin; do not duplicate Playwright's own waiting logic.
• → Isolate tests: each test gets a fresh browser context, so avoid depending on other tests.
• → Authenticate once through a setup step and reuse stored state where appropriate.
• → Enable traces on first retry in CI to diagnose failures.

Running in CI

Playwright Test runs headless by default and supports sharing tests across machines, retries, and artifacts such as screenshots, videos and traces. In a pipeline, install the browsers with the Playwright install command, run the tests and upload the HTML report and traces. Store credentials as secrets and pass them through environment variables, as in the example above. Check the official Playwright documentation for the exact commands and current options for your version.

Common mistakes

Useful Playwright config settings

A starting configuration; check the current Playwright documentation for exact options.

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  retries: process.env.CI ? 1 : 0,
  use: {
    baseURL: process.env.BASE_URL || 'https://example.com',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  reporter: [['html', { open: 'never' }]],
});

Quick checklist

• ✓ Locators use roles, labels or test ids.
• ✓ No manual sleeps.
• ✓ Each test is independent.
• ✓ Secrets come from environment variables.
• ✓ Traces and reports are saved in CI.