testing-e2e

# End-to-End Testing Best Practices Expert guidance for system-wide e2e tests spanning multiple processes. **Scope:** System-wide end-to-end tests only. NOT for unit, integration, or component tests with mocked backends - use `testing-unit-integration` skill instead. **Note:** E2E tests are complex, slow, and limited in quantity - relaxed readability standards and less stringent best practices are acceptable compared to unit tests. ## Core Rules ### Self-Contained Tests (Critical) - **A.8** Each test is self-contained, never relies on other tests' state or artifacts - **A.11** Start with fresh dedicated data created in beforeEach or during test - **A.14** Test real user scenarios, simulate actual user behavior - **A.35** Implement comprehensive test data management with automatic cleanup ### User-Facing Locators (Critical) - **A.17** Only ARIA-based locators: `getByRole`, `getByLabel`, `getByText` - **A.17** NO CSS selectors, test IDs, xpath, $, or implementation-specific locators - **A.40** No positional selectors: nth(i), first(), last() ### Boundaries - **A.23** Only visit and test within application boundaries - **A.48** Don't approach or assert on external systems - assert navigation happened ### Structure - **A.5** Title summarizes flow with stakeholder, action, expectations - **A.26** Max 15 statements - encapsulate multi-step operations in helper functions ## Helper Functions Pattern Each helper represents a meaningful part of user's journey, not low-level interactions: ```typescript // ✅ GOOD - Semantic helpers async function loginAsAdmin(page: Page): Promise<void> async function addProductToCart(page: Page, product: Product): Promise<void> async function completeCheckout(page: Page): Promise<OrderDetails> async function verifyOrderConfirmationEmailSent(email: string, order: OrderDetails): Promise<void> // ❌ BAD - Low-level interactions exposed async function clickButton(page: Page, name: string): Promise<void> async function fillInput(page: Page, selector: string, value: string): Promise<void> ``` ## Waiting Strategies - **A.44** No time-based waiting: `setTimeout`, `page.waitForTimeout()` - **A.44** No `waitForSelector` - couples test to implementation - **A.20** Use auto-retriable assertions (web-first assertions): ```typescript // ❌ BAD await page.waitForTimeout(3000) await page.waitForSelector('.form-loaded') // ✅ GOOD - Auto-retriable assertions await expect(page.getByText(/success/i)).toBeVisible() await expect(page).toHaveURL(/\/dashboard/) ``` ## Data Factories - **A.52** Data from factory files with `buildEntity()` functions - **A.52** Factories return defaults but allow field overrides - **A.55** Use meaningful domain data with faker, not dummy values ```typescript import { faker } from "@faker-js/faker"; import { Customer } from "../types"; export function buildCustomer(overrides: Partial<Customer> = {}): Customer { return { email: faker.internet.email(), name: faker.person.fullName(), address: faker.location.streetAddress(), ...overrides, }; } ``` ## Assertions - **A.58** No custom coding, loops, Array.prototype - use built-in expect APIs - **A.62** Minimal assertions - one strong assertion catches all issues - **A.65** Use matchers that show full diff on failure ### Strong Assertions ```typescript // ❌ WEAK - Multiple redundant assertions expect(response).not.toBeNull() expect(Array.isArray(response)).toBe(true) expect(response.length).toBe(2) // ✅ STRONG - Single assertion catches all expect(response).toEqual([{id: '123'}, {id: '456'}]) ``` ## Navigation Testing E2E tests catch navigation bugs that mocked unit/integration tests miss. - **A.50** Assert navigation OUTCOME (destination page renders), not that navigate() was called - **A.52** Test router config must match production router - use real routes, not mocked - **A.54** Use route constants, not hardcoded path strings - prevents typos and drift - **A.56** Verify URL changed to expected value after navigation actions - **A.58** E2E tests are the safety net - they catch contract and navigation bugs that mocked tests miss ```typescript // ❌ BAD - Testing that navigate function was called (implementation detail) expect(mockNavigate).toHaveBeenCalledWith('/users/123'); // ❌ BAD - Hardcoded path string (typos won't be caught) await page.goto('/usres/123'); // Typo! Would fail silently in unit test // ✅ GOOD - Assert the OUTCOME (user sees the page) await expect(page.getByRole('heading', { name: /user profile/i })).toBeVisible(); // ✅ GOOD - Verify URL changed await expect(page).toHaveURL(/\/users\/\d+/); // ✅ GOOD - Use route constants (from shared constants file) import { ROUTES } from '@/constants/routes'; await page.goto(ROUTES.USER_PROFILE.replace(':id', '123')); ``` ### Why E2E Catches What Unit Tests Miss | Bug Type | Unit Test (Mocked) | E2E Test | |----------|-------------------|----------| | Route typo in navigate('/usres') | ❌ Passes (mock doesn't validate) | ✅ Fails (404 page) | | Route param mismatch (email vs id) | ❌ Passes (mock accepts anything) | ✅ Fails (wrong page loads) | | Missing route in router config | ❌ Passes (mock doesn't use router) | ✅ Fails (404 or error) | | Backend contract change | ❌ Passes (mock returns fantasy data) | ✅ Fails (real API different) | ## Maximum Coverage, Minimal Tests E2E tests are expensive - maximize value per test: - Each test covers a complete user journey - Combine verification steps that belong to same flow - Focus on critical paths and high-risk scenarios - Use helper functions to keep tests readable despite complexity ## BAD E2E Test Example ```typescript test('Should purchase item', async ({ page }) => { // ❌ A.5 - vague title await page.goto('/products') // ❌ A.8, A.11 - assumes existing session await page.getByText('iPhone 15 Pro').click() // ❌ A.8 - assumes specific product await page.locator('#add-to-cart-btn').click() // ❌ A.17 - CSS selector await page.goto('/checkout') await page.waitForSelector('.form-loaded') // ❌ A.44 - implementation detail await page.locator('#email').fill('foo@test.com') // ❌ A.17, A.55 - CSS + dummy data await page.locator('button').last().click() // ❌ A.17, A.40 - positional const cartItems = await page.locator('.cart-item').all() // ❌ A.58 - custom loop for (const item of cartItems) expect(await item.isVisible()).toBe(true) // ❌ A.58 await page.goto('https://stripe.com/confirm') // ❌ A.23 - external system expect(await page.evaluate(() => localStorage.getItem('orderId'))).toBeTruthy() // ❌ A.14 - implementation }) ``` ## GOOD E2E Test Example ```typescript test('The user can purchase an item and post-purchase experience is valid', async ({ page }) => { // Arrange - Create fresh test data const customer = await saveNewCustomer(buildCustomer()) const product = await saveNewProduct(buildProduct()) // Act - User journey through semantic helpers await navigateToProductsPage(page) await selectProduct(page, product) await goToCheckout(page) await fillCustomerDetails(page, customer) await fillPaymentDetails(page, buildCreditCard()) // Assert - Verify outcomes const orderDetails = await submitOrderAndVerifySuccessPage(page) await verifyOrderConfirmationEmailSent(customer.email, orderDetails) await verifySupplyRequestWasCreated(customer.email, orderDetails) }) ``` ## Selector Reference For detailed selector patterns, page object best practices, and resilience strategies, see: **`references/playwright-resilience.md`** - Comprehensive guide including: - Selector priority table (getByRole > getByLabel > getByPlaceholder...) - Bad vs Good patterns for forms, buttons, headings, waiting - When to use data-testid (error messages, toasts, loading indicators) - Page Object best practices - Text matching strategies (regex, partial, exact) - Quick reference for all element types ## Rule Violation Reporting When reviewing e2e tests, report violations as: ``` Line X: Violates [RULE_NUMBER] - [Brief explanation] ``` Example: ``` Line 8: Violates A.17 - Uses CSS selector '#email', should use getByLabel('Email') Line 12: Violates A.44 - Uses waitForTimeout, should use auto-retriable assertion Line 15: Violates A.23 - Navigates to external domain stripe.com ```