1# Page Object Model (POM)
2 
3## Table of Contents
4 
51. [Overview](#overview)
62. [Basic Structure](#basic-structure)
73. [Component Objects](#component-objects)
84. [Composition Patterns](#composition-patterns)
95. [Factory Functions](#factory-functions)
106. [Best Practices](#best-practices)
11 
12## Overview
13 
14Page Object Model encapsulates page structure and interactions, providing:
15 
16- **Maintainability**: Change selectors in one place
17- **Reusability**: Share page interactions across tests
18- **Readability**: Tests express intent, not implementation
19 
20## Basic Structure
21 
22### Page Class
23 
24```typescript
25// pages/login.page.ts
26import { Page, Locator, expect } from "@playwright/test";
27 
28export class LoginPage {
29  readonly page: Page;
30  readonly emailInput: Locator;
31  readonly passwordInput: Locator;
32  readonly submitButton: Locator;
33  readonly errorMessage: Locator;
34 
35  constructor(page: Page) {
36    this.page = page;
37    this.emailInput = page.getByLabel("Email");
38    this.passwordInput = page.getByLabel("Password");
39    this.submitButton = page.getByRole("button", { name: "Sign in" });
40    this.errorMessage = page.getByRole("alert");
41  }
42 
43  async goto() {
44    await this.page.goto("/login");
45  }
46 
47  async login(email: string, password: string) {
48    await this.emailInput.fill(email);
49    await this.passwordInput.fill(password);
50    await this.submitButton.click();
51  }
52 
53  async expectError(message: string) {
54    await expect(this.errorMessage).toContainText(message);
55  }
56}
57```
58 
59### Usage in Tests
60 
61```typescript
62// tests/login.spec.ts
63import { test, expect } from "@playwright/test";
64import { LoginPage } from "../pages/login.page";
65 
66test.describe("Login", () => {
67  test("successful login redirects to dashboard", async ({ page }) => {
68    const loginPage = new LoginPage(page);
69    await loginPage.goto();
70    await loginPage.login("[email protected]", "password123");
71    await expect(page).toHaveURL("/dashboard");
72  });
73 
74  test("shows error for invalid credentials", async ({ page }) => {
75    const loginPage = new LoginPage(page);
76    await loginPage.goto();
77    await loginPage.login("[email protected]", "wrong");
78    await loginPage.expectError("Invalid credentials");
79  });
80});
81```
82 
83## Component Objects
84 
85For reusable UI components:
86 
87```typescript
88// components/navbar.component.ts
89import { Page, Locator } from "@playwright/test";
90 
91export class NavbarComponent {
92  readonly container: Locator;
93  readonly logo: Locator;
94  readonly searchInput: Locator;
95  readonly userMenu: Locator;
96 
97  constructor(page: Page) {
98    this.container = page.getByRole("navigation");
99    this.logo = this.container.getByRole("link", { name: "Home" });
100    this.searchInput = this.container.getByRole("searchbox");
101    this.userMenu = this.container.getByRole("button", { name: /user menu/i });
102  }
103 
104  async search(query: string) {
105    await this.searchInput.fill(query);
106    await this.searchInput.press("Enter");
107  }
108 
109  async openUserMenu() {
110    await this.userMenu.click();
111  }
112}
113```
114 
115```typescript
116// components/modal.component.ts
117import { Locator, expect } from "@playwright/test";
118 
119export class ModalComponent {
120  readonly container: Locator;
121  readonly title: Locator;
122  readonly closeButton: Locator;
123  readonly confirmButton: Locator;
124 
125  constructor(container: Locator) {
126    this.container = container;
127    this.title = container.getByRole("heading");
128    this.closeButton = container.getByRole("button", { name: "Close" });
129    this.confirmButton = container.getByRole("button", { name: "Confirm" });
130  }
131 
132  async expectTitle(title: string) {
133    await expect(this.title).toHaveText(title);
134  }
135 
136  async close() {
137    await this.closeButton.click();
138  }
139 
140  async confirm() {
141    await this.confirmButton.click();
142  }
143}
144```
145 
146## Composition Patterns
147 
148### Page with Components
149 
150```typescript
151// pages/dashboard.page.ts
152import { Page, Locator } from "@playwright/test";
153import { NavbarComponent } from "../components/navbar.component";
154import { ModalComponent } from "../components/modal.component";
155 
156export class DashboardPage {
157  readonly page: Page;
158  readonly navbar: NavbarComponent;
159  readonly newProjectButton: Locator;
160 
161  constructor(page: Page) {
162    this.page = page;
163    this.navbar = new NavbarComponent(page);
164    this.newProjectButton = page.getByRole("button", { name: "New Project" });
165  }
166 
167  async goto() {
168    await this.page.goto("/dashboard");
169  }
170 
171  async createProject() {
172    await this.newProjectButton.click();
173    return new ModalComponent(this.page.getByRole("dialog"));
174  }
175}
176```
177 
178### Page Navigation
179 
180```typescript
181// pages/base.page.ts
182import { Page } from "@playwright/test";
183 
184export abstract class BasePage {
185  constructor(readonly page: Page) {}
186 
187  abstract goto(): Promise<void>;
188 
189  async getTitle(): Promise<string> {
190    return this.page.title();
191  }
192}
193```
194 
195```typescript
196// Return new page object on navigation
197export class LoginPage extends BasePage {
198  async login(email: string, password: string): Promise<DashboardPage> {
199    await this.emailInput.fill(email);
200    await this.passwordInput.fill(password);
201    await this.submitButton.click();
202    return new DashboardPage(this.page);
203  }
204}
205 
206// Usage
207const loginPage = new LoginPage(page);
208await loginPage.goto();
209const dashboardPage = await loginPage.login("[email protected]", "pass");
210await dashboardPage.expectWelcomeMessage();
211```
212 
213## Factory Functions
214 
215Alternative to classes for simpler pages:
216 
217```typescript
218// pages/login.page.ts
219import { Page } from "@playwright/test";
220 
221export function createLoginPage(page: Page) {
222  const emailInput = page.getByLabel("Email");
223  const passwordInput = page.getByLabel("Password");
224  const submitButton = page.getByRole("button", { name: "Sign in" });
225 
226  return {
227    goto: () => page.goto("/login"),
228    login: async (email: string, password: string) => {
229      await emailInput.fill(email);
230      await passwordInput.fill(password);
231      await submitButton.click();
232    },
233    emailInput,
234    passwordInput,
235    submitButton,
236  };
237}
238 
239// Usage
240const loginPage = createLoginPage(page);
241await loginPage.goto();
242await loginPage.login("[email protected]", "password");
243```
244 
245## Best Practices
246 
247### Do
248 
249- **Keep locators in page objects** - Single source of truth
250- **Return new page objects** when navigation occurs
251- **Expose elements** for custom assertions in tests
252- **Use descriptive method names** - `submitOrder()` not `clickButton()`
253- **Keep methods focused** - One action per method
254 
255### Don't
256 
257- **Don't include assertions in page methods** (usually) - Keep in tests
258- **Don't expose implementation details** - Hide complex interactions
259- **Don't make page objects too large** - Split into components
260- **Don't share state** between page object instances
261 
262### Directory Structure
263 
264```
265tests/
266├── pages/
267│   ├── base.page.ts
268│   ├── login.page.ts
269│   ├── dashboard.page.ts
270│   └── settings.page.ts
271├── components/
272│   ├── navbar.component.ts
273│   ├── modal.component.ts
274│   └── table.component.ts
275├── fixtures/
276│   └── pages.fixture.ts
277└── specs/
278    ├── login.spec.ts
279    └── dashboard.spec.ts
280```
281 
282### Using with Fixtures
283 
284```typescript
285// fixtures/pages.fixture.ts
286import { test as base } from "@playwright/test";
287import { LoginPage } from "../pages/login.page";
288import { DashboardPage } from "../pages/dashboard.page";
289 
290type Pages = {
291  loginPage: LoginPage;
292  dashboardPage: DashboardPage;
293};
294 
295export const test = base.extend<Pages>({
296  loginPage: async ({ page }, use) => {
297    await use(new LoginPage(page));
298  },
299  dashboardPage: async ({ page }, use) => {
300    await use(new DashboardPage(page));
301  },
302});
303 
304// Usage in tests
305test("can login", async ({ loginPage }) => {
306  await loginPage.goto();
307  await loginPage.login("[email protected]", "password");
308});
309```
310 
311## Related References
312 
313- **Locator strategies**: See [locators.md](locators.md) for selecting elements
314- **Fixtures**: See [fixtures-hooks.md](fixtures-hooks.md) for advanced fixture patterns
315- **Test organization**: See [test-suite-structure.md](test-suite-structure.md) for structuring test suites
316