| name | playwright-e2e |
| description | 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. |
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
await expect(page.getByRole('button', { name: 'Save' })).toBeEnabled();
await page.getByRole('button', { name: 'Save' }).click();
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
