Page objects, helpers & fixtures

When you read a generated test file you will see references to things like tp.clickAddNewMember(), grid.selectCellDropdownOption(…), and tp.wait.expectToastAfterAction(…). These come from three layers of supporting code that sit between the raw Playwright browser API and the test steps: page objects, helpers, and fixtures.

You do not need to write or edit any of these files. They are maintained by the AI agents and the developers. This page explains what each layer does so you can read generated tests and specs with confidence.

Page objects — one class per screen

Where they live: tests/page-objects/

A page object is a TypeScript class that models a single screen or panel in the PACE application. It wraps all the low-level browser interactions for that screen — clicking buttons, reading grid rows, opening dropdowns — behind named methods with clear, readable names.

Think of a page object as a vocabulary for a screen. Instead of page.locator('#btn-add').click(), the test says tp.clickAddNewMember(). The intent is immediately clear, and if the button's selector changes in a future release, only the page object needs updating — not every test that uses it.

The base page object (BasePage.ts) contains logic shared by all screens (navigation, waiting for loaders). Feature-specific page objects in tests/page-objects/features/ extend that base.

Helpers — reusable actions across screens

Where they live: tests/utils/

Helpers are utilities that work across multiple screens rather than being tied to one. PACE E2E has four main helpers:

Helper	What it does
FormHelper	Fills in input fields, selects dropdown options, and handles date pickers.
WaitHelper	Waits for loaders to disappear, for toasts to appear, for network requests to settle.
TabHelper	Manages browser tabs — opening new ones, switching between them, closing them.
AgGridHelper	Interacts with AG-Grid data tables: reads row counts, selects cell dropdowns, sorts columns.

Most test steps that involve a data grid call AgGridHelper. Steps that submit forms call FormHelper. Steps that assert a success message call WaitHelper. The page objects compose these helpers rather than duplicating their logic.

Fixtures — the launchpad for every test

Where they live: tests/fixtures/

A fixture is Playwright's mechanism for setting up the browser before a test runs and tearing it down afterward. In PACE E2E, fixtures do three things:

1. Log in. The auth.fixture.ts base fixture navigates to the PACE login page and signs in with the credentials from .env. Every test automatically starts authenticated.
2. Navigate to the right page. Feature-specific fixtures (referenced by the fixture: field in a spec's frontmatter) extend the auth fixture to navigate to the correct PACE screen before the first step runs. A test that uses projectTeamPage fixture, for example, starts on the project Team tab — no navigation code needed in the test itself.
3. Inject data and helpers. The data.fixture.ts fixture resolves the data references from the spec's data: frontmatter key and makes them available to the test as a typed data object. It also wires in the page-object instance and the helpers, so every test step can use them immediately.

The layered picture

Test step (spec)
    │
    ▼
Page object method  ←  calls  →  Helpers (Form / Wait / Tab / AgGrid)
    │
    ▼
Playwright browser API

Each layer has a single responsibility:

• Spec — what to do and why (English).
• Page object — how to do it for this screen (named methods).
• Helpers — shared low-level patterns across all screens.
• Fixture — the known-good starting state before step 1 runs.

What this means for testers

You work at the spec level. The agents and developers own everything below that line. If a generated test fails because a selector changed, the developer fixes the page object — your spec stays untouched. If you want the test to exercise a different scenario, you update the spec — the Generator rewrites the TypeScript.