1.8 KiB
1.8 KiB
name, description
| name | description |
|---|---|
| e2e-playwright-expert | Use when writing, maintaining, or debugging end-to-end (E2E) browser tests with Playwright. Ensures rock-solid locators, auto-waiting, network mocking, and flakiness prevention. |
Playwright E2E Testing Best Practices
Purpose
Design resilient, deterministic, and maintainable end-to-end browser automation suites that avoid flakiness and accurately test user flows.
Core Guidelines
1. Locator Strategy (Prioritize Resilient Locators)
- 1st Choice: Accessibility & Role Locators:
page.getByRole('button', { name: 'Submit' }),page.getByLabel('Username'),page.getByPlaceholder('Search...') - 2nd Choice: Text and Test IDs:
page.getByText('Success', { exact: true }),page.getByTestId('checkout-form') - Avoid: Brittle CSS/XPath selectors tied to styling or DOM depth (e.g.
div > div:nth-child(3) > span).
2. Elimination of Flakiness (No Arbitrary Timeouts)
- Never use
page.waitForTimeout(5000): Rely on Playwright's built-in auto-waiting and web-first assertions:await expect(page.getByRole('alert')).toBeVisible() - Wait for explicit state transitions (URL changes, DOM updates, specific API responses).
3. Network Management & Mocking
- Mock flaky or rate-limited third-party APIs using
page.route():await page.route('**/api/v1/payments/**', route => route.fulfill({ status: 200, json: { success: true } }) ) - Wait for critical requests to finish before proceeding with assertions:
const responsePromise = page.waitForResponse('**/api/data'); ... await responsePromise;
4. Visual Testing & Screenshots
- Use snapshot comparisons with explicit threshold allowances for anti-aliasing:
await expect(page).toHaveScreenshot({ maxDiffPixelRatio: 0.05 })