Flaky Playwright tests are rarely random. They usually fail for a reason that is just hard enough to hide behind a rerun, a different machine, or a slightly slower page load. If you treat every failure as “the test is flaky,” you end up guessing at fixes, adding retries, and making the suite slower without making it more trustworthy.

A better approach is to debug Playwright test flakiness by failure signature. Is the failure caused by timing, selector drift, race conditions, or environment differences between local and CI? Each class leaves a different trail in the trace, the screenshot, the console, and the DOM snapshot. Once you learn to read those signals, the fix becomes much more obvious.

This guide focuses on Playwright test flakiness debugging as a forensic exercise, not a superstition exercise. The goal is to narrow the problem before changing code.

What flaky tests usually look like

A flaky test is a test that sometimes passes and sometimes fails with the same code, same input, and same intended outcome. In practice, the failure often comes from one of four sources:

  • Playwright timing issues: the test checks too early, or the app has not finished a UI transition yet.
  • Selector drift: the locator points to an element that changed, moved, or became ambiguous.
  • CI-only failures: the test is sensitive to machine speed, viewport size, fonts, parallelism, or network conditions.
  • Race conditions: two actions overlap, one event handler is still active, or the app state is not settled when the assertion runs.

The important thing is that these do not always show up as the same error. A timeout can mean a missing selector, a bad wait, a blocked API call, or a slow animation. A failed assertion can mean the app is broken, or it can mean the test asserted before the state stabilized.

If you cannot explain the failure signature, do not start by increasing the timeout. Start by identifying what changed between the passing and failing runs.

First step, classify the failure signature

Before editing the test, collect the artifacts that tell you what the browser saw:

  • Playwright trace
  • screenshot at failure
  • video, if enabled
  • console logs
  • network failures
  • DOM snapshot around the action or assertion

If you do not already run trace collection in CI, this is worth adding. Playwright’s trace viewer is often the fastest route to root cause because it shows the sequence of actions, snapshots, and timing around each step.

A useful debugging question is:

  1. Did the test fail before the first user action?
  2. Did it fail while locating or clicking an element?
  3. Did it fail after the action, at the assertion?
  4. Did it pass locally but fail in CI only?
  5. Did it start failing after a UI change, a dependency update, or a browser upgrade?

Those answers often map directly to the cause.

Timing failures, when the app is not ready yet

Timing failures are usually the easiest to misdiagnose because the test is not necessarily “too fast” in a simple sense. It may be waiting on the wrong condition.

Common symptoms:

  • TimeoutError waiting for a selector that appears later than expected
  • click works locally, but fails in CI on slower hardware
  • assertion on text or count fails right after navigation
  • intermittent failures around loading spinners, animated panels, or lazy-loaded content

What to inspect

Check whether the app is actually ready at the moment of the action. In Playwright, many flakiness issues come from assuming that DOM presence equals usability. An element can exist, but still be hidden, disabled, overlapped, or replaced during a re-render.

A typical mistake is waiting for the wrong signal:

typescript

await page.waitForSelector('[data-testid="submit"]');
await page.click('[data-testid="submit"]');

This only proves the element exists, not that it is visible, stable, or ready to receive a click. Prefer locators with built-in actionability checks:

typescript

const submit = page.getByRole('button', { name: 'Submit' });
await expect(submit).toBeVisible();
await submit.click();

Even better, if the app exposes a deterministic readiness signal, wait for that signal instead of a UI side effect. For example, wait for a specific API response, a URL change, or a stable piece of content.

What usually fixes it

  • wait for the specific post-condition, not a generic sleep
  • assert on a stable UI state after the relevant network call finishes
  • avoid waitForTimeout unless you are reproducing a bug or testing animation timing
  • if the test depends on loading data, stub the data or use deterministic fixtures

A common race looks like this:

typescript

await page.getByRole('button', { name: 'Save' }).click();
await expect(page.getByText('Saved')).toBeVisible();

If “Saved” appears only after an API response and UI re-render, this is usually fine. But if the app briefly shows success then re-renders the component, the text can blink in and out. In that case, assert on the persisted state, not the transient message.

Selector drift, when the locator no longer matches reality

Selector drift is one of the most common causes of flaky tests after UI refactors. A test passes until a class name changes, a component is split, or a list order changes. The locator still exists, but it is no longer pointing to the intended element.

Common symptoms:

  • element not found after a UI rewrite
  • click hits the wrong duplicate element
  • a test passes on one branch and fails on another with the same flow
  • failures begin after a CSS, component, or design system update

Look for brittle locator patterns

The most fragile selectors are usually:

  • CSS classes generated by styling tools
  • deeply nested absolute selectors
  • index-based selectors like nth-child
  • text locators used on duplicated labels
  • IDs that are regenerated per render or per deployment

Prefer locators that encode user intent, not implementation detail. In Playwright, this usually means accessible roles, labels, and stable test IDs.

typescript

await page.getByRole('button', { name: 'Add to cart' }).click();
await page.getByLabel('Email').fill('qa@example.com');
await page.getByTestId('checkout-submit').click();

If you have duplicate labels, the problem may not be the locator itself, but the page design. Test selectors are often a mirror of accessibility quality. If the test cannot uniquely identify a control through role or label, users may also struggle to understand the UI.

How to debug selector drift quickly

When a locator fails, inspect the page around the target element:

  • Did the element move into a new component?
  • Was the accessible name changed?
  • Is there a duplicate with the same text?
  • Is the target inside a modal, iframe, or shadow root?
  • Did the target become virtualized or lazy-rendered?

If you can reproduce locally, use Playwright’s locator debugging in headed mode and print the relevant DOM state. In many cases, the test is not flaky, it is too specific.

CI-only failures, when the environment is part of the bug

A test that passes locally and fails in CI is not automatically a test problem. The environment may be different enough to expose an actual bug, or enough to expose a hidden test assumption.

Common differences between local and CI:

  • CPU and memory pressure
  • containerized browsers and limited shared resources
  • different viewport size or device scale factor
  • missing fonts, OS-level differences, or headless rendering differences
  • parallel execution order
  • slower network, mocked services, or unavailable external dependencies

A good CI debug question is not “why is CI slower,” but “what assumption does the test make about the environment?”

Signs of environment drift

  • screenshot layout differs slightly, causing clicks to miss
  • animations or transitions behave differently in headless mode
  • fonts change line wrapping, moving buttons or labels
  • a cookie banner or modal appears only in one environment
  • test order affects shared state

For this class of problem, verify that local and CI are running the same browser channel, viewport, locale, timezone, and test data setup. If a test relies on real network services, isolate that dependency before blaming Playwright.

A useful CI safeguard is to make the environment explicit:

name: e2e
on: [push, pull_request]
jobs:
  playwright:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test

If failures only appear under parallel load, inspect whether shared test users, shared backend records, or shared browser context are colliding.

Race conditions, when two things happen in the wrong order

Race conditions are especially frustrating because the test can be technically correct and still fail. The app might be updating state asynchronously while the test is already moving on to the next step.

Typical race patterns:

  • clicking before a previous navigation finishes
  • asserting after a state update but before the final render
  • multiple requests updating the same UI region
  • overlapping API mocks or event listeners
  • debounced inputs where the test types and immediately checks results

How to identify them

Look for failures where the state is almost correct. The page is on the right route, but the expected content is missing. The button click happened, but the modal opened late. The list has the right items, but the order or count is transient.

In trace view, race conditions often show a step that succeeded immediately followed by an assertion on a stale snapshot. The browser did what you asked, just not yet in the final state.

How to stabilize them

Use the browser and app signals that represent completion:

  • expect(page).toHaveURL(...)
  • expect(locator).toBeVisible() or toBeHidden()
  • waitForResponse() for a specific API call
  • expect(locator).toHaveText(...) after a state change

Example:

typescript

await Promise.all([
  page.waitForResponse(resp => resp.url().includes('/api/profile') && resp.ok()),
  page.getByRole('button', { name: 'Save profile' }).click(),
]);
await expect(page.getByText('Profile updated')).toBeVisible();

This pattern reduces the chance that the test clicks and then races ahead before the request has even started.

Retry strategy, helpful safety net or masking layer?

Retries are not evil, but they are often overused. A retry can reduce noise while you investigate a known intermittent issue. It should not be the primary fix for a structural problem.

Good reasons to retry:

  • known external dependency instability
  • transient infrastructure issues in CI
  • infrequent browser launch failures
  • one-off network blips in non-mocked environments

Bad reasons to retry:

  • unstable locators
  • unmodeled timing dependencies
  • shared test data collisions
  • assertions that race the UI state

A practical approach is to use retries as a signal, not a solution. If a test passes on retry, ask what changed between attempts. Did the UI have more time, did the backend data settle, or did a transient overlay disappear? That answer tells you whether the test is brittle or the environment is noisy.

In Playwright, retries can help you gather evidence, but they should not become a substitute for a deterministic test contract.

A failure-signature workflow that scales

When a flaky test appears, use the same sequence every time:

1. Reproduce the exact failure mode

Do not immediately edit the test. Re-run the failing spec with trace collection and the same environment settings as CI.

2. Identify the earliest broken step

Find the first point where reality diverges from expectation. The root cause is often earlier than the line that throws.

3. Classify the failure

Ask whether it is primarily timing, selector drift, environment drift, or a race.

4. Validate the smallest fix

Change only one thing, for example a locator, a wait condition, or the test data setup. Avoid broad refactors during incident response.

5. Add a regression guard

If the bug came from a missing wait, add an assertion that would have caught it earlier. If it came from selector drift, move to a more stable locator strategy.

The best flakiness fixes do two things, they make the test more deterministic, and they make the failure easier to diagnose next time.

Practical locator and wait heuristics

If you want a quick rule set, use this:

  • Prefer role, label, and visible text locators over CSS structure.
  • Use data-testid when user-facing semantics are not stable enough.
  • Avoid arbitrary sleeps, except for very specific debugging or animation verification.
  • Prefer assertions that describe user-visible state, not internal DOM implementation.
  • If a test needs multiple retries to pass, treat that as a bug report, not a success.

For example, this is usually a better pattern than waiting on a raw selector:

typescript

const dialog = page.getByRole('dialog', { name: 'Invite teammate' });
await expect(dialog).toBeVisible();
await dialog.getByLabel('Email').fill('teammate@example.com');
await dialog.getByRole('button', { name: 'Send invite' }).click();

The locator reads like a user flow, and the assertions align with the page contract.

When the problem is not Playwright at all

Sometimes the failure is in the application, not the test. Playwright is just good at surfacing it.

Look upstream if you see:

  • nondeterministic backend data
  • feature flags changing behavior between runs
  • delayed websocket or polling updates
  • cached state leaking across tests
  • analytics or third-party scripts changing page timing

A good test suite should isolate as much of that as possible. Stable fixtures, isolated users, explicit teardown, and controlled mocks all reduce ambiguity.

If your suite still requires a lot of low-level debugging, it may be a sign that your team is spending too much effort maintaining the framework layer. In that case, a managed platform such as Endtest, an agentic AI [Test automation](https://en.wikipedia.org/wiki/Test_automation) platform, can be worth evaluating, especially if you want Playwright-compatible automation with less infrastructure and locator maintenance overhead. Its AI Test Creation Agent generates editable platform-native tests from plain-English scenarios, and its self-healing approach can reduce the amount of time spent chasing locator breakage. That tradeoff is not always right for code-first teams, but it is a reasonable alternative when the debugging burden starts to dominate the work.

A short decision tree for the next flaky failure

Use this when a test fails again and you need a fast triage path:

  • Fails before interaction: inspect page load, routing, and waiting conditions.
  • Fails on click or fill: inspect selector stability and actionability.
  • Fails on assertion after action: inspect asynchronous state updates and race conditions.
  • Fails only in CI: compare environment, browser version, viewport, and parallelism.
  • Fails after UI changes: inspect locator drift, accessible names, and element ordering.
  • Passes on retry: determine whether the retry masked a timing bug or an environmental dependency.

What to improve in your suite after the incident

Once the immediate failure is fixed, use the incident to harden the suite:

  • standardize on a locator convention
  • collect trace on failure in all CI jobs
  • isolate shared test data by test run
  • keep page objects or helper functions thin, so failures remain readable
  • remove obsolete waits and accidental dependency chains
  • prefer deterministic test fixtures over real-time data when possible

This is where teams often get long-term wins. Most flaky suites are not failing because one test is broken, but because the suite has developed a pattern of weak contracts.

Closing thoughts

Playwright flakiness is usually a diagnosis problem before it is a code problem. If you can identify the failure signature, you can usually tell whether the fix belongs in the locator, the wait strategy, the test data, or the environment. That is much more effective than scattering retries and hoping the noise goes away.

The most reliable suites are not the ones with the most sleeps or the highest retry count. They are the ones that express intent clearly, wait on the right signals, and keep the environment controlled enough that failures are meaningful.

If you want to stay code-first, Playwright remains a strong choice. If you want to reduce the amount of low-level debugging, a platform like Endtest can be a simpler operational model for some teams, especially when test authoring and maintenance need to be shared beyond developers.