A flaky test sometimes passes and sometimes fails without a relevant code change. In a multi-process application, timing, shared data, caches, queues, and external services can all cause instability. Flaky tests waste engineering time and teach teams to ignore failures, making genuine regressions harder to notice. The goal is not to retry every test until it turns green. It is to find the uncertainty and make the test's environment and assertions deterministic enough to trust.
Identify the failure pattern
Record which test fails, how often, under which process load, and whether order or parallel execution matters. Preserve logs, seed values, and correlation identifiers from failed runs. A test that fails only in CI may depend on a faster local machine or an unavailable external service. A failure after another test may indicate shared database state. Repeat the failing test in isolation and with its neighboring tests to narrow the cause. Do not label a real race in production code as “just a flaky test” without investigating it.
Replace fixed sleeps
A fixed delay assumes a job or service will be ready after a chosen number of milliseconds. That assumption changes under load. Wait for a meaningful condition with a bounded timeout: a health check becomes ready, a job reaches completed state, or a record appears. Report the last observed state on timeout so the failure is actionable. Avoid unbounded polling that hides a hung process. In Qwik or React UI tests, wait for the user-visible state rather than an internal implementation detail. A condition-based wait makes the test faster when the system is fast and clearer when it is slow.
Isolate data and resources
Use unique tenant and item fixtures through centralized ID utilities, or reset an isolated database between tests. Do not let two tests modify the same shared record unless concurrency is the behavior under test. Clean up jobs and files, and ensure background workers do not continue altering data after a test ends. If tests run in parallel, derive worker count from available CPU resources rather than hardcoding a magic number. Parallelism can be valuable, but it should not turn shared state into a hidden dependency. Separate external integration tests from fast local checks where possible.
Control time and dependencies
Date boundaries, time zones, token expiration, and random values can make tests inconsistent. Inject or freeze a clock where the architecture permits it and use explicit time zones in fixtures. Mock an external provider at its boundary for focused tests, then run a smaller integration check against a real sandbox when needed. Do not mock the business logic the test is meant to verify. Give retries a known policy and assert the final outcome rather than the exact millisecond timing of each attempt. These choices make failures point to behavior, not the test harness.
Improve the composed environment
A multi-repository product should start from known revisions and configuration. Check readiness before tests begin, and capture which bundles and processes were loaded. A stale generated export can look like a random test failure if the build cache changes between runs. Keep test commands repeatable and report missing dependencies clearly. When a test passes only after a manual cleanup step, automate that setup or teardown. A reliable environment is part of the product's developer experience, not a luxury.
Make failure meaningful again
Quarantine a flaky test only with an owner and a plan to fix it, especially if it covers a critical rule. Track recurrence and review whether the cause is test code or a real service race. Remove redundant tests that provide no distinct evidence. For SMB teams, a compact trusted suite helps releases more than a large unstable one. The goal is a green result that means something and a red result that directs the team to a specific problem. After a fix, rerun the test in the conditions that previously failed and record the evidence. A test that passes once locally is not proof that an intermittent failure is gone. Keep the diagnostic data focused so the team can tell whether the same failure returns.