Playwright E2E Testing
Write tests that mimic user behavior, not implementation details.
Core Principles
- Test user-visible behavior - Use role-based locators, assert visible outcomes
- Isolate every test - Fresh context, own data, no shared state
- Use web-first assertions -
expect(locator).toBeVisible()auto-waits - Never test third parties - Mock OAuth, external APIs, analytics
- Prefer API setup over UI - Seed data via API, test UI separately
Locator Priority (Use in Order)
| Priority | Method | Example |
|---|---|---|
| 1 | getByRole() |
getByRole('button', { name: 'Submit' }) |
| 2 | getByLabel() |
getByLabel('Email address') |
| 3 | getByText() |
getByText('Welcome back') |
| 4 | getByPlaceholder() |
getByPlaceholder('Search...') |
| 5 | getByTestId() |
getByTestId('submit-btn') |
| 6 | CSS/XPath | AVOID - fragile, breaks with styling |
Critical Anti-Patterns
- Never
waitForTimeout()- Use web-first assertions instead - Never CSS class selectors -
.MuiButton-rootbreaks on updates - Never XPath - Hard to read, brittle
- Never test dependencies - Tests affect each other
- Never skip isolation - Parallel execution will fail
Quick Patterns
// ✅ Good: Role-based, auto-waiting
await expect(page.getByRole('button', { name: 'Save' })).toBeEnabled();
await page.getByRole('button', { name: 'Save' }).click();
// ❌ Bad: CSS selector, manual wait
await page.waitForTimeout(2000);
await page.locator('.save-btn').click();
References
For detailed patterns, see:
references/locators.md- Chaining, filtering, nth-childreferences/page-objects.md- POM + fixtures patternreferences/auth.md- storageState, multi-rolereferences/network.md- Mocking, HAR recordingreferences/ci-cd.md- GitHub Actions, shardingreferences/headless-ui.md- Dialog, Menu, Listbox testingreferences/anti-patterns.md- Full anti-pattern catalog