1---
2name: e2e-testing-patterns
3description: Master end-to-end testing with Playwright and Cypress to build reliable test suites that catch bugs, improve confidence, and enable fast deployment. Use when implementing E2E tests, debugging flaky tests, or establishing testing standards.
4---
5 
6# E2E Testing Patterns
7 
8Build reliable, fast, and maintainable end-to-end test suites that provide confidence to ship code quickly and catch regressions before users do.
9 
10## When to Use This Skill
11 
12- Implementing end-to-end test automation
13- Debugging flaky or unreliable tests
14- Testing critical user workflows
15- Setting up CI/CD test pipelines
16- Testing across multiple browsers
17- Validating accessibility requirements
18- Testing responsive designs
19- Establishing E2E testing standards
20 
21## Core Concepts
22 
23### 1. E2E Testing Fundamentals
24 
25**What to Test with E2E:**
26 
27- Critical user journeys (login, checkout, signup)
28- Complex interactions (drag-and-drop, multi-step forms)
29- Cross-browser compatibility
30- Real API integration
31- Authentication flows
32 
33**What NOT to Test with E2E:**
34 
35- Unit-level logic (use unit tests)
36- API contracts (use integration tests)
37- Edge cases (too slow)
38- Internal implementation details
39 
40### 2. Test Philosophy
41 
42**The Testing Pyramid:**
43 
44```
45        /\
46       /E2E\         ← Few, focused on critical paths
47      /─────\
48     /Integr\        ← More, test component interactions
49    /────────\
50   /Unit Tests\      ← Many, fast, isolated
51  /────────────\
52```
53 
54**Best Practices:**
55 
56- Test user behavior, not implementation
57- Keep tests independent
58- Make tests deterministic
59- Optimize for speed
60- Use data-testid, not CSS selectors
61 
62## Playwright Patterns
63 
64### Setup and Configuration
65 
66```typescript
67// playwright.config.ts
68import { defineConfig, devices } from "@playwright/test";
69 
70export default defineConfig({
71  testDir: "./e2e",
72  timeout: 30000,
73  expect: {
74    timeout: 5000,
75  },
76  fullyParallel: true,
77  forbidOnly: !!process.env.CI,
78  retries: process.env.CI ? 2 : 0,
79  workers: process.env.CI ? 1 : undefined,
80  reporter: [["html"], ["junit", { outputFile: "results.xml" }]],
81  use: {
82    baseURL: "http://localhost:3000",
83    trace: "on-first-retry",
84    screenshot: "only-on-failure",
85    video: "retain-on-failure",
86  },
87  projects: [
88    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
89    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
90    { name: "webkit", use: { ...devices["Desktop Safari"] } },
91    { name: "mobile", use: { ...devices["iPhone 13"] } },
92  ],
93});
94```
95 
96### Pattern 1: Page Object Model
97 
98```typescript
99// pages/LoginPage.ts
100import { Page, Locator } from "@playwright/test";
101 
102export class LoginPage {
103  readonly page: Page;
104  readonly emailInput: Locator;
105  readonly passwordInput: Locator;
106  readonly loginButton: Locator;
107  readonly errorMessage: Locator;
108 
109  constructor(page: Page) {
110    this.page = page;
111    this.emailInput = page.getByLabel("Email");
112    this.passwordInput = page.getByLabel("Password");
113    this.loginButton = page.getByRole("button", { name: "Login" });
114    this.errorMessage = page.getByRole("alert");
115  }
116 
117  async goto() {
118    await this.page.goto("/login");
119  }
120 
121  async login(email: string, password: string) {
122    await this.emailInput.fill(email);
123    await this.passwordInput.fill(password);
124    await this.loginButton.click();
125  }
126 
127  async getErrorMessage(): Promise<string> {
128    return (await this.errorMessage.textContent()) ?? "";
129  }
130}
131 
132// Test using Page Object
133import { test, expect } from "@playwright/test";
134import { LoginPage } from "./pages/LoginPage";
135 
136test("successful login", async ({ page }) => {
137  const loginPage = new LoginPage(page);
138  await loginPage.goto();
139  await loginPage.login("[email protected]", "password123");
140 
141  await expect(page).toHaveURL("/dashboard");
142  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
143});
144 
145test("failed login shows error", async ({ page }) => {
146  const loginPage = new LoginPage(page);
147  await loginPage.goto();
148  await loginPage.login("[email protected]", "wrong");
149 
150  const error = await loginPage.getErrorMessage();
151  expect(error).toContain("Invalid credentials");
152});
153```
154 
155### Pattern 2: Fixtures for Test Data
156 
157```typescript
158// fixtures/test-data.ts
159import { test as base } from "@playwright/test";
160 
161type TestData = {
162  testUser: {
163    email: string;
164    password: string;
165    name: string;
166  };
167  adminUser: {
168    email: string;
169    password: string;
170  };
171};
172 
173export const test = base.extend<TestData>({
174  testUser: async ({}, use) => {
175    const user = {
176      email: `test-${Date.now()}@example.com`,
177      password: "Test123!@#",
178      name: "Test User",
179    };
180    // Setup: Create user in database
181    await createTestUser(user);
182    await use(user);
183    // Teardown: Clean up user
184    await deleteTestUser(user.email);
185  },
186 
187  adminUser: async ({}, use) => {
188    await use({
189      email: "[email protected]",
190      password: process.env.ADMIN_PASSWORD!,
191    });
192  },
193});
194 
195// Usage in tests
196import { test } from "./fixtures/test-data";
197 
198test("user can update profile", async ({ page, testUser }) => {
199  await page.goto("/login");
200  await page.getByLabel("Email").fill(testUser.email);
201  await page.getByLabel("Password").fill(testUser.password);
202  await page.getByRole("button", { name: "Login" }).click();
203 
204  await page.goto("/profile");
205  await page.getByLabel("Name").fill("Updated Name");
206  await page.getByRole("button", { name: "Save" }).click();
207 
208  await expect(page.getByText("Profile updated")).toBeVisible();
209});
210```
211 
212### Pattern 3: Waiting Strategies
213 
214```typescript
215// ❌ Bad: Fixed timeouts
216await page.waitForTimeout(3000); // Flaky!
217 
218// ✅ Good: Wait for specific conditions
219await page.waitForLoadState("networkidle");
220await page.waitForURL("/dashboard");
221await page.waitForSelector('[data-testid="user-profile"]');
222 
223// ✅ Better: Auto-waiting with assertions
224await expect(page.getByText("Welcome")).toBeVisible();
225await expect(page.getByRole("button", { name: "Submit" })).toBeEnabled();
226 
227// Wait for API response
228const responsePromise = page.waitForResponse(
229  (response) =>
230    response.url().includes("/api/users") && response.status() === 200,
231);
232await page.getByRole("button", { name: "Load Users" }).click();
233const response = await responsePromise;
234const data = await response.json();
235expect(data.users).toHaveLength(10);
236 
237// Wait for multiple conditions
238await Promise.all([
239  page.waitForURL("/success"),
240  page.waitForLoadState("networkidle"),
241  expect(page.getByText("Payment successful")).toBeVisible(),
242]);
243```
244 
245### Pattern 4: Network Mocking and Interception
246 
247```typescript
248// Mock API responses
249test("displays error when API fails", async ({ page }) => {
250  await page.route("**/api/users", (route) => {
251    route.fulfill({
252      status: 500,
253      contentType: "application/json",
254      body: JSON.stringify({ error: "Internal Server Error" }),
255    });
256  });
257 
258  await page.goto("/users");
259  await expect(page.getByText("Failed to load users")).toBeVisible();
260});
261 
262// Intercept and modify requests
263test("can modify API request", async ({ page }) => {
264  await page.route("**/api/users", async (route) => {
265    const request = route.request();
266    const postData = JSON.parse(request.postData() || "{}");
267 
268    // Modify request
269    postData.role = "admin";
270 
271    await route.continue({
272      postData: JSON.stringify(postData),
273    });
274  });
275 
276  // Test continues...
277});
278 
279// Mock third-party services
280test("payment flow with mocked Stripe", async ({ page }) => {
281  await page.route("**/api/stripe/**", (route) => {
282    route.fulfill({
283      status: 200,
284      body: JSON.stringify({
285        id: "mock_payment_id",
286        status: "succeeded",
287      }),
288    });
289  });
290 
291  // Test payment flow with mocked response
292});
293```
294 
295## Cypress Patterns
296 
297### Setup and Configuration
298 
299```typescript
300// cypress.config.ts
301import { defineConfig } from "cypress";
302 
303export default defineConfig({
304  e2e: {
305    baseUrl: "http://localhost:3000",
306    viewportWidth: 1280,
307    viewportHeight: 720,
308    video: false,
309    screenshotOnRunFailure: true,
310    defaultCommandTimeout: 10000,
311    requestTimeout: 10000,
312    setupNodeEvents(on, config) {
313      // Implement node event listeners
314    },
315  },
316});
317```
318 
319### Pattern 1: Custom Commands
320 
321```typescript
322// cypress/support/commands.ts
323declare global {
324  namespace Cypress {
325    interface Chainable {
326      login(email: string, password: string): Chainable<void>;
327      createUser(userData: UserData): Chainable<User>;
328      dataCy(value: string): Chainable<JQuery<HTMLElement>>;
329    }
330  }
331}
332 
333Cypress.Commands.add("login", (email: string, password: string) => {
334  cy.visit("/login");
335  cy.get('[data-testid="email"]').type(email);
336  cy.get('[data-testid="password"]').type(password);
337  cy.get('[data-testid="login-button"]').click();
338  cy.url().should("include", "/dashboard");
339});
340 
341Cypress.Commands.add("createUser", (userData: UserData) => {
342  return cy.request("POST", "/api/users", userData).its("body");
343});
344 
345Cypress.Commands.add("dataCy", (value: string) => {
346  return cy.get(`[data-cy="${value}"]`);
347});
348 
349// Usage
350cy.login("[email protected]", "password");
351cy.dataCy("submit-button").click();
352```
353 
354### Pattern 2: Cypress Intercept
355 
356```typescript
357// Mock API calls
358cy.intercept("GET", "/api/users", {
359  statusCode: 200,
360  body: [
361    { id: 1, name: "John" },
362    { id: 2, name: "Jane" },
363  ],
364}).as("getUsers");
365 
366cy.visit("/users");
367cy.wait("@getUsers");
368cy.get('[data-testid="user-list"]').children().should("have.length", 2);
369 
370// Modify responses
371cy.intercept("GET", "/api/users", (req) => {
372  req.reply((res) => {
373    // Modify response
374    res.body.users = res.body.users.slice(0, 5);
375    res.send();
376  });
377});
378 
379// Simulate slow network
380cy.intercept("GET", "/api/data", (req) => {
381  req.reply((res) => {
382    res.delay(3000); // 3 second delay
383    res.send();
384  });
385});
386```
387 
388## Advanced Patterns
389 
390### Pattern 1: Visual Regression Testing
391 
392```typescript
393// With Playwright
394import { test, expect } from "@playwright/test";
395 
396test("homepage looks correct", async ({ page }) => {
397  await page.goto("/");
398  await expect(page).toHaveScreenshot("homepage.png", {
399    fullPage: true,
400    maxDiffPixels: 100,
401  });
402});
403 
404test("button in all states", async ({ page }) => {
405  await page.goto("/components");
406 
407  const button = page.getByRole("button", { name: "Submit" });
408 
409  // Default state
410  await expect(button).toHaveScreenshot("button-default.png");
411 
412  // Hover state
413  await button.hover();
414  await expect(button).toHaveScreenshot("button-hover.png");
415 
416  // Disabled state
417  await button.evaluate((el) => el.setAttribute("disabled", "true"));
418  await expect(button).toHaveScreenshot("button-disabled.png");
419});
420```
421 
422### Pattern 2: Parallel Testing with Sharding
423 
424```typescript
425// playwright.config.ts
426export default defineConfig({
427  projects: [
428    {
429      name: "shard-1",
430      use: { ...devices["Desktop Chrome"] },
431      grepInvert: /@slow/,
432      shard: { current: 1, total: 4 },
433    },
434    {
435      name: "shard-2",
436      use: { ...devices["Desktop Chrome"] },
437      shard: { current: 2, total: 4 },
438    },
439    // ... more shards
440  ],
441});
442 
443// Run in CI
444// npx playwright test --shard=1/4
445// npx playwright test --shard=2/4
446```
447 
448### Pattern 3: Accessibility Testing
449 
450```typescript
451// Install: npm install @axe-core/playwright
452import { test, expect } from "@playwright/test";
453import AxeBuilder from "@axe-core/playwright";
454 
455test("page should not have accessibility violations", async ({ page }) => {
456  await page.goto("/");
457 
458  const accessibilityScanResults = await new AxeBuilder({ page })
459    .exclude("#third-party-widget")
460    .analyze();
461 
462  expect(accessibilityScanResults.violations).toEqual([]);
463});
464 
465test("form is accessible", async ({ page }) => {
466  await page.goto("/signup");
467 
468  const results = await new AxeBuilder({ page }).include("form").analyze();
469 
470  expect(results.violations).toEqual([]);
471});
472```
473 
474## Best Practices
475 
4761. **Use Data Attributes**: `data-testid` or `data-cy` for stable selectors
4772. **Avoid Brittle Selectors**: Don't rely on CSS classes or DOM structure
4783. **Test User Behavior**: Click, type, see - not implementation details
4794. **Keep Tests Independent**: Each test should run in isolation
4805. **Clean Up Test Data**: Create and destroy test data in each test
4816. **Use Page Objects**: Encapsulate page logic
4827. **Meaningful Assertions**: Check actual user-visible behavior
4838. **Optimize for Speed**: Mock when possible, parallel execution
484 
485```typescript
486// ❌ Bad selectors
487cy.get(".btn.btn-primary.submit-button").click();
488cy.get("div > form > div:nth-child(2) > input").type("text");
489 
490// ✅ Good selectors
491cy.getByRole("button", { name: "Submit" }).click();
492cy.getByLabel("Email address").type("[email protected]");
493cy.get('[data-testid="email-input"]').type("[email protected]");
494```
495 
496## Common Pitfalls
497 
498- **Flaky Tests**: Use proper waits, not fixed timeouts
499- **Slow Tests**: Mock external APIs, use parallel execution
500- **Over-Testing**: Don't test every edge case with E2E
501- **Coupled Tests**: Tests should not depend on each other
502- **Poor Selectors**: Avoid CSS classes and nth-child
503- **No Cleanup**: Clean up test data after each test
504- **Testing Implementation**: Test user behavior, not internals
505 
506## Debugging Failing Tests
507 
508```typescript
509// Playwright debugging
510// 1. Run in headed mode
511npx playwright test --headed
512 
513// 2. Run in debug mode
514npx playwright test --debug
515 
516// 3. Use trace viewer
517await page.screenshot({ path: 'screenshot.png' });
518await page.video()?.saveAs('video.webm');
519 
520// 4. Add test.step for better reporting
521test('checkout flow', async ({ page }) => {
522    await test.step('Add item to cart', async () => {
523        await page.goto('/products');
524        await page.getByRole('button', { name: 'Add to Cart' }).click();
525    });
526 
527    await test.step('Proceed to checkout', async () => {
528        await page.goto('/cart');
529        await page.getByRole('button', { name: 'Checkout' }).click();
530    });
531});
532 
533// 5. Inspect page state
534await page.pause();  // Pauses execution, opens inspector
535```
536