Runbook 08 — Page Objects at scale (pages/components/flows)

Scope

• Standardize Page Object Model layout: pages/, components/, flows/, assertions/.
• Standardize locator policy (role/label/testid first).
• Define required methods and naming for page objects.
• Define a repeatable procedure for adding new pages and flows.
• Define PR review checks to prevent drift.

Exit criteria

• ✔ Directory structure exists and is used consistently.
• ✔ Tests contain minimal inline locators.
• ✔ Repeated multi-step sequences moved to flows/.
• ✔ Repeated expectations moved to assertions/.
• ✔ New page procedure produces one new page + one recipe spec that passes.

Structure

pages/
  HomePage.*
  LoginPage.*
  SettingsPage.*
  EditorPage.*
  ArticlePage.*
  ProfilePage.*

components/
  Navbar.*
  ArticlePreview.*
  TagList.*

flows/
  AuthFlow.*
  PublishArticleFlow.*
  FollowUserFlow.*

assertions/
  expectLoggedIn.*
  expectArticleVisible.*
  expectToast.*

helpers/
  env.*
  urls.*
  dataFactories.*

Locator policy

POM contract

• Each page object must expose open() and assertAt() (or isAt() + explicit expect).
• Locators are properties grouped by intent (no inline locators in specs).
• Actions do actions. Assertions live in assertions/ (avoid mixed responsibilities).
• Pages do not generate test data. Specs/fixtures provide data inputs.
• Pages do not read environment variables directly (use helpers/fixtures).

Flows

• Flows own multi-step tasks that cross pages (publish, follow, update settings).
• Flows accept page objects as inputs (no raw page usage in specs).
• Flows return identifiers when relevant (slug, username) for downstream assertions.

New page procedure

1. Create pages/NewFeaturePage.* with open() and assertAt().
2. Add locators using locator policy (role/label/testid first).
3. If UI chunk repeats, create a components/ object and reference it from the page.
4. If the task crosses pages, create/extend a flows/ helper.
5. Add/extend assertion helpers in assertions/ for repeated checks.
6. Add one recipe spec proving page + component + flow integration.

PR review checks

• ✔ No new inline locators added to specs.
• ✔ New locators follow policy (role/label/testid before CSS).
• ✔ Multi-step sequence implemented in flows/ (not duplicated across specs).
• ✔ Repeated expects moved to assertions/.
• ✔ Page objects implement open() + assertAt().

# detect hardcoded URLs and raw selectors in specs
grep -R "http://" -n specs pages components flows assertions || true
grep -R "https://" -n specs pages components flows assertions || true

# discourage inline locator patterns in specs
grep -R "getByRole\\(|getByLabel\\(|getByTestId\\(|locator\\(" -n specs || true

Commands

Set env contract:

export WEB_BASE_URL="http://sut.testlab:3000"
export API_BASE_URL="http://sut.testlab:3001/api"

Run Sprint 8 recipe spec:

npx playwright test specs/sprint8 \
  --project=auth-chromium --workers=1 --reporter=line

Expected outputs

• ✔ Recipe spec passes and reads as workflow-level steps.
• ✔ Specs contain minimal locator usage (mechanics in pages/components).
• ✔ Failures (when induced) produce sufficient artifacts when enabled (trace/screenshot/video + HTML report).

Failure modes

• God page object: one page grows without bound → split into components + flows.
• Selector churn: DOM-dependent selectors → replace with role/label/testid.
• Assertion drift: same concept asserted multiple ways → centralize in assertions/.
• Spec bloat: repeated multi-step setup → move into flows/ and reuse.
• Wait-based stabilization: added sleeps/timeouts → replace with state assertions and trace-first debugging.