Testing async code

A good async test waits for the work to finish

Async code is code that finishes later. It uses promises, timers, events, or streams. A test for it has one job: wait until that work is done, then check the result.

Two words come up all the time in this lesson:

• A test runner is the tool that runs your tests and reports PASS or FAIL. Examples are node:test, Vitest, and Jest.
• An assertion is a check, like "the cart has 3 items". If the check is wrong, it throws an error, and the test fails.

Waiting longer does not make an async test good. The test must give the runner the exact thing that says "the work is done". Most often, that thing is a promise.

The table shows four ways to write a test body. Read each row across to see whether the runner waits.

This lesson builds on promises, async/await, microtasks, the event loop, timers, promise errors, the mocks and fakes lesson, and cancellation.

Here is the most common async test bug, step by step:

1. The test starts some async work. The check sits inside that work.
2. The test does not return the promise, and does not await it.
3. So the runner gets undefined back. To the runner, that means "nothing to wait for".
4. The runner marks the test as passed. The check runs later, after the result is already written.

This is called a false pass. If the late check fails, its error may show up on its own, or a catch may only log it. Either way, the PASS was not real.

const loadCart = () => Promise.resolve(3);
const testCart = () => loadCart().then((items) => {
  if (items !== 3) throw new Error("wrong cart");
  console.log("cart has 3 items");
});
testCart();

loadCart() gives back a promise of 3. testCart returns the chain made by .then(...), and the check sits inside that chain. A runner that gets testCart as the test body waits for that chain. The cart has 3 items, so it prints cart has 3 items.

In a real runner, pass testCart itself as the test body. Don't call it yourself first.

const loadCart = () => Promise.resolve(3);
async function testCart() {
  loadCart().then((items) => console.log("late: " + items));
  console.log("test body done");
}
testCart();

Line 3 starts a promise, but does not await it or return it. Line 4 prints test body done first. Only after that does the .then callback print late: 3.

The async function does give back a promise. But that promise does not include the cart check, so a runner would not wait for the check.

The step-through below uses a tiny test runner, called a harness. It does four things:

1. It calls the test body.
2. It checks whether the body gave back a promise (something with a .then method).
3. If so, it awaits that promise.
4. Then it logs PASS, or FAIL with the error message.

Real runners such as node:test, Vitest, and Jest do the same check around your test function.

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);

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);

The value a promise gives when it succeeds is its resolved value. Check it directly, for example with assert.equal(await loadName(), "Ada") or await expect(loadName()).resolves.toBe("Ada"). What matters is that the check sits inside the promise the runner waits for.

A promise that fails is called rejected. A rejection is not the same as a normal throw. It happens later, inside the promise. So you need checks made for promises. A good rejection check does two things:

• It fails the test if the promise succeeds instead.
• It checks that the error is the one you expected, by its message or its type.

const saveCart = () => Promise.reject(new Error("offline"));
saveCart().catch((error) => {
  console.log(error.message === "offline" ? "expected: offline" : "wrong error");
});

saveCart rejects with an error whose message is offline. The .catch callback checks the message and prints expected: offline.

This is only a demo, not a full test. If the promise succeeded, the callback would never run, and nothing would fail. A real test needs a check that fails when the promise succeeds.

const saveCart = () => Promise.reject(new Error("permission denied"));
saveCart().catch(() => console.log("caught something"));

Now saveCart rejects with permission denied. The .catch callback ignores the error and still prints caught something. A good rejection check asks two questions: did the promise reject, and was it the right error?

The table shows three ways to check a rejection. The last column says what each one protects you from.

Here is a full Node test. Line 9 awaits assert.rejects. It waits for the promise, fails if the promise succeeds, and checks the message against /offline/. That is a pattern that matches any message containing the word offline.

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});

Below is the real output from running that file with node --test. It uses TAP, a plain text format for test results. ok 1 and # pass 1 mean the test passed. The times show <normalized> because they change on every run.

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>

Vitest and Jest write the check the same way. Put await in front of expect. Without it, the test can end before the check runs.

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})();

You can also write the check by hand with try/catch, but it is easy to get wrong. Here is the common mistake:

1. Inside the try, you put assert.fail() or throw new Error("expected rejection"), to fail the test if the promise succeeds.
2. The promise succeeds, so that line throws.
3. The catch catches that very error and treats 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})();

shouldReject succeeds, so line 8 throws expected rejection to fail the test. But the catch on line 9 catches that error. Line 10 prints caught expected rejection, and a loose test would call that a pass.

A fake timer, or fake clock, replaces the real clock in a test. The test does not wait 200 real milliseconds. It says "move time forward 200ms", and every timer due by then runs at once.

But JavaScript keeps two separate waiting lines here:

• Timer callbacks wait in the task queue. Moving a fake clock forward runs them.
• Promise callbacks (.then callbacks, and code after await) wait in the microtask queue. They run only after the current callback finishes.

The moment JavaScript runs the waiting promise callbacks is called a microtask turn. A timer callback can schedule a promise callback that has not run yet. If you check too early, the code looks broken. It isn't; the promise callback is only waiting for its turn.

const events = [];
function timerFired() {
  events.push("timer");
  Promise.resolve().then(() => events.push("promise"));
}
timerFired();
console.log(events.join(" -> "));
queueMicrotask(() => console.log(events.join(" -> ")));

timerFired stands in for a callback that a fake clock runs. Line by line:

1. Line 3 adds timer to the events list right away.
2. Line 4 schedules a promise callback that will add promise later.
3. The first log, on line 7, prints timer.
4. Line 8 uses queueMicrotask(fn), which puts fn in the microtask queue behind the promise callback. So the second log prints timer -> promise.

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(" -> ")));

Next, a fake clock tests real-looking code: retryWithBackoff. It tries some work. If the work fails, it waits 100ms and tries again. If that fails too, it waits 200ms and tries a third time. Waiting longer after each failure is called backoff.

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 fake clock in this lesson is a small teaching model, not a full timer library. It has two parts:

• delay(ms) gives back a promise. It resolves when fake time reaches that point.
• advanceAsync(ms) moves fake time forward. After each timer that is due, it awaits one microtask turn, so promise callbacks can run.

That is enough for this retry example. Longer promise chains may need more turns. For real test suites, use your runner's async timer helpers.

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})();

Debounce means: wait until calls stop for a while, then run only the last one. A search box uses it so it doesn't search on every key press. To test it, check both sides of its deadline, and check that the older call was cancelled.

let now = 0;
let jobs = [];
const clock = {
  set(callback, ms) { const job = { at: now + ms, callback }; jobs.push(job); return job; },
  clear(job) { jobs = jobs.filter((item) => item !== job); },
  advance(ms) { now += ms; const due = jobs.filter((job) => job.at <= now); jobs = jobs.filter((job) => job.at > now); due.forEach((job) => job.callback()); },
};
let pending;
function search(term) {
  clock.clear(pending);
  pending = clock.set(() => console.log("search " + term), 200);
}
search("t"); search("tea");
clock.advance(199);
console.log("before deadline");
clock.advance(1);

Line 13 calls search("t"), then search("tea"). The second call cancels the job for t. At 199ms, line 15 prints before deadline; the search has not run yet. At 200ms, line 16 runs the job, which prints search tea once.

There is no real waiting and no retry. In a real test, reset the fake clock after each test.

The table lists the timer tools you are likely to meet. The last column is the detail people most often miss.

Node 22 has four functions for fake timers:

• mock.timers.enable turns fake timers on.
• mock.timers.tick(ms) moves fake time forward.
• mock.timers.runAll() runs every waiting timer.
• mock.timers.reset() turns fake timers off again.

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});

Line 6 lists what to fake: setTimeout and Date. If you list only setTimeout, Date.now() keeps reading the real clock. Line 13 moves time 50ms, so the timer runs and records 1767225600050: the start time from line 7, plus 50.

Vitest and Jest use the same name: advanceTimersByTimeAsync. It moves fake time and lets promise callbacks run in between. Always await it.

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");

An event is a signal, like a click. A listener only hears events that happen after it starts listening. So an event test follows three steps:

1. Start listening first.
2. Make the event happen second.
3. Give the wait a deadline, so a missing event fails fast instead of hanging.

const button = new EventTarget();
const clicked = new Promise((resolve) => {
  button.addEventListener("click", () => resolve("clicked"), { once: true });
});
button.dispatchEvent(new Event("click"));
clicked.then((value) => console.log(value));

button is an EventTarget: a plain object that can send and hear events. Line 3 adds the listener. { once: true } removes it after the first event. Line 5 sends the click with dispatchEvent. The promise resolves, so line 6 prints clicked.

If you send the click before adding the listener, nobody hears it. The promise then waits forever.

The longer example below wraps this in a helper called waitForEvent. It adds a deadline with an abort signal, an object that can say "stop now". AbortSignal.timeout(50) makes a signal that fires after 50ms.

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

Two details keep the helper safe:

• If the signal has already fired when the wait starts, line 4 rejects at once.
• If the signal fires later, line 8 removes the event listener too, so no listener is left behind.

In the browser, an EventTarget has addEventListener. In Node, many objects use EventEmitter instead. Node's events.once gives you the same kind of promise for an EventEmitter.

A stream sends data in pieces. Node streams are event emitters, and they usually end with one of these events: end, finish, close, or error. Wait for the one that matches what your test checks.

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) stops one wait. A runner timeout, such as test(name, { timeout: 100 }, async () => ...), fails the whole test if it takes longer than 100ms. Both are deadlines: they say when to give up. A sleep is different. It guesses when the work will be done.

A flaky test passes sometimes and fails other times, with no change to the code. Flaky async tests usually come from one of these causes:

• real timers, or sleeps that guess how long to wait;
• data shared between tests;
• tests that only pass when they run in a certain order;
• real network calls;
• time zones and dates;
• random values;
• race conditions, where two things finish in an order you can't predict.

Fix the cause, so the test gets the same result on every run. Reach for retries only after that.

const screen = { text: "Saving..." };
const saved = Promise.resolve().then(() => { screen.text = "Saved"; });
console.log(screen.text);
(async () => {
  await saved;
  console.log(screen.text);
})();

Line 3 prints Saving.... Line 5 awaits the save promise, whose callback updates the screen. So line 6 prints Saved.

In a real screen test, wait for what the user sees, with a query like screen.findByText("Saved"). Don't guess a delay.

Each row of the table is one cause of flaky tests. Read across: what you notice, then the first fix to try.

Common misconceptions

• “The test is marked async, so everything inside counts.” Only work you await, or a promise you return, is part of what the runner waits for.
• “A sleep proves the screen or stream is done.” A sleep only proves that time passed. Wait for the visible result, the event, or the end signal.
• “Fake timers run promise callbacks too.” Timer callbacks and promise callbacks wait in separate queues. Use the async timer helpers, or await a microtask turn.
• “Any caught error means the rejection happened.” A loose catch can catch your own failing check. Use a rejection check, like assert.rejects.
• “Retries fix flaky tests.” Retries only hide the problem. Removing the guess fixes the test.

These four tools are easy to mix up. Each row says what the tool is for, and how it is often misused.

Key takeaways

• An async test is only trustworthy if the runner waits for the promise, event, timer, or stream that holds the check.
• Use async tests or returned promises. In older suites, call done carefully. Never start async work and give back undefined.
• Check rejected promises with assert.rejects or expect(...).rejects. An unhandled rejection means some work got away from the test.
• Fake timers don't run promise callbacks by themselves. Use the async timer helpers, or a clock with advanceAsync.
• Fix flaky tests by removing guesses: fake the time, keep data separate, control outside inputs, and await the right signal.

Up next: Testing the DOM & end to end.