Skip to content
Velloreth
Programming 6 min read

Fixing Flaky Tests: Causes and Cures

A flaky test passes and fails without code changes. Learn the common causes, how to find them, and how to fix them properly.

By

What flakiness is

A flaky test produces different results on the same code. It passes sometimes and fails other times, with no change to the source.

The cause is always non-determinism: something in the test or its environment varies between runs.

Flakiness is corrosive. Once a suite has flaky tests, developers learn to re-run failures instead of investigating them. Real failures get ignored, and the suite stops providing value.

The common causes

Timing

The most common cause. The test assumes something has happened by the time it checks.

// Flaky: the request may not have completed
test('shows the user name', () => {
  renderProfile();
  expect(screen.getByText('Ada')).toBeInTheDocument();
});

The render is asynchronous. On a fast machine it completes before the assertion; on a slow one it does not.

The fix: wait for the condition explicitly.

test('shows the user name', async () => {
  renderProfile();
  expect(await screen.findByText('Ada')).toBeInTheDocument();
});

findByText polls until the element appears or a timeout expires. It is deterministic in the sense that it waits for the right condition rather than guessing a duration.

Sleeps

A sleep is a guess about how long something takes.

// Flaky and slow
await sleep(500);
expect(result).toBe('done');

On a fast machine, 500ms is plenty. On a loaded CI runner, it may not be. And on every run, you pay 500ms even when the work takes 5ms.

The fix: wait for the condition, not a duration.

await waitFor(() => expect(result).toBe('done'));

Shared state

Tests that share mutable state depend on execution order.

let counter = 0;

test('increments', () => {
  counter++;
  expect(counter).toBe(1); // fails if another test ran first
});

The fix: reset state in a beforeEach, or make each test create its own state.

let counter: number;

beforeEach(() => {
  counter = 0;
});

Order dependence

A test passes alone but fails in the suite, or vice versa. This is usually shared state, but it can also be a global registration, a cached module, or a database row left behind.

The fix: find the shared resource and isolate it. Run the suite in a random order to surface these.

External services

A test that calls a real API depends on that API’s availability, latency, and data.

// Flaky: depends on a third party
const response = await fetch('https://api.example.com/users/1');
expect(response.status).toBe(200);

The fix: mock the boundary, or use a recorded fixture. External services should not be in the unit test path.

Time and dates

// Flaky: fails at midnight, or on the last day of the month
expect(formatRelative(new Date())).toBe('today');

The fix: inject the clock.

const clock = { now: () => new Date('2026-06-15T12:00:00Z') };
expect(formatRelative(clock.now(), clock)).toBe('today');

Randomness

// Flaky: fails when the random value is 0
const id = generateId();
expect(id.length).toBe(10);

The fix: seed the random generator, or inject it.

Concurrency

Tests that run in parallel and share a resource — a port, a database, a temp file — interfere with each other.

The fix: give each test its own resource. Use a random port, a unique schema, or a temp directory per test.

Resource limits

A test that needs more memory or file handles than the CI runner provides fails intermittently.

The fix: reduce the resource usage, or increase the limit. This is often a sign the test is doing too much.

Finding the cause

1. Confirm the flake. Run the test in a loop.

for i in $(seq 1 50); do npm test -- mytest || echo "FAILED on run $i"; done

If it fails once in fifty, you have a flake. If it never fails, the flake may depend on the full suite.

2. Run it in isolation.

npm test -- mytest

If it passes alone but fails in the suite, the cause is shared state or order dependence.

3. Run the suite in a random order. Many runners support this. It surfaces order dependence quickly.

4. Run it in parallel. If it fails only when parallel, the cause is a shared resource.

5. Add logging. Log the values that vary — timestamps, ids, counts — and compare a passing run with a failing one.

What not to do

Do not add a retry. A retry hides the cause and makes the suite slower. It is acceptable as a temporary measure while you investigate, but it should be tracked and removed.

Do not add a sleep. It makes the test slower and still does not guarantee the condition. It also fails on slower machines.

Do not increase the timeout without understanding why. A longer timeout may mask a genuine performance regression.

Do not delete the test. Deleting a flaky test removes the coverage it provided. Fix it, or quarantine it with a ticket.

Do not mark it as skipped and forget. A skipped test is a test that will never run again.

Quarantine

When a flaky test cannot be fixed immediately, quarantine it.

Move it to a separate suite that runs but does not block the pipeline.

Create a ticket with the failure output and the investigation so far.

Set a deadline. A quarantined test that is never fixed is a deleted test with extra steps.

Review the quarantine list regularly. It should be short and shrinking.

Preventing flakiness

Wait for conditions, not durations. Use findBy, waitFor, or an explicit poll.

Isolate state. Reset in beforeEach, and give each test its own resources.

Inject time and randomness. Never read the clock or a random source directly in testable code.

Mock external services. Keep them out of the unit test path.

Run tests in random order in CI, so order dependence is caught early.

Run tests in parallel in CI, so shared resources are caught early.

Keep tests fast. Slow tests are more likely to hit timeouts.

Review failures, do not re-run them. A culture of re-running normalises flakiness.

Practical guidance

  • Treat flakiness as a bug in the test, not an inconvenience.
  • Reproduce it in a loop before trying to fix it.
  • Run in isolation and in random order to narrow the cause.
  • Wait for conditions, never for durations.
  • Inject time and randomness.
  • Isolate shared state in beforeEach.
  • Never fix flakiness with a retry or a sleep.
  • Quarantine with a ticket if you cannot fix it now, and set a deadline.

For the related practices, see unit testing basics and why your tests are slow. For the broader context, integration vs unit tests and regression testing guide.

Quotable summary

A flaky test produces different results on the same code, which destroys trust in the whole suite, because developers learn to re-run failures instead of investigating them. The most common causes are timing, shared state, order dependence, and dependence on external services, along with unseeded randomness and un-injected clocks. Never fix flakiness with a retry or a sleep: both hide the cause, and a sleep also makes the test slower and still fails on slower machines. Reproduce the flake by running the test in a loop, then in isolation, then in a different order, to narrow the cause. A flaky test that cannot be fixed immediately should be quarantined with a ticket and a deadline, not left failing in the main suite or silently skipped.

Frequently asked questions

What is a flaky test?
A flaky test produces different results on the same code, passing sometimes and failing other times. The cause is usually timing, shared state, order dependence, or an external dependency.
Why are flaky tests a problem?
Because they destroy trust in the test suite. When a failure might be a flake, developers re-run instead of investigating, and real failures get ignored. Flakiness also slows down delivery, since pipelines fail randomly.
How do I find the cause of a flaky test?
Run it in a loop to confirm the flake, then run it in isolation and in a different order. If it passes alone but fails in the suite, the cause is shared state or order dependence. If it fails alone, the cause is timing or an external dependency.
Is adding a retry a good fix for flakiness?
No. A retry hides the cause and makes the suite slower. It is acceptable as a temporary measure while you investigate, but the underlying problem should be fixed.
Why is sleep a bad fix for flaky tests?
Because it makes the test slower and still does not guarantee the condition is met. A sleep of 500ms may pass on a fast machine and fail on a slow one. Wait for the condition explicitly instead.
What is test quarantine?
Quarantine moves a flaky test out of the main suite into a separate, non-blocking run, so it stops breaking the pipeline while it is investigated. It should be tracked with a ticket and fixed, not forgotten.