playwright-best-practices

name	playwright-best-practices
description	Use when: write or fix Playwright tests with resilient selectors, fixtures, parallelism, and CI.

Goal: end-to-end tests that are stable, isolated, and fast in CI.

Use for:

• flaky or slow Playwright suites
• authoring new browser tests that survive UI changes
• configuring CI runs with retries and reporting

Workflow:

1. Select by role, label, or test id; avoid CSS/text coupling.
2. Use web-first assertions that auto-wait; never sleep fixed time.
3. Isolate state per test with fixtures and fresh contexts.
4. Set up auth and data via API, not slow UI steps.
5. Run in parallel; keep tests independent and order-free.
6. Configure retries, traces, and screenshots on failure for CI.

Patterns:

• getByRole/getByTestId over brittle selectors
• expect(locator).toBeVisible() for auto-waiting
• fixtures for shared setup and teardown
• storageState to reuse authentication

Rules:

• no arbitrary waits; rely on auto-waiting assertions
• each test sets up and cleans its own data
• avoid shared mutable state across tests
• capture traces on failure to debug CI flakes