| name | end-to-end-testing |
| description | End-to-end (E2E) testing patterns for user journeys, browser automation, UI state, and production-like environment validation. Use when testing the system as a black box from the user's perspective. |
End-to-End Testing
Validate complete user workflows across the entire stack, ensuring that UI components, APIs, and databases work together in a production-like environment.
When to Activate
- Automate a critical user journey (Signup, Checkout, etc.)
- Resolve flaky browser tests or slow CI cycles
- Implement visual regression or screenshot testing
- Choose a selector strategy (ARIA vs CSS vs Test ID)
- Test cross-browser or mobile responsiveness
- Simulate network failures or latency in the UI
- Verify analytics or external tracking pixels
Selector Strategy
| Type | Example | Stability | Recommendation |
|---|
| User-facing (ARIA) | getByRole("button", { name: "Submit" }) | High | Primary: Tests what the user sees |
| Data attribute | getByTestId("submit-btn") | Medium | Secondary: Use when ARIA is ambiguous |
| CSS Class/ID | locator(".btn-primary") | Low | Avoid: Highly coupled to styling |
Execution Strategy
| Concern | Strategy |
|---|
| Test Data | Use a dedicated setup API or direct DB seed before each run |
| State Isolation | Clean cookies, localStorage, and indexedDB between tests |
| Waiting | Use auto-waiting or "Wait for State" (loading spinner gone) over hard sleeps |
BAD
await page.click('.login-submit');
await page.waitForTimeout(5000);
expect(await page.url()).toContain('/dashboard');
GOOD
const submitBtn = page.getByRole('button', { name: /log in/i });
await submitBtn.click();
await expect(page).toHaveURL(/\/dashboard/);
await expect(page.getByText(/welcome back/i)).toBeVisible();
Flakiness Prevention
| Risk | Solution |
|---|
| Animation lag | Disable CSS animations in the test environment |
| Third-party scripts | Block or stub chat widgets, ads, and telemetry |
| Race conditions | Assert state changes (e.g. "button is hidden") before next step |
Checklist
