agentic-playwright page-objects.instructions.md

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.