E2e Testing

Assertions — always use web-first (await expect)

await expect(page.getByRole('button', { name: 'Save' })).toBeVisible()
await expect(page.getByLabel('Email')).toHaveValue('[email protected]')
await expect(page.getByRole('checkbox')).toBeChecked()
await expect(page.getByRole('listitem')).toHaveCount(5)
await expect(page).toHaveURL('/dashboard')

Never use waitForTimeout() or waitForSelector() — await expect() auto-retries.

Test isolation rules

• Each test sets up its own state (login, data, etc.)
• No test depends on another test's side effects
• Use beforeEach for common setup within a suite
• Use afterEach for cleanup (prefer API calls over UI)
• Use fixtures for reusable setup (authenticated page, etc.)

Core rules

• ✅ Test user behavior (what they see and can do)
• ✅ Embrace auto-waiting — Playwright waits for actionability automatically
• ✅ Semantic locators guarantee accessibility compliance as a side effect
• ❌ No CSS/XPath selectors
• ❌ No waitForTimeout() / arbitrary sleeps
• ❌ No testing internal state (window.__state, component props, etc.)

Supporting files

• QUICKSTART.md — common test patterns ready to copy
• EXAMPLES.md — complete real-world test examples
• ANTI-PATTERNS.md — what not to do and why
• DEBUGGING-FAILING-TESTS.md — systematic workflow for fixing failing tests