How to fix flaky Playwright tests in CI

Approach 1: Find and fix each flake

1. 1.Set trace: 'on-first-retry' so a retry records DOM snapshots, network and timing without slowing green runs.
2. 2.Reproduce locally with npx playwright test --repeat-each=50 --retries=0 on the failing file.
3. 3.Classify the failure: race condition, shared data, environment difference or an external service.
4. 4.Replace guesses with conditions: expect(locator).toBeVisible(), waitForResponse(), waitForURL(). Never waitForTimeout().
5. 5.Give each test its own data with unique names and a fresh state; use serial mode only for genuinely dependent steps.
6. 6.Fix the root cause, then re-enable parallel workers. Retries are a safety net, not a fix.

Race conditions that survive auto-wait

Playwright’s auto-wait is good, and its definition of “stable” is precise: the element’s bounding box has not changed across two consecutive animation frames. A slide or a scale moves the box, so Playwright waits for it. What gets through is everything that leaves the box alone. Three kinds of race survive. Fades and late layout: a dialog fading in has its final bounding box from the first frame, so Playwright treats it as ready while it is still transparent and the app may still be ignoring input; content that finishes loading after the check can shift the target. Debounced inputs: a search box that waits after the last keystroke before requesting results will still show stale results when the assertion runs. Client-side navigation: the URL can change before the destination component has fetched its data. The fix is the same shape each time: wait for the condition that means ready, not for time. Wait for the element’s animations to finish, wait for the response the debounce triggers, and assert on content that only exists once the destination has rendered.

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

// Flaky: a fading dialog has a stable box from the first frame, so the click can land while it is still transparent.
test('create project (flaky)', async ({ page }) => {
  await page.goto('/dashboard');
  await page.getByRole('button', { name: 'New project' }).click();
  await page.getByRole('button', { name: 'Create' }).click();
});

// Fixed: wait for the transition to finish before interacting.
test('create project', async ({ page }) => {
  await page.goto('/dashboard');
  await page.getByRole('button', { name: 'New project' }).click();
  const dialog = page.getByRole('dialog');
  await expect(dialog).toBeVisible();
  await dialog.evaluate((el) => Promise.all(el.getAnimations().map((a) => a.finished)));
  await dialog.getByRole('button', { name: 'Create' }).click();
});

// Flaky: the assertion can run before the debounced request has fired.
test('search users (flaky)', async ({ page }) => {
  await page.goto('/users');
  await page.getByPlaceholder('Search').fill('alice');
  await expect(page.getByText('[email protected]')).toBeVisible();
});

// Fixed: register the response wait before typing, then await it.
test('search users', async ({ page }) => {
  await page.goto('/users');
  const results = page.waitForResponse((r) => r.url().includes('/api/users') && r.ok());
  await page.getByPlaceholder('Search').fill('alice');
  await results;
  await expect(page.getByText('[email protected]')).toBeVisible();
});

Shared data and ordering dependencies

Every test passes alone. Every test passes in a fixed order. Run the suite in parallel and a few fail at random. The cause is shared mutable state: two tests that create the same user, or one that empties a list another one counts. Playwright runs files in parallel by default, so order across files is not deterministic. The fix is isolation. Each test creates its own data with a unique name and does not depend on what another test left behind. Where steps are genuinely sequential, put them in one describe block in serial mode and share a page explicitly, so the dependency is visible in the code rather than hidden in worker scheduling. Authentication is the shared state most teams get wrong. Sign in once in a setup project, save the storage state to a file, and let every test start from that file. Tests then share a saved session without sharing a live browser. Share an account only when tests do not mutate conflicting server-side state; otherwise use separate accounts and fixtures. Add .auth/ to .gitignore and exclude saved authentication state from shared artifacts because it contains reusable login credentials.

import { test, expect, type Page } from '@playwright/test';

// Flaky in parallel: two workers both create 'My Project' and one hits a uniqueness error.
test('create project (flaky)', async ({ page }) => {
  await page.goto('/projects');
  await page.getByRole('button', { name: 'New' }).click();
  await page.getByLabel('Name').fill('My Project');
  await page.getByRole('button', { name: 'Create' }).click();
});

// Fixed: every test owns its data.
test('create project', async ({ page }, testInfo) => {
  const name = `Project ${testInfo.workerIndex}-${Date.now()}`;
  await page.goto('/projects');
  await page.getByRole('button', { name: 'New' }).click();
  await page.getByLabel('Name').fill(name);
  await page.getByRole('button', { name: 'Create' }).click();
  await expect(page.getByText(name)).toBeVisible();
});

// Genuinely dependent steps: one worker, one shared page, in order.
test.describe('checkout', () => {
  test.describe.configure({ mode: 'serial' });
  let page: Page;
  test.beforeAll(async ({ browser }) => { page = await browser.newPage(); });
  test.afterAll(async () => { await page.close(); });

  test('adds an item', async () => {
    await page.goto('/products/widget');
    await page.getByRole('button', { name: 'Add to cart' }).click();
    await expect(page.getByTestId('cart-count')).toHaveText('1');
  });

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

How Zerocheck exposes recovery

A moved control can be resolved again from its description. The result records old and new targets, the reason and validation state. A repair is saved only after the unchanged test passes with independent evidence; a failed assertion stays a failure. A disabled intended control fails rather than healing to a different enabled control.

Read the trace instead of guessing

When a test flakes only in CI, the trace viewer is the tool that turns “works on my machine” into a specific fix. A trace records every action with timing, a DOM snapshot at each step, network requests and console output. With trace: 'on-first-retry' the trace describes the retry, not the initial failing attempt. Use trace: 'retain-on-failure' when you need the original failure's trace, accepting its recording overhead. Treat traces as sensitive test artifacts. Get the trace off the runner by uploading the test-results directory even when a retry makes the job pass, then open it locally with npx playwright show-trace. Step through to the failing action and read the timing: a click that fired before an animation ended, or a request that took far longer in CI than locally. That is the evidence a fix can be written against.

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

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
        env:
          CI: true
      # Keep available evidence even when a retry passes.
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-results
          path: test-results/
          if-no-files-found: ignore
          retention-days: 7

# Locally: npx playwright show-trace test-results/<test-name>/trace.zip