# AGENTS.md — Playwright

Official Playwright e2e best practices (https://playwright.dev/docs/best-practices). Use `@playwright/test`.

- Test user-visible behaviour, not implementation details (function names, CSS classes, DOM structure).
- Prefer user-facing locators: `getByRole`, `getByText`, `getByLabel`, `getByPlaceholder`, `getByAltText`, `getByTitle`. Use `getByTestId` only when none fit.
- Don't use CSS or XPath selectors — they break when the DOM changes.
- Narrow with chaining + `filter({ hasText })` / `filter({ has })` instead of `.first()` / `.nth()`.
- Use web-first auto-retrying assertions: `await expect(locator).toBeVisible()` — never `expect(await locator.isVisible()).toBe(true)`.
- Put `await` before `expect`, not inside it.
- Use `expect.soft()` to collect multiple failures in one run.
- Don't use manual waits (`waitForTimeout`); let locators and assertions auto-wait.
- Keep tests isolated: own storage/cookies/data per test; share setup via `beforeEach`/`afterEach`.
- Reuse auth via a setup project + `storageState`, not per-test login.
- Mock third-party responses with `page.route()`; don't test sites you don't own.
- Run across Chromium, Firefox, WebKit via `projects` in `playwright.config.ts`.
- On CI install only needed browsers: `npx playwright install chromium --with-deps`; capture traces `on-first-retry`.
- Lint with TS + ESLint `@typescript-eslint/no-floating-promises`; run `tsc --noEmit`.
- Generate locators with `npx playwright codegen <url>`; keep Playwright updated with `@playwright/test@latest`.