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.