A Page Object Model (POM) puts the selectors and actions of one page in one class, so your tests read like intentions and a UI change is fixed in one place. Here is the smallest version that is still useful, written for Playwright Test with TypeScript. I ran every file below against the public Playwright demo app, TodoMVC, with Playwright 1.65.
Project layout
playwright.config.ts pages/todo-page.ts tests/todo.spec.ts The config, and a trap
// playwright.config.ts import { defineConfig } from '@playwright/test'; export default defineConfig({ testDir: './tests', use: { baseURL: 'https://demo.playwright.dev/todomvc/' }, }); Note the trailing slash. Playwright resolves page.goto() paths with the standard URL rules. With baseURL: '.../todomvc' (no slash), goto('/') goes to https://demo.playwright.dev/, not to the app, and the first fill() times out waiting for an input that is not there. The safe pattern when your app lives under a path: keep the trailing slash in baseURL and use a relative path, goto('./').
The page object
// pages/todo-page.ts import { type Locator, type Page, expect } from '@playwright/test'; export class TodoPage { readonly page: Page; readonly newTodo: Locator; readonly items: Locator; constructor(page: Page) { this.page = page; this.newTodo = page.getByPlaceholder('What needs to be done?'); this.items = page.getByTestId('todo-title'); } async goto() { await this.page.goto('./'); } async add(title: string) { await this.newTodo.fill(title); await this.newTodo.press('Enter'); } async complete(title: string) { await this.page .getByTestId('todo-item') .filter({ hasText: title }) .getByRole('checkbox') .check(); } async expectTodos(titles: string[]) { await expect(this.items).toHaveText(titles); } } Three choices worth copying:
- Locators are defined once, in the constructor. They are lazy: nothing is queried until an action runs, so there is no stale element problem.
- Prefer user-facing locators (
getByRole,getByPlaceholder,getByTestId) over CSS chains. They survive markup changes better. - Methods describe what a user does (
add,complete), not what the DOM does.
The tests
// tests/todo.spec.ts import { test, expect } from '@playwright/test'; import { TodoPage } from '../pages/todo-page'; test.describe('Todo list', () => { let todo: TodoPage; test.beforeEach(async ({ page }) => { todo = new TodoPage(page); await todo.goto(); }); test('adds two items', async () => { await todo.add('Write the test plan'); await todo.add('Review the locators'); await todo.expectTodos(['Write the test plan', 'Review the locators']); }); test('marks an item as completed', async ({ page }) => { await todo.add('Write the test plan'); await todo.complete('Write the test plan'); await expect(page.getByTestId('todo-item')).toHaveClass(/completed/); }); }); Run it with npx playwright test. Both tests pass on the demo app.
What belongs in a page object, and what does not
- In: locators, user actions, and simple read helpers.
- Out: the test's business decision. Keep the final
expectin the test when it states the rule being checked (as in the second test). Assertion helpers likeexpectTodosare fine for repeated checks, but do not hide every assertion in the page class, or a failing test will tell you less. - Avoid: one giant page object for the whole app. Split by page or by component (a header, a modal) and compose them.
Playwright also offers fixtures, which can create page objects for you and remove the beforeEach setup. A good next step once this pattern feels natural.
Where to go from here
Page objects are one module of a full automation path. If you want the whole sequence (locators, POM, API tests, CI) with practice and a mentor, see our online Playwright course.
How do you structure page objects on your team: one class per page, per component, or something else?



