/e2e-playwright

name: e2e-playwright
description: Use when writing end-to-end browser tests with Playwright. Covers resilient locators, auto-waiting, network interception, authentication reuse, parallelization, and eliminating flakiness. Trigger on "write playwright tests", "e2e test is flaky", "replace our cypress suite", "reuse login state in playwright". Do not use for manually checking a feature in a browser — see the web-app-testing skill; for screenshot diffs, see the visual-qa skill.
metadata:
  category: testing
  version: 1.0.0
  tags: [playwright, e2e, browser, flakiness, automation]

End-to-End Testing with Playwright

Purpose

Write browser tests that fail only when the application is broken. An end-to-end suite that fails randomly is worse than no suite: it consumes attention and trains the team to ignore red.

When to Use

• Testing a complete user journey through a real browser.
• Replacing a flaky Selenium or Cypress suite.
• Testing flows that cross pages, tabs, or authentication.
• Debugging an intermittent E2E failure.

Capabilities

• Resilient locators based on user-visible attributes.
• Auto-waiting and web-first assertions.
• Network interception, mocking, and request assertion.
• Authentication state reuse across tests.
• Parallel execution and sharding.
• Trace, video, and screenshot capture on failure.

Inputs

• The journeys that matter enough to test end to end (there are fewer than you think).
• The application, its authentication, and its test data strategy.

Outputs

• Tests locating elements by role and accessible name.
• Zero explicit waits or sleeps.
• Traces on failure that make a CI-only failure diagnosable.

Workflow

1. **Choose the journeys** — End-to-end tests are slow and expensive. Test the paths whose failure would be a serious incident: sign up, check out, pay. Not every form. 2. **Locate the way a user would** — `getByRole("button", { name: "Place order" })`. Not a CSS class, not an XPath. Class names change; the accessible name is the contract with the user. 3. **Never sleep** — Playwright's assertions auto-wait and retry. `waitForTimeout` is the single largest cause of both flakiness and slowness in an E2E suite. 4. **Reuse authentication** — Log in once in a setup project, save the storage state, and reuse it. Logging in before every test triples the suite runtime. 5. **Control the network where the test is not about the network** — Mock the third-party payment provider; do not depend on its sandbox being up. 6. **Capture traces on failure** — A CI failure with a trace is diagnosable in two minutes. Without one, it is a mystery.

Best Practices

• Any `waitForTimeout` in a Playwright test is a bug. If you need to wait for something, assert on the thing you are waiting for — the assertion retries until it is true.
• Locating by CSS class couples the test to the styling. A CSS refactor should not break the test suite.
• Tests must be independent and able to run in any order, in parallel. A test that depends on a previous test's data will fail intermittently forever.
• Each test creates the data it needs, with a unique identifier. Shared fixture data plus parallel execution equals a race condition.
• Assert on the user-visible outcome, not on an implementation detail. "The order confirmation shows the order number" — not "the POST returned 201".
• Run the suite against a production-like build. E2E tests against a dev server with hot reloading are testing something you do not ship.

Examples

**Resilient, independent, and free of sleeps:**

import { test, expect } from "@playwright/test";

test.describe("checkout", () => {
  test("a customer can place an order and see it confirmed", async ({ page }) => {
    // Unique data per test: the suite can run in parallel without collisions.
    const email = `test-${crypto.randomUUID()}@example.com`;
    await seedCustomer({ email, cardOnFile: true });

    // The payment provider is a third party. The test is not about their uptime.
    await page.route("**/v1/payment_intents", (route) =>
      route.fulfill({ status: 200, json: { id: "pi_test", status: "succeeded" } }),
    );

    await page.goto("/checkout");

    // Located as a user perceives them, not by class name.
    await page.getByRole("textbox", { name: "Email" }).fill(email);
    await page.getByRole("button", { name: "Place order" }).click();

    // Web-first assertion: retries until it passes or times out. No sleep needed.
    await expect(page.getByRole("heading", { name: "Order confirmed" })).toBeVisible();
    await expect(page.getByTestId("order-number")).toHaveText(/^ord_[0-9A-Z]{10}$/);
  });
});

**Authentication reused, not repeated:**

// auth.setup.ts — runs once, before everything.
setup("authenticate", async ({ page }) => {
  await page.goto("/login");
  await page.getByRole("textbox", { name: "Email" }).fill(process.env.TEST_USER!);
  await page.getByRole("textbox", { name: "Password" }).fill(process.env.TEST_PASS!);
  await page.getByRole("button", { name: "Sign in" }).click();
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();

  await page.context().storageState({ path: ".auth/user.json" });
});

// playwright.config.ts
projects: [
  { name: "setup", testMatch: /auth\.setup\.ts/ },
  {
    name: "chromium",
    dependencies: ["setup"],
    use: { storageState: ".auth/user.json" },   // every test starts logged in
  },
],

Notes

• `trace: "on-first-retry"` in the config gives you a full trace — DOM snapshots, network, console — for exactly the runs that failed, at negligible cost. It is the difference between debugging a CI flake in minutes and never diagnosing it.
• Playwright's auto-waiting covers actionability (visible, enabled, stable, receives events). It does not cover *your* application's asynchronous state — for that, assert on what the user would see.
• Component testing (Playwright, Vitest browser mode) covers far more ground