1# Organizing Reusable Test Code
2 
3## Table of Contents
4 
51. [Pattern Comparison](#pattern-comparison)
62. [Selection Flowchart](#selection-flowchart)
73. [Page Objects](#page-objects)
84. [Custom Fixtures](#custom-fixtures)
95. [Helper Functions](#helper-functions)
106. [Combined Project Structure](#combined-project-structure)
117. [Anti-Patterns](#anti-patterns)
12 
13Use all three patterns together. Most projects benefit from a hybrid approach:
14 
15- **Page objects** for UI interaction (pages/components with 5+ interactions)
16- **Custom fixtures** for test infrastructure (auth state, database, API clients, anything with lifecycle)
17- **Helper functions** for stateless utilities (generate data, format values, simple waits)
18 
19If only using one pattern, choose **custom fixtures** — they handle setup/teardown, compose well, and Playwright is built around them.
20 
21## Pattern Comparison
22 
23| Aspect | Page Objects | Custom Fixtures | Helper Functions |
24|---|---|---|---|
25| **Purpose** | Encapsulate UI interactions | Provide resources with setup/teardown | Stateless utilities |
26| **Lifecycle** | Manual (constructor/methods) | Built-in (`use()` with automatic teardown) | None |
27| **Composability** | Constructor injection or fixture wiring | Depend on other fixtures | Call other functions |
28| **Best for** | Pages with many reused interactions | Resources needing setup AND teardown | Simple logic with no side effects |
29 
30## Selection Flowchart
31 
32```text
33What kind of reusable code?
34|
35+-- Interacts with browser page/component?
36|   |
37|   +-- Has 5+ interactions (fill, click, navigate, assert)?
38|   |   +-- YES: Used in 3+ test files?
39|   |   |   +-- YES --> PAGE OBJECT
40|   |   |   +-- NO --> Inline or small helper
41|   |   +-- NO --> HELPER FUNCTION
42|   |
43|   +-- Needs setup before AND cleanup after test?
44|       +-- YES --> CUSTOM FIXTURE
45|       +-- NO --> PAGE OBJECT method or HELPER
46|
47+-- Manages resource with lifecycle (create/destroy)?
48|   +-- Examples: auth state, DB connection, API client, test user
49|   +-- YES --> CUSTOM FIXTURE (always)
50|
51+-- Stateless utility? (no browser, no side effects)
52|   +-- Examples: random email, format date, build URL, parse response
53|   +-- YES --> HELPER FUNCTION
54|
55+-- Not sure?
56    +-- Start with HELPER FUNCTION
57    +-- Promote to PAGE OBJECT when interactions grow
58    +-- Promote to FIXTURE when lifecycle needed
59```
60 
61## Page Objects
62 
63Best for pages/components with 5+ interactions appearing in 3+ test files.
64 
65```typescript
66// page-objects/booking.page.ts
67import { type Page, type Locator, expect } from '@playwright/test';
68 
69export class BookingPage {
70  readonly page: Page;
71  readonly dateField: Locator;
72  readonly guestCount: Locator;
73  readonly roomType: Locator;
74  readonly reserveBtn: Locator;
75  readonly totalPrice: Locator;
76 
77  constructor(page: Page) {
78    this.page = page;
79    this.dateField = page.getByLabel('Check-in date');
80    this.guestCount = page.getByLabel('Guests');
81    this.roomType = page.getByLabel('Room type');
82    this.reserveBtn = page.getByRole('button', { name: 'Reserve' });
83    this.totalPrice = page.getByTestId('total-price');
84  }
85 
86  async goto() {
87    await this.page.goto('/booking');
88  }
89 
90  async fillDetails(opts: { date: string; guests: number; room: string }) {
91    await this.dateField.fill(opts.date);
92    await this.guestCount.fill(String(opts.guests));
93    await this.roomType.selectOption(opts.room);
94  }
95 
96  async reserve() {
97    await this.reserveBtn.click();
98    await this.page.waitForURL('**/confirmation');
99  }
100 
101  async expectPrice(amount: string) {
102    await expect(this.totalPrice).toHaveText(amount);
103  }
104}
105```
106 
107```typescript
108// tests/booking/reservation.spec.ts
109import { test, expect } from '@playwright/test';
110import { BookingPage } from '../page-objects/booking.page';
111 
112test('complete reservation with standard room', async ({ page }) => {
113  const booking = new BookingPage(page);
114  await booking.goto();
115  await booking.fillDetails({ date: '2026-03-15', guests: 2, room: 'standard' });
116  await booking.reserve();
117  await expect(page.getByText('Reservation confirmed')).toBeVisible();
118});
119```
120 
121**Page object principles:**
122- One class per logical page/component, not per URL
123- Constructor takes `Page`
124- Locators as `readonly` properties in constructor
125- Methods represent user intent (`reserve`, `fillDetails`), not low-level clicks
126- Navigation methods (`goto`) belong on the page object
127 
128## Custom Fixtures
129 
130Best for resources needing setup before and teardown after tests — auth state, database connections, API clients, test users.
131 
132```typescript
133// fixtures/base.fixture.ts
134import { test as base, expect } from '@playwright/test';
135import { BookingPage } from '../page-objects/booking.page';
136import { generateMember } from '../helpers/data';
137 
138type Fixtures = {
139  bookingPage: BookingPage;
140  member: { email: string; password: string; id: string };
141  loggedInPage: import('@playwright/test').Page;
142};
143 
144export const test = base.extend<Fixtures>({
145  bookingPage: async ({ page }, use) => {
146    await use(new BookingPage(page));
147  },
148 
149  member: async ({ request }, use) => {
150    const data = generateMember();
151    const res = await request.post('/api/test/members', { data });
152    const member = await res.json();
153    await use(member);
154    await request.delete(`/api/test/members/${member.id}`);
155  },
156 
157  loggedInPage: async ({ page, member }, use) => {
158    await page.goto('/login');
159    await page.getByLabel('Email').fill(member.email);
160    await page.getByLabel('Password').fill(member.password);
161    await page.getByRole('button', { name: 'Sign in' }).click();
162    await expect(page).toHaveURL('/dashboard');
163    await use(page);
164  },
165});
166 
167export { expect } from '@playwright/test';
168```
169 
170```typescript
171// tests/dashboard/overview.spec.ts
172import { test, expect } from '../../fixtures/base.fixture';
173 
174test('member sees dashboard widgets', async ({ loggedInPage }) => {
175  await expect(loggedInPage.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
176  await expect(loggedInPage.getByTestId('stats-widget')).toBeVisible();
177});
178 
179test('new member sees welcome prompt', async ({ loggedInPage, member }) => {
180  await expect(loggedInPage.getByText(`Welcome, ${member.email}`)).toBeVisible();
181});
182```
183 
184**Fixture principles:**
185- Use `test.extend()` — never module-level variables
186- `use()` callback separates setup from teardown
187- Teardown runs even if test fails
188- Fixtures compose: one can depend on another
189- Fixtures are lazy: created only when requested
190- Wrap page objects in fixtures for lifecycle management
191 
192## Helper Functions
193 
194Best for stateless utilities — generating test data, formatting values, building URLs, parsing responses.
195 
196```typescript
197// helpers/data.ts
198import { randomUUID } from 'node:crypto';
199 
200export function generateEmail(prefix = 'user'): string {
201  return `${prefix}-${Date.now()}-${randomUUID().slice(0, 8)}@test.local`;
202}
203 
204export function generateMember(overrides: Partial<Member> = {}): Member {
205  return {
206    email: generateEmail(),
207    password: 'SecurePass456!',
208    name: 'Test Member',
209    ...overrides,
210  };
211}
212 
213interface Member {
214  email: string;
215  password: string;
216  name: string;
217}
218 
219export function formatPrice(cents: number): string {
220  return `$${(cents / 100).toFixed(2)}`;
221}
222```
223 
224```typescript
225// helpers/assertions.ts
226import { type Page, expect } from '@playwright/test';
227 
228export async function expectNotification(page: Page, message: string): Promise<void> {
229  const notification = page.getByRole('alert').filter({ hasText: message });
230  await expect(notification).toBeVisible();
231  await expect(notification).toBeHidden({ timeout: 10000 });
232}
233```
234 
235```typescript
236// tests/settings/account.spec.ts
237import { test, expect } from '@playwright/test';
238import { generateEmail } from '../../helpers/data';
239import { expectNotification } from '../../helpers/assertions';
240 
241test('update account email', async ({ page }) => {
242  const newEmail = generateEmail('updated');
243  await page.goto('/settings/account');
244  await page.getByLabel('Email').fill(newEmail);
245  await page.getByRole('button', { name: 'Save' }).click();
246  await expectNotification(page, 'Account updated');
247  await expect(page.getByLabel('Email')).toHaveValue(newEmail);
248});
249```
250 
251**Helper principles:**
252- Pure functions with no side effects
253- No browser state — take `page` as parameter if needed
254- Promote to fixture if setup/teardown needed
255- Promote to page object if many page interactions grow
256- Keep small and focused
257 
258## Combined Project Structure
259 
260```text
261tests/
262+-- fixtures/
263|   +-- auth.fixture.ts
264|   +-- db.fixture.ts
265|   +-- base.fixture.ts
266+-- page-objects/
267|   +-- login.page.ts
268|   +-- booking.page.ts
269|   +-- components/
270|       +-- data-table.component.ts
271+-- helpers/
272|   +-- data.ts
273|   +-- assertions.ts
274+-- e2e/
275|   +-- auth/
276|   |   +-- login.spec.ts
277|   +-- booking/
278|       +-- reservation.spec.ts
279playwright.config.ts
280```
281 
282**Layer responsibilities:**
283 
284| Layer | Pattern | Responsibility |
285|---|---|---|
286| **Test file** | `test()` | Describes behavior, orchestrates layers |
287| **Fixtures** | `test.extend()` | Resource lifecycle — setup, provide, teardown |
288| **Page objects** | Classes | UI interaction — navigation, actions, locators |
289| **Helpers** | Functions | Utilities — data generation, formatting, assertions |
290 
291## Anti-Patterns
292 
293### Page object managing resources
294 
295```typescript
296// BAD: page object handling API calls and database
297class LoginPage {
298  async createUser() { /* API call */ }
299  async deleteUser() { /* API call */ }
300  async signIn(email: string, password: string) { /* UI */ }
301}
302```
303 
304Resource lifecycle belongs in fixtures where teardown is guaranteed. Keep only `signIn` in the page object.
305 
306### Locator-only page objects
307 
308```typescript
309// BAD: no methods, just locators
310class LoginPage {
311  emailInput = this.page.getByLabel('Email');
312  passwordInput = this.page.getByLabel('Password');
313  submitBtn = this.page.getByRole('button', { name: 'Sign in' });
314  constructor(private page: Page) {}
315}
316```
317 
318Add intent-revealing methods or skip the page object entirely.
319 
320### Monolithic fixtures
321 
322```typescript
323// BAD: one fixture doing everything
324test.extend({
325  everything: async ({ page, request }, use) => {
326    const user = await createUser(request);
327    const products = await seedProducts(request, 50);
328    await setupPayment(request, user.id);
329    await page.goto('/dashboard');
330    await use({ user, products, page });
331    // massive teardown...
332  },
333});
334```
335 
336Break into small, composable fixtures. Each fixture does one thing.
337 
338### Helpers with side effects
339 
340```typescript
341// BAD: module-level state
342let createdUserId: string;
343 
344export async function createTestUser(request: APIRequestContext) {
345  const res = await request.post('/api/users', { data: { email: '[email protected]' } });
346  const user = await res.json();
347  createdUserId = user.id; // shared across tests!
348  return user;
349}
350```
351 
352Module-level state leaks between parallel tests. If it has side effects and needs cleanup, make it a fixture.
353 
354### Over-abstracting simple operations
355 
356```typescript
357// BAD: helper for one-liner
358export async function clickButton(page: Page, name: string) {
359  await page.getByRole('button', { name }).click();
360}
361```
362 
363Only abstract when there is real duplication (3+ usages) or complexity (5+ interactions).
364