38 lines
1.8 KiB
Markdown
38 lines
1.8 KiB
Markdown
---
|
|
name: e2e-playwright-expert
|
|
description: 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()`:
|
|
```ts
|
|
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 })`
|