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.