The Page Object Model

Why it matters

Without this structure, every test repeats the same locators and steps. When a button is renamed or a form gains a step, dozens of tests fail although the product works, and someone spends a day editing tests instead of testing.

Page objects make an interface change a one-class fix and let a test read as the scenario it checks. They do not make a bad locator good: a fragile locator in a page object is still fragile, only now in one place.

What belongs in a page object, and what stays out

A page object wraps a page, or part of one, with an API in the application's terms. It is created per test from the test's browser handle, such as the Playwright page fixture from the previous lesson, and is the only code that knows how its screen is built. The Selenium documentation states rules that fit any tool:

• Public methods are the services the page offers, named after user intent: placeOrder(), not clickBlueButton().
• Internals stay inside: locators, frames, the order of clicks and waits. A test never needs a selector.
• No assertions: a method returns data or an element, and the test decides what is correct. Fowler weighs both views and also favours keeping assertions out; checks that many tests repeat can go into shared assertion helpers. The one check that belongs inside is that the right page has loaded, made when the object is created. A JavaScript constructor cannot await, so Playwright page objects make it in the method that reaches the page, as placeOrder() does below.
• Navigation returns the next page object: cart.checkout() returns a CheckoutPage, so the return types document the flow.
• Different results of one action are different methods: signIn() returns the account page, signInExpectingError() the sign-in page.

Component objects: one class for a repeated part

Many parts of a screen are not pages: a header with search and a cart count, a row in an orders table, a date picker, a dialog. The Selenium documentation calls their classes page component objects; Fowler's example is an album list that contains album objects. Page objects compose them: CheckoutPage has a header, and OrdersPage returns an OrderRow for an order number.

The key technique is the root: a component object receives the locator of its own container and searches only inside it, so one class serves every row, and order('ORD-2026-000184').cancel() cannot click the neighbouring row's button. Playwright narrows a locator with filter({ hasText }) and searches inside it with getByRole; Selenium calls findElement on the parent element.

// components/order-row.ts: one class for every row of the orders table
import type { Locator } from '@playwright/test';

export class OrderRow {
  constructor(private readonly root: Locator) {}    // the row's own element

  status(): Locator {
    return this.root.getByTestId('order-status');
  }

  async cancel(): Promise<void> {
    await this.root.getByRole('button', { name: 'Cancel order' }).click();
  }
}

// pages/orders-page.ts: the page composes the component
import type { Page } from '@playwright/test';
import { OrderRow } from '../components/order-row';

export class OrdersPage {
  constructor(private readonly page: Page) {}

  order(orderNumber: string): OrderRow {
    const row = this.page.getByRole('row').filter({ hasText: orderNumber });
    return new OrderRow(row);
  }
}

// in a test
const ordersPage = new OrdersPage(page);
const row = ordersPage.order('ORD-2026-000184');
await row.cancel();
await expect(row.status()).toHaveText('Cancelled');

Try it: HTML Formatter

Worked example: refactoring a checkout test

An online store has twelve tests that pass through checkout, each repeating the steps of the first test below with good, user-facing locators.

After the refactoring, page objects hold the steps, a Header component holds the cart count, and the test states only the scenario and the expected outcome. CheckoutPage models the two outcomes of submitting as two methods sharing a private submit().

• "Place order" is renamed "Pay now": before, 12 tests change; after, one line in CheckoutPage.
• The cart count gets a new test id or moves elsewhere in the header: only Header.cartCount() changes, and no test.

// BEFORE: tests/checkout.spec.ts (these steps are copied into 12 tests)
test('customer pays with a saved address', async ({ page }) => {
  await page.goto('/cart');
  await page.getByRole('button', { name: 'Checkout' }).click();
  await page.getByRole('radio', { name: 'Home' }).check();
  await page.getByRole('button', { name: 'Place order' }).click();
  await expect(page.getByRole('heading', { level: 1 }))
    .toHaveText('Thank you for your order');
  await expect(page.getByRole('banner').getByTestId('cart-count')).toHaveText('0');
});

// AFTER: pages/checkout-page.ts (CartPage, ConfirmationPage and the
// Header component are written the same way; imports omitted)
export class CheckoutPage {
  readonly header: Header;

  constructor(private readonly page: Page) {
    this.header = new Header(page);
  }

  async placeOrder(address: string): Promise<ConfirmationPage> {
    await this.submit(address);
    await this.page.waitForURL('**/order/confirmation');   // the page-loaded check
    return new ConfirmationPage(this.page);
  }

  async placeOrderExpectingError(address: string): Promise<CheckoutPage> {
    await this.submit(address);
    return this;                      // stays on checkout, which shows the error
  }

  errorMessage(): Locator {
    return this.page.getByRole('alert');
  }

  private async submit(address: string): Promise<void> {
    await this.page.getByRole('radio', { name: address }).check();
    await this.page.getByRole('button', { name: 'Place order' }).click();
  }
}

// AFTER: tests/checkout.spec.ts
test('customer pays with a saved address', async ({ page }) => {
  const cart = await new CartPage(page).open();
  const checkout = await cart.checkout();
  const confirmation = await checkout.placeOrder('Home');
  await expect(confirmation.heading()).toHaveText('Thank you for your order');
  await expect(confirmation.header.cartCount()).toHaveText('0');
});

Try it: Text Diff Try it: JavaScript Formatter

The Screenplay pattern: actors, tasks and questions

Page objects organise test code around screens; the Screenplay pattern organises it around the people who use the system and their goals. Serenity BDD for Java and Serenity/JS implement it; its concepts, in Serenity/JS terms, are below.

Because an actor can have several abilities, one scenario can set up an order through the API and check it in the browser.

• Actors: people or external systems that interact with the system under test, such as Layla, a returning customer.
• Abilities: thin wrappers around the libraries an actor uses, such as Playwright for the browser or an HTTP client for a REST API.
• Interactions: low-level activities through one interface, such as clicking a button or sending a request.
• Tasks: sequences of activities that form a business step, such as PlaceOrder built from opening the cart, choosing an address and submitting.
• Questions: retrieve information, such as the order status on the page or in the API response; the test asserts on the answer.

Anti-patterns that turn page objects into a burden

Each of these makes the suite harder to change.

• Assertions in page objects, such as verifyOrderTotal(): the test no longer shows what it expects, and tests that expect different things cannot share the method.
• The god page: a BasePage of hundreds of lines that every page inherits, or one class for a whole single-page app. Prefer small classes and composition (a page has a header) to deep inheritance.
• Exposing the steps: tests click and fill a page object's elements one by one, so the flow lives in the test again. Returning a locator for a retrying assertion, as Playwright's examples do, is fine.
• Fixed sleeps in methods: a waitForTimeout(3000) inside placeOrder() slows every test that calls it and still fails on a slow day.
• Flag-driven methods: checkout(true, false, 'Home') hides several flows behind one name.
• Shared state: a static driver or one page object for the whole suite breaks parallel runs; create page objects per test or through a fixture.

Frequently asked questions

References

• Page object models — SeleniumSelenium ProjectThe page object pattern: one class per page or component that hides locators and exposes the actions a test needs, reducing duplication.
• Page Object (Martin Fowler)martinfowler.com · 2013The page object pattern: wrap a page in an application-specific API so tests do not touch raw HTML, and keep assertions in the tests rather than in the page object.
• Locators — PlaywrightMicrosoft (Playwright)How Playwright finds elements, why locators re-resolve and auto-wait, and why role-based locators are recommended first.
• Best Practices — PlaywrightMicrosoft (Playwright)Test user-visible behaviour, keep tests isolated, prefer resilient locators and web-first assertions, and debug with traces.