playwright-tests

Quick Reference

The Golden Rules

1. Use role-based locators - Never CSS classes unless absolutely necessary
2. Assert absence broadly, presence specifically - Wide net for "not there", scoped for "is there"
3. Never use timeouts or networkidle - Wait for visible effects only
4. Improve accessibility while testing - Tests drive better markup
5. Wait for user-visible changes - Not implementation details like network requests
6. Set up portable contracts through the UI - Never inject application state through cookies, storage, databases, or framework internals

Anti-Patterns to Avoid

❌ page.waitForTimeout(1000) - Arbitrary waits (flaky) ❌ page.waitForLoadState('networkidle') - Unreliable ❌ page.waitForResponse(...) - Implementation detail ❌ page.locator('.css-class') - Fragile selectors ❌ Adding test IDs when accessibility markup would work ❌ Hardcoding dynamic store data names (e.g., collection titles from sortKey: UPDATED_AT queries)