How to Fix Flaky Playwright Tests for Good
The recurring causes of flaky Playwright tests—timing, shared state, animation, network and parallelism—and the concrete fix for each, plus how to stop new flake from entering the suite.
A retry hides flake; it does not remove it. Every automatic retry buys a green build today and costs trust in the suite tomorrow, because nobody can tell a real regression from noise. Flake in Playwright almost always comes from one of five sources, and each has a specific fix.
1. Waiting on time instead of state
Fixed sleeps encode an assumption about machine speed. CI is slower and more variable than a laptop, so the assumption breaks. Replace every sleep with a condition: wait for the element to be visible and enabled, for the response you depend on, or for the value you are about to assert.
// fragile
await page.waitForTimeout(2000);
await expect(page.getByRole('row')).toHaveCount(3);
// deterministic
await page.getByRole('button', { name: 'Save' }).click();
await expect(page.getByRole('row')).toHaveCount(3);2. Shared state between tests
Tests that reuse one account, one record, or one seeded database row pass alone and fail in parallel. Give each test its own data, created through the API in a fixture and torn down afterwards. Order-dependence is not a scheduling problem; it is a data-ownership problem.
3. Animation and layout shift
Clicks landing mid-transition produce the classic intermittent failure that nobody can reproduce locally. Disable animations in the test environment and assert on stable roles and accessible names rather than coordinates or CSS classes.
4. Uncontrolled network dependencies
A third-party widget, an analytics beacon, or a slow search index turns your product test into an availability test for someone else's service. Decide per test which calls are the subject and which are scenery, then route the scenery to a stub so its latency cannot fail your build.
5. Parallelism your environment cannot support
Workers competing for the same tenant, port, or file cause failures that move between tests. Make each worker's resources exclusive and keep the worker count within what the environment actually provides.
Stopping new flake from entering
- 01Run every new or changed test repeatedly in the pull request and reject anything that is not consistently green.
- 02Quarantine known-flaky tests out of the release gate with a named owner and a deadline, rather than retrying them silently.
- 03Track flake rate per test file so the worst offenders are visible instead of averaged away.
- 04Treat a fixed flake like a bug fix: reproduce it, fix the cause, and record which of the five sources it was.
A suite people trust is worth more than a suite that is large. When the pass rate becomes a signal again, teams start reading failures instead of re-running them.
Take the ten tests with the highest failure rate this month, classify each against the five causes above, and fix the cause rather than adding a retry.