How to fix flaky Playwright tests in CI

Approach 1: Debug and fix each flake

1. 1.Enable trace capture on first retry to collect actionability logs, DOM snapshots, and network timelines
2. 2.Run the failing test 50 times locally with --repeat-each=50 to reproduce intermittent failures
3. 3.Classify each flake: race condition, data dependency, environment difference, or external service timeout
4. 4.Replace implicit waits with explicit conditions: waitForLoadState, waitForFunction, or expect().toBeVisible()
5. 5.Isolate test data per worker using unique IDs or beforeEach cleanup to eliminate ordering dependencies
6. 6.Pin CI config: set workers to 1 for initial stability, then increase once flakes are resolved

Race conditions: when auto-wait isn't enough

Playwright's auto-wait is good. It checks that an element is visible, enabled, and stable before interacting with it. But "stable" in Playwright's definition means the element's bounding box hasn't changed between two animation frames. That is not the same as "ready for interaction." Three categories of race conditions survive auto-wait. First, CSS animations and transitions. A modal that slides in over 300ms is technically visible and stable midway through the animation, but clicking a button inside it while it is still moving can miss the target. Second, debounced inputs. If your search field waits 500ms after the last keystroke before firing a request, Playwright will type and immediately try to assert results, long before the debounce fires. Third, SPA route transitions. Client-side navigation with React Router, Next.js, or similar frameworks can update the URL before the destination component has mounted and rendered data. The fix is different for each case. For animations, wait for the animation to complete using waitForFunction that checks getComputedStyle or a specific CSS class. For debounced inputs, wait for the network request that the debounce triggers. For SPA transitions, wait for the actual content to appear on the destination page, not just the URL change. The code below shows a common flaky pattern and the fixed version for each case.

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

// BAD: Clicking a button inside an animating modal
test("flaky modal interaction", async ({ page }) => {
  await page.goto("/dashboard");
  await page.getByRole("button", { name: "New project" }).click();
  // Modal is animating in - click may miss
  await page.getByRole("button", { name: "Create" }).click();
});

// FIXED: Wait for animation to complete
test("stable modal interaction", async ({ page }) => {
  await page.goto("/dashboard");
  await page.getByRole("button", { name: "New project" }).click();

  // Wait for the modal to finish its CSS transition
  const modal = page.getByRole("dialog");
  await modal.waitFor({ state: "visible" });
  await page.waitForFunction(() => {
    const el = document.querySelector('[role="dialog"]');
    if (!el) return false;
    return getComputedStyle(el).opacity === "1";
  });

  await modal.getByRole("button", { name: "Create" }).click();
});

// BAD: Asserting search results before debounce fires
test("flaky search", async ({ page }) => {
  await page.goto("/users");
  await page.getByPlaceholder("Search").fill("alice");
  // Debounce hasn't fired yet - results are stale
  await expect(page.getByText("[email protected]")).toBeVisible();
});

// FIXED: Wait for the search request to complete
test("stable search", async ({ page }) => {
  await page.goto("/users");
  const searchResponse = page.waitForResponse(
    (resp) => resp.url().includes("/api/users") && resp.status() === 200
  );
  await page.getByPlaceholder("Search").fill("alice");
  await searchResponse;
  await expect(page.getByText("[email protected]")).toBeVisible();
});

Shared test data and ordering dependencies

This is the flake that makes you question your career choices. Every test passes when run alone. Every test passes when run in a specific order. But run them all in parallel, and 3 out of 40 fail randomly. The root cause is shared mutable state. Tests that read from or write to the same database rows, the same browser storage, or the same API resources will interfere with each other when execution order changes. Playwright runs test files in parallel by default (one worker per CPU core), and the order within a file is sequential but the order across files is not deterministic. Common patterns that cause this: test A creates a user with email [email protected], test B also creates a user with email [email protected], whoever runs second gets a unique constraint violation. Or test A deletes all items from a list, test B asserts the list has 3 items, and B fails because A ran first. The fix is test isolation. Each test should create its own data and not depend on data created by other tests. Use unique identifiers (timestamps, UUIDs) for test entities. Use beforeEach to set up fresh state and afterEach to clean up. For tests that genuinely depend on a sequence (like a multi-step workflow), use test.describe.serial() to force sequential execution within that describe block. Playwright's storageState feature is also useful for isolation. You can capture authenticated state in a setup step and reuse it across tests without them sharing a live session.

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

// BAD: Tests share the same user data
test("create project", async ({ page }) => {
  await page.goto("/projects");
  await page.getByRole("button", { name: "New" }).click();
  // This name collides when tests run in parallel
  await page.getByLabel("Name").fill("My Project");
  await page.getByRole("button", { name: "Create" }).click();
});

// FIXED: Unique data per test run
test("create project (isolated)", async ({ page }) => {
  const uniqueName = `Project-${Date.now()}-${Math.random()
    .toString(36)
    .slice(2, 7)}`;

  await page.goto("/projects");
  await page.getByRole("button", { name: "New" }).click();
  await page.getByLabel("Name").fill(uniqueName);
  await page.getByRole("button", { name: "Create" }).click();
  await expect(page.getByText(uniqueName)).toBeVisible();
});

// Sequential tests for dependent workflows
test.describe.serial("checkout workflow", () => {
  test("add item to cart", async ({ page }) => {
    await page.goto("/products/widget-1");
    await page.getByRole("button", { name: "Add to cart" }).click();
    await expect(page.getByTestId("cart-count")).toHaveText("1");
  });

  test("complete checkout", async ({ page }) => {
    await page.goto("/cart");
    await page.getByRole("button", { name: "Checkout" }).click();
    await expect(page).toHaveURL(/\/confirmation/);
  });
});

// Shared auth state without shared sessions
// In playwright.config.ts:
// { storageState: '.auth/user.json' }
// In auth.setup.ts:
test("authenticate", async ({ page }) => {
  await page.goto("/login");
  await page.getByLabel("Email").fill("[email protected]");
  await page.getByLabel("Password").fill(process.env.CI_TEST_PASSWORD!);
  await page.getByRole("button", { name: "Log in" }).click();
  await page.waitForURL("/dashboard");
  // Save signed-in state for other tests to reuse
  await page.context().storageState({ path: ".auth/user.json" });
});

The nuclear option: Playwright trace viewer for CI

When a test only flakes in CI and you cannot reproduce it locally, the trace viewer is your best diagnostic tool. A Playwright trace captures a complete recording of the test execution: every DOM snapshot, every network request, every console message, every action your test performed with exact timing. The recommended config is trace: 'on-first-retry'. This means Playwright runs the test normally on the first attempt (no trace overhead), and if it fails, the retry captures a full trace. This keeps your CI fast on green runs and gives you detailed diagnostics when something flakes. Once the trace is captured, you need to get it off the CI runner. Traces are saved as .zip files in the test-results directory. Configure your CI to upload this directory as a build artifact. In GitHub Actions, use the actions/upload-artifact step. In other CI systems, configure equivalent artifact storage. To analyze the trace, download the artifact and open it with npx playwright show-trace trace.zip. The trace viewer shows a timeline of every action, a DOM snapshot at each point, network requests with timing, and console logs. You can step through the test frame by frame and see exactly what the page looked like when the assertion failed. The key insight traces reveal for CI-specific flakes is timing. You can see that a click happened 50ms before an element finished animating, or that a network request took 4 seconds in CI versus 200ms locally. This concrete timing data turns a "works on my machine" problem into a specific, fixable issue.

# .github/workflows/e2e.yml
name: E2E Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium

      - name: Run Playwright tests
        run: npx playwright test
        env:
          CI: true

      # Upload traces and screenshots when tests fail
      - name: Upload test artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-traces
          path: test-results/
          retention-days: 7

# After downloading the artifact, analyze the trace:
# npx playwright show-trace test-results/my-test/trace.zip
#
# Or view traces in the HTML report:
# npx playwright show-report