# Why tests go flaky

## Order dependence and shared state

**Tell:** passes alone, fails in the suite, or fails only in a particular order.

Shared module state, a database not rolled back, a global registry, a cached singleton,
a file left behind, an environment variable set by another test.

**Fix:** make each test set up and tear down its own state. Randomize test order
permanently so this cannot silently return.

## Time

**Tell:** fails near midnight, at month boundaries, in a particular time zone, or on a
fast machine.

Tests that assert on `now`, assume a day is 24 hours, compare wall-clock durations, or
depend on daylight saving.

**Fix:** inject the clock. Never call the system clock from code under test. Use a fixed
instant in tests, and include an awkward one such as a leap day or a DST boundary.

## Concurrency

**Tell:** fails more under parallelism or on machines with more cores.

Real races: unsynchronized shared access, an assertion made before the work completes,
a callback that has not fired yet.

**Fix:** await the condition rather than a duration. If the race is in the product code
rather than the test, you have found a bug. Do not fix it in the test.

## Randomness

**Tell:** fails at a stable low rate with no environmental pattern.

Unseeded generators, random data that occasionally violates an assumption, hash
iteration order.

**Fix:** seed deterministically, and log the seed on every run. When a property-based
test finds a failing case, add that case as a permanent example test.

## Resource contention

**Tell:** fails only in CI, or only when several jobs run together.

Hardcoded ports, a shared temp path, a shared database, a fixed filename.

**Fix:** allocate dynamically. Port zero, a temp directory per test, a schema per worker.

## External dependencies

**Tell:** failures correlate with network conditions or another team's deploys.

A real HTTP call, a real DNS lookup, a shared staging environment, a rate limit.

**Fix:** stub at the boundary. Keep a small number of genuine integration tests, run
them separately, and never let them gate a unit test suite.

## A real bug

**Tell:** the failure is a legitimate assertion failure that only occurs under a
specific interleaving or input.

**Fix:** fix the product. This is the case where the flaky test was doing its job, and
the retry annotation would have hidden a defect that will eventually reach production.