Testing async code and killing flaky tests

Why async tests race: the unawaited assertion

The core failure is simple: if a test does not await the async work it asserts on, the assertion runs before the work finishes. The expectation evaluates against the old state — so it either passes for the wrong reason, fails intermittently, or the dangling promise leaks into the next test and corrupts it. Returning or awaiting the promise is the contract that tells the test runner “wait for this.”

// WRONG — fire-and-forget: the assertion runs before saveUser resolves
it('creates a user', () => {
  service.createUser(dto);          // promise dropped on the floor
  expect(repo.save).toHaveBeenCalled(); // races the await — passes/fails by luck
});

// RIGHT — await the work, then assert against settled state
it('creates a user', async () => {
  await service.createUser(dto);    // runner waits for this promise
  expect(repo.save).toHaveBeenCalledWith(dto);
});

Use the async/await form, not the legacy done callback, unless you genuinely need done for an event you can’t turn into a promise — and even then, call done(err) on failure or a thrown assertion hangs until the timeout. The rule is absolute: never fire-and-forget an async call in a test. Every promise you create, you await or return.

Fake timers: turning 30 seconds into zero

Real code uses setTimeout, setInterval, debounce, and retry-with-backoff. A test that lets those run on the real clock either waits real seconds or, worse, asserts before the timer fires. jest.useFakeTimers() swaps the global clock for one you drive. jest.advanceTimersByTimeAsync(ms) and jest.runAllTimersAsync() fast-forward time deterministically — a 30-second backoff is exercised in well under a millisecond.

// Service under test: retry with exponential backoff, capped at 3 attempts
async function callWithBackoff(fn: () => Promise<string>): Promise<string> {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (attempt >= 2) throw err;
      await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt)); // 1s, 2s
    }
  }
}

it('retries twice with backoff then succeeds', async () => {
  jest.useFakeTimers();
  const fn = jest
    .fn<Promise<string>, []>()
    .mockRejectedValueOnce(new Error('flap'))
    .mockRejectedValueOnce(new Error('flap'))
    .mockResolvedValueOnce('ok');

  const promise = callWithBackoff(fn);     // kicks off attempt 0, hits the 1s wait

  await jest.advanceTimersByTimeAsync(1000); // fast-forward the 1s backoff
  await jest.advanceTimersByTimeAsync(2000); // fast-forward the 2s backoff

  await expect(promise).resolves.toBe('ok');
  expect(fn).toHaveBeenCalledTimes(3);
});

The trap is mixing fake timers with real promises. The setTimeout is faked, but the await between attempts is a real microtask — advancing the timer fires the callback, but the awaited continuation only runs when the microtask queue drains. The *Async variants of the timer APIs flush microtasks for you between advances; the synchronous advanceTimersByTime does not, so the continuation never runs and the test hangs or asserts on a half-finished state. Use the async timer APIs whenever real promises sit between your timers.

Testing queues and events: await the handler, don’t sleep on it

@nestjs/event-emitter and BullMQ both run handlers asynchronously by design. A test that emits an event and immediately asserts races the listener — exactly the signup incident. There is a tempting, broken fix: await new Promise(r => setTimeout(r, 50)) before asserting, hoping the handler finished. On a fast machine it does; on a loaded CI box it doesn’t. That setTimeout(50) is the flakiness.

// FLAKY — emit then assert immediately races the async listener
emitter.emit('user.created', user);
expect(mailer.send).toHaveBeenCalled();   // listener may not have run yet

// FLAKY — the "fix" that just lowers the failure rate, never to zero
emitter.emit('user.created', user);
await new Promise((r) => setTimeout(r, 50)); // hope, not guarantee
expect(mailer.send).toHaveBeenCalled();

// DETERMINISTIC — call the consumer directly and await it
await listener.handleUserCreated(user);   // no event bus, no race
expect(mailer.send).toHaveBeenCalledWith(user.email);

// DETERMINISTIC — or await a signal the handler resolves
const done = new Promise((res) => emitter.once('email.sent', res));
emitter.emit('user.created', user);
await done;                                 // resolves only after the work
expect(mailer.send).toHaveBeenCalled();

For BullMQ, split the concern: in the unit test assert the job was enqueued (expect(queue.add).toHaveBeenCalledWith('send-email', payload)) and unit-test the processor’s process method directly with a fake Job. If you need the end-to-end path, run a real worker in the test and await its completed event — never poll with a timeout. The principle is one: replace “wait and hope” with a deterministic signal you actually await.

The flaky test as a bug report

A flaky test passes ~95% of runs. Treat that number as a defect severity, not a tolerance. The root causes are a short list:

1. Timing — setTimeout-based waits, real clock, real network latency. Fix: fake timers, awaited signals.
2. Shared mutable state — a module-level static, a real DB row, a singleton — combined with test-order dependence or parallel workers stepping on each other. Fix: reset state in beforeEach, isolate per-test data, don’t share a writable singleton.
3. Real IO and randomness — wall-clock time, Math.random(), network. Fix: inject and stub the clock/RNG, seed randomness, mock the boundary.
4. Unawaited async — a promise from test A settling during test B. Fix: await everything; fail the suite on unhandled rejections.

All four root causes share one structure: something races something else. Diagnose which pair is racing, apply the matching fix, and the flakiness disappears — not because you gave it more time, but because you removed the non-determinism entirely.

The anti-pattern that ties them together is reaching for jest.retryTimes(3) to “stabilize” the suite. It works in the narrow sense — CI goes green — and fails in every sense that matters: the race is still in prod, the signal is gone, and the next engineer trusts a suite that lies. The senior stance is that a flaky test is a defect report about non-determinism, in the test or the code, and the only correct response is to restore determinism. The numbers make the stakes concrete. A single 95%-pass test in a 1000-test suite makes the whole suite fail constantly — independent failures compound, so the suite’s green rate collapses well below any single test’s. And the human cost is worse than the CI cost: once a suite flakes, engineers learn to rerun red, and the day a real regression goes red, they rerun that too. Flakiness doesn’t just waste minutes; it trains the team to ignore the alarm.