E2E Testing (Playwright)
Guidelines for writing stable, fast end-to-end tests with Playwright. Contains 9 rules across 5 categories, prioritized by impact on flakiness and maintainability.
When to Apply
Reference these guidelines when:
- Writing a new Playwright test for a user flow
- Choosing locators for elements on a page
- Diagnosing a flaky or intermittently failing E2E test
- Structuring a growing suite with Page Objects
- Setting up or tuning Playwright in CI (sharding, retries, tracing)
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Locator Strategy | CRITICAL | locators- |
| 2 | Waiting & Assertions | CRITICAL | waiting- |
| 3 | Test Isolation & Data | HIGH | isolation- |
| 4 | Page Object Model & Structure | MEDIUM | pom- |
| 5 | CI & Reliability | MEDIUM | ci- |
Quick Reference
1. Locator Strategy (CRITICAL)
locators-role-based- Prefer getByRole/getByLabel/getByTextlocators-avoid-css-xpath- Avoid structural CSS/XPath selectors
2. Waiting & Assertions (CRITICAL)
waiting-no-fixed-timeouts- Never use waitForTimeout in committed testswaiting-web-first-assertions- Use expect(locator).toHave*() over manual reads
3. Test Isolation & Data (HIGH)
isolation-independent-tests- Every test independently runnableisolation-seed-via-api- Seed data via API, not UI
4. Page Object Model & Structure (MEDIUM)
pom-page-object-model- Encapsulate locators/actions per page
5. CI & Reliability (MEDIUM)
ci-parallel-sharding- Shard suites across CI machinesci-trace-on-retry- Capture traces only on retry
How to Use This Skill
- Read
rules/_sections.mdfor full category descriptions. - When writing a new test, start from
locators-role-basedandwaiting-web-first-assertions— most flakiness starts here. - When triaging a flaky test, check
waiting-no-fixed-timeoutsandisolation-independent-testsfirst. - As a suite grows past a handful of tests, apply
pom-page-object-modelto keep locator changes centralized.
See rules/_template.md for the format used by every rule file.