Testing async code

Reliable tests wait for the right signal

Async code spreads work across promises, timers, events, streams, and the event loop. Testing it well is not about waiting longer. It is about giving the test runner the exact thing that proves the behavior is finished.

This lesson connects to promises, async/await, microtasks, the event loop, timers, promise errors, the concurrent mocks and fakes lesson, and cancellation.

The classic bug is small: a test starts async work, but does not return or await the promise that contains the assertion. The runner sees undefined, marks the test done, and the assertion happens later. Sometimes it becomes an unhandled rejection; sometimes a catch logs it; either way, the test result was not trustworthy.

1const output = [];Run2const log = (line) => { output.push(line); console.log(line); };3 4function assertEqual(actual, expected) {5  if (actual !== expected) throw new Error(`expected ${expected}, got ${actual}`);6}7async function test(name, body) {8  try {9    const result = body();10    if (result && typeof result.then === "function") await result;11    log(`PASS ${name}`);12  } catch (error) {13    log(`FAIL ${name}: ${error.message}`);14  }15}16const fetchStatus = () => Promise.resolve("saved");17 18test("forgot to await", () => {19  fetchStatus()20    .then((status) => assertEqual(status, "draft"))21    .catch((error) => log(`LATE ${error.message}`));22});23setTimeout(() => log(`SUMMARY ${output.join(" | ")}`), 0);

The tiny harness is intentionally simple: it calls the test body, checks whether the returned value looks like a promise, awaits it when present, then records pass or fail. Real runners such as node:test, Vitest, and Jest do the same kind of contract check around your test function.

1const output = [];2const log = (line) => { output.push(line); console.log(line); };3 4function assertEqual(actual, expected) {5  if (actual !== expected) throw new Error(`expected ${expected}, got ${actual}`);6}7async function test(name, body) {8  try {9    const result = body();10    if (result && typeof result.then === "function") await result;11    log(`PASS ${name}`);12  } catch (error) {13    log(`FAIL ${name}: ${error.message}`);14  }15}16const fetchStatus = () => Promise.resolve("saved");17 18test("forgot to await", () => {19  fetchStatus()20    .then((status) => assertEqual(status, "draft"))21    .catch((error) => log(`LATE ${error.message}`));22});23setTimeout(() => log(`SUMMARY ${output.join(" | ")}`), 0);

Assert resolved values directly: assert.equal(await loadName(), "Ada"), await expect(loadName()).resolves.toBe("Ada"), or the equivalent in your runner. The important part is that the assertion is inside the promise the runner is waiting for.

A rejected promise is not a synchronous throw. Use rejection assertions so the test fails when the promise unexpectedly resolves, and so the expected error message or type is checked.

1import test from "node:test";2import assert from "node:assert/strict";3 4async function saveInvoice() {5  throw new Error("offline");6}7 8test("saveInvoice rejects when storage is offline", async () => {9  await assert.rejects(saveInvoice(), /offline/);10});

TAP version 13
# Subtest: saveInvoice rejects when storage is offline
ok 1 - saveInvoice rejects when storage is offline
  ---
  duration_ms: <normalized>
  type: 'test'
  ...
1..1
# tests 1
# suites 0
# pass 1
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms <normalized>

1// Vitest2await expect(saveInvoice()).rejects.toThrow(/offline/);3 4// Jest5await expect(saveInvoice()).rejects.toThrow(/offline/);

1async function save(mode) {2  if (mode === "fail") throw new Error("offline");3  return "ok";4}5async function expectRejects(promise, pattern) {6  try {7    await promise;8    return "FAIL resolved instead of rejected";9  } catch (error) {10    return pattern.test(error.message)11      ? `PASS rejected with ${error.message}`12      : `FAIL wrong error: ${error.message}`;13  }14}15 16(async () => {17  console.log(await expectRejects(save("fail"), /offline/));18  console.log(await expectRejects(save("ok"), /offline/));19})();

Manual try/catch can work, but it is easy to catch the wrong thing. The common pitfall is placing assert.fail() or throw new Error("expected rejection") inside the try, then catching that failure and treating it as the expected rejection.

1async function shouldReject() {2  return "ok";3}4 5(async () => {6  try {7    await shouldReject();8    throw new Error("expected rejection");9  } catch (error) {10    console.log("caught " + error.message);11    console.log("A loose catch would treat this as a pass.");12  }13})();

Timer callbacks are tasks. Promise callbacks are microtasks. Advancing a fake clock can run a timer callback, but a Promise.then scheduled inside that callback still needs a microtask turn. If you assert too early, the code looks broken even though the promise is merely waiting in the next queue.

1const events = [];2class TinyClock {3  constructor() { this.now = 0; this.jobs = []; }4  setTimeout(callback, ms) { this.jobs.push({ at: this.now + ms, callback }); }5  advance(ms) {6    const end = this.now + ms;7    for (const job of this.jobs.filter((job) => job.at <= end)) {8      this.now = job.at;9      job.callback();10    }11    this.now = end;12  }13}14 15const clock = new TinyClock();16clock.setTimeout(() => {17  events.push("timer");18  Promise.resolve().then(() => events.push("promise"));19}, 10);20clock.advance(10);21console.log(events.join(" -> "));22Promise.resolve().then(() => console.log(events.join(" -> ")));

1class FakeClock {Run2  constructor() { this.now = 0; this.jobs = []; }3  delay(ms) {4    return new Promise((resolve) => {5      this.jobs.push({ at: this.now + ms, resolve });6    });7  }8  async advanceAsync(ms) {9    const target = this.now + ms;10    while (true) {11      this.jobs.sort((a, b) => a.at - b.at);12      const job = this.jobs[0];13      if (!job || job.at > target) break;14      this.jobs.shift();15      this.now = job.at;16      job.resolve();17      await Promise.resolve();18    }19    this.now = target;20    await Promise.resolve();21  }22}23async function retryWithBackoff(work, clock) {24  for (const wait of [100, 200]) {25    try { return await work(); }26    catch { await clock.delay(wait); }27  }28  return work();29}30 31(async () => {32  const events = [];33  const clock = new FakeClock();34  let attempts = 0;35  const work = async () => {36    attempts += 1;37    events.push(`try ${attempts} at ${clock.now}`);38    if (attempts < 3) throw new Error("offline");39    return "ok";40  };41 42  const result = retryWithBackoff(work, clock);43  await Promise.resolve();44  await clock.advanceAsync(100);45  await clock.advanceAsync(200);46  events.push(await result);47  console.log(events.join(" -> "));48})();

The lesson fake clock is a real function, not a drawing. delay(ms) returns a promise. advanceAsync(ms) finds due delays, resolves them, and awaits a microtask after each timer callback so promise continuations can schedule the next delay.

1class FakeClock {2  constructor() { this.now = 0; this.jobs = []; }3  delay(ms) {4    return new Promise((resolve) => {5      this.jobs.push({ at: this.now + ms, resolve });6    });7  }8  async advanceAsync(ms) {9    const target = this.now + ms;10    while (true) {11      this.jobs.sort((a, b) => a.at - b.at);12      const job = this.jobs[0];13      if (!job || job.at > target) break;14      this.jobs.shift();15      this.now = job.at;16      job.resolve();17      await Promise.resolve();18    }19    this.now = target;20    await Promise.resolve();21  }22}23async function retryWithBackoff(work, clock) {24  for (const wait of [100, 200]) {25    try { return await work(); }26    catch { await clock.delay(wait); }27  }28  return work();29}30 31(async () => {32  const events = [];33  const clock = new FakeClock();34  let attempts = 0;35  const work = async () => {36    attempts += 1;37    events.push(`try ${attempts} at ${clock.now}`);38    if (attempts < 3) throw new Error("offline");39    return "ok";40  };41 42  const result = retryWithBackoff(work, clock);43  await Promise.resolve();44  await clock.advanceAsync(100);45  await clock.advanceAsync(200);46  events.push(await result);47  console.log(events.join(" -> "));48})();

1import { mock, test } from "node:test";2import assert from "node:assert/strict";3 4test("timer callback runs on the fake clock", () => {5  mock.timers.enable({6    apis: ["setTimeout", "Date"],7    now: new Date("2026-01-01T00:00:00Z"),8  });9 10  const seen = [];11  setTimeout(() => seen.push(Date.now()), 50);12 13  mock.timers.tick(50);14  assert.deepEqual(seen, [1767225600050]);15 16  mock.timers.reset();17});

Node 22.23.1 exposes mock.timers.enable, mock.timers.tick, mock.timers.runAll, and mock.timers.reset. Passing { apis: ["setTimeout", "Date"], now } mocks both timers and Date; if you list only setTimeout, Date.now() stays real.

1// Vitest2vi.useFakeTimers();3const promise = retryWithBackoff(work);4await vi.advanceTimersByTimeAsync(300);5await expect(promise).resolves.toBe("ok");6 7// Jest8jest.useFakeTimers();9const result = retryWithBackoff(work);10await jest.advanceTimersByTimeAsync(300);11await expect(result).resolves.toBe("ok");

Events are easy to miss if you attach the listener after triggering the behavior. Start the wait first, trigger the action second, and give the wait a deadline so a missing event fails quickly.

1const target = new EventTarget();2function waitForEvent(target, type, { signal } = {}) {3  return new Promise((resolve, reject) => {4    const cleanup = () => signal?.removeEventListener("abort", onAbort);5    const onEvent = (event) => { cleanup(); resolve(event); };6    const onAbort = () => {7      target.removeEventListener(type, onEvent);8      reject(signal.reason ?? new Error("aborted"));9    };10    target.addEventListener(type, onEvent, { once: true });11    signal?.addEventListener("abort", onAbort, { once: true });12  });13}14 15const saved = waitForEvent(target, "saved", {16  signal: AbortSignal.timeout(50),17});18target.dispatchEvent(new CustomEvent("saved", { detail: { id: 7 } }));19saved.then((event) => console.log(event.detail.id));

Node's events.once gives EventEmitter and stream tests the same promise shape. Streams often finish with end, finish, close, or error; choose the event that represents the behavior your test promises.

1import { EventEmitter, once } from "node:events";2 3const emitter = new EventEmitter();4const saved = once(emitter, "saved", {5  signal: AbortSignal.timeout(50),6});7 8emitter.emit("saved", { id: 7 });9const [payload] = await saved;10console.log(payload.id);

1import test from "node:test";2 3test("polls until ready", { timeout: 100 }, async () => {4  await waitForReadyState();5});

AbortSignal.timeout(50) is useful in examples and wrappers because it cancels the wait itself. Runner timeouts, such as test(name, { timeout: 100 }, async () => ...), protect the whole test from hanging forever.

Flaky async tests usually have one of a few causes: real timers or sleeps, shared state between tests, order dependence, real network calls, time zones and dates, randomness, or race conditions. The fix is to make the signal deterministic before you reach for retries.

Common misconceptions

• “The test is marked async, so everything inside counts.” Only awaited work or a returned promise belongs to the runner's contract.
• “A sleep proves the UI or stream is done.” A sleep proves only that time passed. Wait for the visible result, event, or completion signal.
• “Fake timers run promise callbacks too.” Timer callbacks and promise callbacks are separate queues. Use async timer helpers or flush microtasks.
• “Any caught error means the rejection happened.” A broad catch can catch your own assertion failure. Use rejection-specific assertions.
• “Retries fix flakes.” Retries hide symptoms. Deterministic seams fix the test.

Key takeaways

• Async tests pass only after the runner waits for the promise, event, timer, or stream that contains the assertion.
• Use async tests, returned promises, or carefully wired legacy done callbacks; never start async work and return undefined.
• Use assert.rejects or expect(...).rejects for promise errors, and treat unhandled rejections as escaped work.
• Fake timers and promises need microtask flushing; prefer async timer helpers or an injected clock with advanceAsync.
• Fix flaky tests by removing guesses: fake time, isolate state, control external inputs, and await the right signal.

Up next: Testing the DOM & end to end.