---
description: Playwright e2e testing best practices (official)
globs: ["**/*.spec.ts", "**/*.test.ts", "**/e2e/**", "**/tests/**"]
alwaysApply: true
---

- Test user-visible behaviour, not implementation details (function names, CSS classes, DOM shape).
- Prefer user-facing locators: `getByRole`, `getByText`, `getByLabel`, `getByPlaceholder`, `getByAltText`, `getByTitle`; `getByTestId` only when none fit.
- No CSS/XPath selectors — they break when the DOM changes.
- Narrow with chaining + `filter({ hasText })` / `filter({ has })`, not `.first()` / `.nth()`.
- Use web-first auto-retrying assertions: `await expect(locator).toBeVisible()` — not `expect(await locator.isVisible()).toBe(true)`.
- `await` goes before `expect`, never inside it. Don't leave floating promises.
- No manual waits (`page.waitForTimeout`); locators and assertions auto-wait.
- Keep tests isolated (own storage/cookies/data); share setup via `beforeEach`/`afterEach`; reuse auth via setup project + `storageState`.
- Mock third-party responses with `page.route()`; don't test sites you don't own.
- Run across Chromium/Firefox/WebKit; on CI capture traces `on-first-retry`.