# Playwright Best Practices

> Use when: write or fix Playwright tests with resilient selectors, fixtures, parallelism, and CI.

- Skill: `kimtth/playwright-best-practices` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kimtth/playwright-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kimtth/playwright-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kimtth (https://skillmd.com/u/kimtth)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kimtth/playwright-best-practices

---


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