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-root breaks 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
1---2name: playwright-e2e3description: This skill should be used when the user asks to "write playwright test", "e2e test", "playwright locator", "test isolation", "page object", or needs guidance on Playwright E2E testing patterns, locator strategies, test structure, or debugging flaky tests.4---56# Playwright E2E Testing78Write tests that mimic user behavior, not implementation details.910## Core Principles11121. **Test user-visible behavior** - Use role-based locators, assert visible outcomes132. **Isolate every test** - Fresh context, own data, no shared state143. **Use web-first assertions** - `expect(locator).toBeVisible()` auto-waits154. **Never test third parties** - Mock OAuth, external APIs, analytics165. **Prefer API setup over UI** - Seed data via API, test UI separately1718## Locator Priority (Use in Order)1920| Priority | Method | Example |21|----------|--------|---------|22| 1 | `getByRole()` | `getByRole('button', { name: 'Submit' })` |23| 2 | `getByLabel()` | `getByLabel('Email address')` |24| 3 | `getByText()` | `getByText('Welcome back')` |25| 4 | `getByPlaceholder()` | `getByPlaceholder('Search...')` |26| 5 | `getByTestId()` | `getByTestId('submit-btn')` |27| 6 | CSS/XPath | **AVOID** - fragile, breaks with styling |2829## Critical Anti-Patterns3031- **Never `waitForTimeout()`** - Use web-first assertions instead32- **Never CSS class selectors** - `.MuiButton-root` breaks on updates33- **Never XPath** - Hard to read, brittle34- **Never test dependencies** - Tests affect each other35- **Never skip isolation** - Parallel execution will fail3637## Quick Patterns3839```typescript40// ✅ Good: Role-based, auto-waiting41await expect(page.getByRole('button', { name: 'Save' })).toBeEnabled();42await page.getByRole('button', { name: 'Save' }).click();4344// ❌ Bad: CSS selector, manual wait45await page.waitForTimeout(2000);46await page.locator('.save-btn').click();47```4849## References5051For detailed patterns, see:52- `references/locators.md` - Chaining, filtering, nth-child53- `references/page-objects.md` - POM + fixtures pattern54- `references/auth.md` - storageState, multi-role55- `references/network.md` - Mocking, HAR recording56- `references/ci-cd.md` - GitHub Actions, sharding57- `references/headless-ui.md` - Dialog, Menu, Listbox testing58- `references/anti-patterns.md` - Full anti-pattern catalog
nexus-labs-automation