agents-inc/web-testing-playwright-e2e

Playwright E2E Testing Patterns

Quick Guide: Use Playwright for end-to-end tests that verify complete user workflows through the real browser. Focus on critical user journeys, use accessibility-based locators (getByRole), and leverage auto-waiting assertions -- never use manual sleeps. Isolate each test with its own browser context. Mock external APIs via route interception for reliability.

---

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use getByRole() as your primary locator strategy - it mirrors how users interact with the page)

(You MUST test complete user workflows end-to-end - login flows, checkout processes, form submissions)

(You MUST use web-first assertions that auto-wait - toBeVisible(), toHaveText(), not manual sleeps)

(You MUST isolate tests - each test runs independently with its own browser context)

(You MUST use named constants for test data - no magic strings or numbers in test files)

</critical_requirements>

---

Auto-detection: Playwright, E2E testing, end-to-end testing, browser automation, page.goto, test.describe, expect(page), getByRole, getByTestId, toBeVisible, toHaveScreenshot, toMatchAriaSnapshot

When to use:

• Testing critical user-facing workflows (login, checkout, form submission)
• Multi-step user journeys that span multiple pages
• Cross-browser compatibility testing
• Testing real integration with backend APIs
• Visual regression testing with screenshots
• Accessibility tree validation with ARIA snapshots

When NOT to use:

• Testing pure utility functions (use unit tests)
• Testing individual component variants in isolation (use component testing tools)
• API-only testing without UI (use API testing)

Key patterns covered:

• Test structure and organization (test.describe, test, hooks)
• Page Object Model pattern for maintainability
• Locator strategies prioritizing accessibility (getByRole, getByLabel, chaining, operators)
• Web-first assertions with auto-waiting (toBeVisible, toHaveText, soft assertions)
• Network mocking and interception (route.fulfill, route.abort, response modification)
• Visual regression testing (toHaveScreenshot, masking, thresholds)
• Custom and worker-scoped fixtures
• Clock API for time-dependent testing (v1.45+)
• ARIA snapshot testing for accessibility (v1.49+)
• Accessibility assertions (v1.44+): toHaveAccessibleName, toHaveRole

Detailed Resources:

• examples/core.md - User flows, page objects, network mocking, config, auth fixtures
• examples/page-objects.md - Base page inheritance, hierarchy
• examples/api-mocking.md - Response interception and modification
• examples/visual-testing.md - Screenshot comparison, component visual testing
• examples/fixtures.md - Combined fixtures, database seeding, IndexedDB state
• examples/advanced-features.md - Clock API, ARIA snapshots, worker fixtures, polling assertions, accessibility assertions
• reference.md - Decision frameworks, locator/assertion tables, anti-patterns, CLI commands, configuration reference

---

<philosophy>

Philosophy

Playwright E2E tests verify that your application works correctly from the user's perspective. They interact with the real browser, navigate through actual pages, and validate user-visible behavior.

Core Principles:

1. Test user-visible behavior - Focus on what end users see and interact with, not implementation details
2. Use accessibility locators - getByRole mirrors how screen readers and users interact with pages
3. Isolate tests completely - Each test has its own browser context, cookies, and storage
4. Trust auto-waiting - Playwright automatically waits for elements; no manual sleeps needed
5. Mock external dependencies - Use route interception for third-party APIs to ensure reliability

When E2E tests provide the most value:

• Critical business workflows (authentication, payments, core features)
• User journeys spanning multiple pages or components
• Testing real backend integration
• Cross-browser compatibility verification
• Catching integration bugs that unit tests miss

When E2E tests may not be the best choice:

• Testing pure utility functions (unit tests are faster and more precise)
• Testing component styling variants (use visual testing tools)
• Testing every edge case (balance with unit and integration tests)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Test Structure and Organization

Group related tests with test.describe, use beforeEach for common navigation, and name constants for all test data.

const LOGIN_URL = "/login";
const VALID_EMAIL = "[email protected]";

test.describe("Login Flow", () => {
  test.beforeEach(async ({ page }) => {
    await page.goto(LOGIN_URL);
  });

  test("successful login redirects to dashboard", async ({ page }) => {
    await page.getByLabel(/email/i).fill(VALID_EMAIL);
    // ... fill password, click sign in
    await expect(page).toHaveURL("/dashboard");
  });
});

Why good: Groups related tests logically, beforeEach maintains isolation, named constants prevent magic strings

See examples/core.md Pattern 1 for complete user flow with error scenarios.

---

Pattern 2: Page Object Model

Encapsulate page structure and interactions in reusable classes. Define locators in the constructor, expose domain-specific methods.

export class LoginPage {
  readonly emailInput: Locator;
  readonly signInButton: Locator;

  constructor(page: Page) {
    this.emailInput = page.getByLabel(/email/i);
    this.signInButton = page.getByRole("button", { name: /sign in/i });
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    // ...
  }
}

Why good: Centralizes locators -- UI changes update one place, methods encapsulate interactions

When to use: Tests spanning multiple interactions on the same page, reusable flows across test files.

When not to use: Simple one-off tests where inline locators are clearer.

See examples/core.md Pattern 2 for full page objects with fixtures, examples/page-objects.md for base page inheritance.

---

Pattern 3: Locator Strategies

Prioritize accessibility-based locators that mirror how users interact with the application.

// BEST: Accessibility-based
await page.getByRole("button", { name: /submit/i });
await page.getByLabel(/email address/i);
await page.getByText(/welcome back/i);

// ACCEPTABLE: Test IDs for complex cases
await page.getByTestId("user-avatar"); // When no semantic role exists

// AVOID: Implementation-dependent
await page.locator("#submit-btn"); // Fragile
await page.locator(".btn-primary"); // CSS class can change

Chaining and filtering narrow down to specific elements without fragile selectors:

await page
  .getByRole("listitem")
  .filter({ hasText: "Product A" })
  .getByRole("button", { name: /add to cart/i })
  .click();

// Exclude elements (v1.33+)
await page
  .getByRole("listitem")
  .filter({ hasNot: page.getByText("Out of stock") })
  .first()
  .click();

// Combine conditions (v1.33+)
const btn = page.getByRole("button").and(page.getByTitle("Subscribe"));

Why good: getByRole validates accessibility as a side effect, survives UI refactoring, chaining handles dynamic lists

See reference.md for locator priority table and common ARIA role mappings.

---

Pattern 4: Web-First Assertions

Use assertions that automatically wait and retry until the condition is met.

// Auto-waits for element visibility
await expect(page.getByText("Welcome")).toBeVisible();
// Auto-waits for URL
await expect(page).toHaveURL(/\/dashboard/);
// Negated assertions also auto-wait
await expect(page.getByRole("progressbar")).not.toBeVisible();

Why good: Eliminates flaky tests from race conditions, no manual sleeps needed

// BAD: Manual waiting
await page.waitForTimeout(2000); // Arbitrary sleep!
const text = await page.textContent(".result");
expect(text).toBe("Success"); // Non-waiting assertion

Why bad: Fixed timeouts are either too short (flaky) or too long (slow), doesn't adapt to actual page load time

Soft assertions collect all failures in one run:

await expect.soft(page.getByTestId("avatar")).toBeVisible();
await expect.soft(page.getByText("Premium")).toBeVisible();
// Test continues, all failures reported at end

See reference.md for complete assertion table, polling assertions, and accessibility assertions (v1.44+).

---

Pattern 5: Network Mocking and Interception

Mock external APIs for reliable, isolated tests. Use page.route() to intercept and fulfill requests.

const API_USERS = "**/api/users";

await page.route(API_USERS, (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ id: "user-123", name: "John Doe" }),
  }),
);

// Error simulation
await page.route(API_USERS, (route) => route.abort("failed")); // Network failure

Why good: Eliminates third-party flakiness, enables testing error states, controls exact data

Modifying real responses (hybrid approach):

await page.route("**/api/products", async (route) => {
  const response = await route.fetch();
  const json = await response.json();
  json.products = json.products.map((p: { price: number }) => ({
    ...p,
    price: p.price * 0.9,
  }));
  await route.fulfill({ response, json });
});

See examples/core.md Pattern 3 for complete mocking with error states, examples/api-mocking.md for response modification.

---

Pattern 6: Visual Regression Testing

Capture and compare screenshots to detect unintended visual changes.

await expect(page).toHaveScreenshot("homepage.png");

// Mask dynamic content
await expect(page).toHaveScreenshot("dashboard.png", {
  mask: [page.getByTestId("current-time"), page.getByTestId("random-ad")],
});

// Disable animations for deterministic screenshots
await expect(page).toHaveScreenshot("stable.png", { animations: "disabled" });

Why good: Catches unintended visual changes, masking prevents false positives from timestamps

See examples/visual-testing.md for component visual testing with state variations.

---

Pattern 7: Custom Fixtures

Extend the base test with reusable fixtures for page objects, authentication, and shared setup.

export const test = base.extend<{
  loginPage: LoginPage;
  authenticatedPage: void;
}>({
  loginPage: async ({ page }, use) => {
    await use(new LoginPage(page));
  },
  authenticatedPage: [
    async ({ context }, use) => {
      await context.addCookies([
        { name: "session", value: "token", domain: "localhost", path: "/" },
      ]);
      await use();
      await context.clearCookies();
    },
    { auto: true },
  ],
});

Why good: Encapsulates setup + teardown, auto fixtures eliminate repetitive auth, composable

See examples/core.md Pattern 5 for auth fixtures, examples/fixtures.md for combined fixtures and database seeding, examples/advanced-features.md for worker-scoped fixtures.

---

Pattern 8: Clock API (v1.45+)

Control time for testing countdowns, session timeouts, and scheduled events.

await page.clock.install({ time: new Date("2024-02-02T08:00:00") });
await page.goto("/dashboard");

await page.clock.fastForward("25:00"); // Jump 25 minutes
await expect(page.getByText(/session expires/i)).toBeVisible();

CRITICAL: clock.install() MUST be called before any other clock methods.

See examples/advanced-features.md for countdown testing and session timeout patterns.

---

Pattern 9: ARIA Snapshot Testing (v1.49+)

Validate accessibility tree structure programmatically.

await expect(page.getByRole("navigation")).toMatchAriaSnapshot(`
  - navigation:
    - link "Home"
    - link "Products"
    - link "About"
`);

Why good: Catches ARIA issues before production, documents expected accessibility behavior

See examples/advanced-features.md for complex component ARIA snapshots.

</patterns>

---

<red_flags>

RED FLAGS

High Priority Issues:

• Using page.waitForTimeout() with fixed delays -- causes flaky or slow tests, use auto-waiting assertions instead
• Using CSS selectors like .btn-primary or #submit-btn -- fragile and break on refactoring, use getByRole
• Not testing error states -- only happy paths leaves error handling untested
• Tests sharing state or data -- causes flaky failures in parallel execution, isolate each test completely

Medium Priority Issues:

• Using getByTestId as primary locator -- misses accessibility validation, prioritize getByRole
• No network mocking for external APIs -- third-party flakiness affects your tests
• Running E2E tests only on one browser -- cross-browser issues go undetected
• Screenshots without masking dynamic content -- timestamps and ads cause false positives

Common Mistakes:

• Hardcoded test data scattered throughout files -- use named constants
• Testing implementation details (e.g., Redux state via window.__REDUX_STATE__) instead of user behavior
• Not using beforeEach for common setup -- leads to duplicated code
• Mixing E2E tests with unit tests in the same directory

Gotchas & Edge Cases:

• toBeVisible() auto-waits for the element; toBeAttached() checks DOM presence without visibility -- prefer visibility checks for most cases
• Screenshots vary by OS and browser -- run visual tests in consistent CI environment
• beforeAll runs once per worker, not once globally -- use globalSetup in config for true one-time setup
• Network routes are global to context -- routes set in beforeEach override previous; always set up fresh per test
• Parallel tests cannot share state -- use fixtures for per-test setup, not shared variables
• toBeEditable() throws on non-editable elements (v1.50+) -- verify element type first
• Glob URL patterns in page.route() no longer support ? and [] (v1.52+) -- use regex instead
• route.continue() cannot override Cookie header (v1.52+) -- use context.addCookies() instead
• _react and _vue selectors removed (v1.58) -- use data-testid or role-based locators

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST use getByRole() as your primary locator strategy - it mirrors how users interact with the page)

(You MUST test complete user workflows end-to-end - login flows, checkout processes, form submissions)

(You MUST use web-first assertions that auto-wait - toBeVisible(), toHaveText(), not manual sleeps)

(You MUST isolate tests - each test runs independently with its own browser context)

(You MUST use named constants for test data - no magic strings or numbers in test files)

Failure to follow these rules will result in flaky tests, false positives, and maintenance nightmares.

</critical_reminders>