---
name: playwright-testing
description: "Playwright E2E tests: page objects, cross-browser projects, traces and CI setup. Use when writing or debugging Playwright specs, or configuring Playwright in CI."
---

# Playwright Testing

Project test config and breakpoints: `.opencastle/stack/testing-config.md`. Docs: https://playwright.dev/docs/intro

Layout: specs `tests/e2e/{feature}/`, page objects `tests/pages/`, fixtures `tests/fixtures/`.

## Locator priority

`getByRole(role, { name })` → `getByLabel()` for inputs → `getByTestId()` for containers → `getByText()` → `page.locator(css)` **only** when no semantic alternative exists.

## Gotchas

- Page objects must hold no module-level/global state. Parallel workers share the process, so a singleton leaks state between tests and produces order-dependent failures.
- `trace: 'on-first-retry'` costs nothing on green runs — enable it for flaky suites and attach the trace ID to failure tickets.
- Visual diffs: snapshot only stable regions and `mask` dynamic content, otherwise every run diffs.
- `forbidOnly: !!process.env.CI` prevents a stray `test.only` from silently shrinking the CI suite to one test.
- `webServer.reuseExistingServer: !process.env.CI` — locally reuses your dev server; in CI it must start its own.
- `retries: 2` and `workers: 1` in CI trade wall-clock for determinism.
- Mock at the network layer: `await page.route('/api/login', route => route.fulfill({ status: 200, body: ... }))`.

## Commands

```bash
npx playwright test --ui                      # interactive iteration
npx playwright test auth.spec.ts              # single spec
npx playwright test --project=chromium        # one browser
npx playwright test --grep "login"            # filter by title
npx playwright test --debug                   # step through
npx playwright codegen http://localhost:3000  # record a spec
npx playwright show-report                    # HTML report (verify 0 failures)
npx playwright install                        # browsers — required on a fresh machine/CI
```

`projects` in `playwright.config.ts` map to `devices[...]` presets (`Desktop Chrome`, `Desktop Firefox`, `Desktop Safari`, `iPhone 14`).