Page Objects

Page Object Model

Critical

• Locators are get accessors returning Locator. This is a style/readability convention — Playwright's Locator is lazy either way (it only queries the DOM when an action runs), so get vs readonly field behave identically at runtime. Use get for consistency with the rest of the scaffold.
• Constructor uses private readonly page: Page. No other visibility modifiers, no alternative DI patterns.
• Page objects import expect, Locator, Page from @playwright/test — never from fixtures/pom/test-options.ts (that's for spec files and fixtures).
• JSDoc rules:
  • Forbidden on locator getters and on any method that returns a Locator. Names are self-documenting.
  • Required (with @param and @returns) on every action method and every verification method.
  • Allowed on component fields (e.g. readonly nav: NavigationComponent) — these are not locators.
• Three locator sections when the page has forms or CRUD: interactive-element locators, feedback/validation-message locators, action methods. Feedback locators are not optional — see the selectors skill.
• Feedback/message strings come from enums/{area}/* (e.g. Messages.LOGIN_ERROR). Never hardcoded strings inside getByText(...).
• NEVER page.waitForTimeout(...) inside a page object. Use web-first assertions (await expect(locator).toBeVisible()) or page.waitForResponse(...).
• Exploration with playwright-cli is mandatory before writing any locators (see the selectors skill's Exploration-First Workflow). No guessing from wireframes, docs, or screenshots. If the app is unavailable, stop and say so — never ship placeholder locators.
• Register every new page object as a fixture in fixtures/pom/page-object-fixture.ts. Tests consume page objects through the fixture, never via new PageObject(page).

File Locations

{area} is a placeholder. Before creating or referencing any path below, run ls pages/ to discover the real subdirectory names in this repo (e.g., front-office, back-office) and use those instead.

Page Object Pattern

import { expect, Locator, Page } from '@playwright/test';
import { Messages } from '../../enums/app/app';

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

    // ==================== Locators ====================

    get emailInput(): Locator {
        return this.page.getByLabel('Email');
    }

    get submitButton(): Locator {
        return this.page.getByRole('button', { name: 'Submit' });
    }

    // ==================== Feedback Locators ====================

    get successMessage(): Locator {
        return this.page.getByText(Messages.LOGIN_SUCCESS);
    }

    get errorMessage(): Locator {
        return this.page.getByText(Messages.LOGIN_ERROR);
    }

    get requiredFieldError(): Locator {
        return this.page.getByText(Messages.REQUIRED_FIELD);
    }

    // ==================== Actions ====================

    /**
     * Submits the form and waits for the API response.
     * @param {string} email - The user's email address.
     * @returns {Promise<void>}
     */
    async submitForm(email: string): Promise<void> {
        await this.emailInput.fill(email);
        await this.submitButton.click();
        await this.page.waitForResponse((r) => r.url().includes('/api/submit'));
    }
}

Every page object that handles forms or CRUD operations must have three locator sections: interactive element locators, feedback/validation message locators, and action methods. Feedback locators are not optional — see the selectors skill for the full list of feedback types to capture.

Rules

Locators as getters

Use get accessor returning Locator. Both get and readonly field work identically at runtime (Playwright's Locator is lazy), but get is the scaffold convention — terser, locators stay grouped in the class body, constructor stays focused on dependencies.

// PREFERRED -- the scaffold's convention
get submitButton(): Locator {
    return this.page.getByRole('button', { name: 'Submit' });
}

Constructor pattern

constructor(private readonly page: Page) {}

No JSDoc on locators

JSDoc is forbidden on locator getters and on any method that returns a Locator. The name documents what it is:

// CORRECT -- no comment needed
get submitButton(): Locator {
    return this.page.getByRole('button', { name: 'Submit' });
}

// WRONG -- locators don't need JSDoc
/** The submit button. */
get submitButton(): Locator {
    return this.page.getByRole('button', { name: 'Submit' });
}

JSDoc is required on action methods and verification methods (see below).

Action methods and verification methods

• Action methods represent complete user actions (login(), submitForm(), addToCart()).
• Verification methods combine an action with a success assertion (loginAndVerify()). They may use expect(...) internally.
• Plain action methods should not assert — the test asserts. Use a verification method when the success check is re-used across tests.
• Always wait for API responses or state changes inside the method (page.waitForResponse, web-first assertions). Never page.waitForTimeout(...).
• Always specify an explicit return type (Promise<void> is the common case).
• JSDoc with @param and @returns is required; an @example block is encouraged for non-trivial methods.

Imports in page objects

Page objects import from @playwright/test (not from test-options.ts):

import { expect, Locator, Page } from '@playwright/test';

Component composition

Reusable UI fragments (headers, modals, sidebars) are defined as components and composed into page objects:

// pages/components/navigation.component.ts
import { Locator, Page } from '@playwright/test';

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

    get homeLink(): Locator {
        return this.page.getByRole('link', { name: 'Home' });
    }

    async clickHome(): Promise<void> {
        await this.homeLink.click();
    }

    async logout(): Promise<void> {
        await this.page.getByTestId('user-menu-button').click();
        await this.page.getByRole('button', { name: 'Logout' }).click();
    }
}

Compose components into page objects:

// pages/app/dashboard.page.ts
import { Page } from '@playwright/test';
import { NavigationComponent } from '../components/navigation.component';

export class DashboardPage {
    /** Navigation component for header/nav interactions */
    readonly nav: NavigationComponent;

    constructor(private readonly page: Page) {
        this.nav = new NavigationComponent(page);
    }
}

// Usage in tests
await dashboardPage.nav.clickHome();
await dashboardPage.nav.logout();

The nav: NavigationComponent field is a component, not a locator, so the JSDoc-forbidden rule does not apply — a short descriptive JSDoc is allowed.

Instructions

Phase 1: Verify prerequisites

Before writing any code:

• Run ls pages/ to resolve {area} (e.g. app, front-office, back-office). Do not guess.
• Identify which enums the page needs (Messages, ApiEndpoints, Roles, etc.). If a required enum member does not yet exist, extend it via the enums skill first — verify UI text with playwright-cli before encoding it.
• Confirm the scaffold has a matching schema (for pages that trigger API calls you need to wait for / assert on) via ls fixtures/api/schemas/; if missing, create it via the api-testing skill.