Mocks, spies & fakes

Why tests use stand-ins

A unit test checks one small piece of your code. It should fail only when that code is wrong. But code often uses outside things that the test can't control:

• the network, which can be slow or down;
• the clock, which keeps moving;
• Math.random(), which gives a different number each time;
• browser storage, which can still hold data from an earlier test;
• outside services, like email or analytics, which should never get real messages from a test.

The Unit testing lesson showed how to write and run tests. This lesson shows how to swap the outside things those tests touch. It uses ideas from closures, higher-order functions, timers, fetch, web storage, and pure functions.

Each row of the table names one outside thing, says why it causes trouble in a test, and shows how a test can take control of it.

People often call every stand-in a "mock". But a mock is only one of five kinds. Each kind has its own job. The name tells you what the stand-in does in the test.

Read each row as: this kind of double does this job, for example like this.

To name a double, ask what the test does with it:

• The test never uses it: it is a dummy.
• It gives back a fixed answer: it is a stub.
• The test reads its call record afterward: it is a spy.
• The test fails if an expected call doesn't happen: it is a mock.
• It is a smaller working version of the real thing: it is a fake.

A spy answers the question "what happened?" A stub answers the question "what should happen next?" The small helpers below are plain JavaScript functions, not part of a test library. Once you know them, the library versions are easier to read: mock.fn in Node, vi.fn in Vitest, and jest.fn in Jest.

const calls = [];
const onSave = (todo) => calls.push(todo);
onSave("tea");
console.log(calls.join(","));

Line 1 makes an empty array, calls. Line 2 makes a callback that pushes each todo into it. Line 3 calls it with "tea", so line 4 prints tea. This is a tiny spy. A record like this helps when the code you test gives nothing back, so there is no return value to check.

1function spy(fn = () => undefined) {Run2  const calls = [];3  function wrapper(...args) {4    try {5      const returned = fn(...args);6      calls.push({ args, returned });7      return returned;8    } catch (error) {9      calls.push({ args, threw: error.message });10      throw error;11    }12  }13  wrapper.calls = calls;14  return wrapper;15}16 17function stub(...values) {18  let index = 0;19  return spy(() => values[Math.min(index++, values.length - 1)]);20}21 22const add = spy((a, b) => a + b);23console.log(add(2, 3));24console.log(JSON.stringify(add.calls));25 26const nextId = stub("id-1", "id-2");27console.log(nextId());28console.log(nextId());29console.log(JSON.stringify(nextId.calls.map((call) => call.returned)));

Step through the helpers above. The spy does four things:

1. It makes an empty calls array.
2. It calls the real function with the same arguments.
3. It pushes the arguments and the returned value into calls.
4. It gives back the real result, so the code works the same as before.

The stub is simpler. It keeps a list of planned answers and hands back the next one on each call. In a real test, check the visible result first. Check the call record only when the call itself is part of what the code must do.

1function spy(fn = () => undefined) {2  const calls = [];3  function wrapper(...args) {4    try {5      const returned = fn(...args);6      calls.push({ args, returned });7      return returned;8    } catch (error) {9      calls.push({ args, threw: error.message });10      throw error;11    }12  }13  wrapper.calls = calls;14  return wrapper;15}16 17function stub(...values) {18  let index = 0;19  return spy(() => values[Math.min(index++, values.length - 1)]);20}21 22const add = spy((a, b) => a + b);23console.log(add(2, 3));24console.log(JSON.stringify(add.calls));25 26const nextId = stub("id-1", "id-2");27console.log(nextId());28console.log(nextId());29console.log(JSON.stringify(nextId.calls.map((call) => call.returned)));

const calls = [];
function save(todo) {
  calls.push(todo);
  throw new Error("offline");
}
try {
  save("tea");
} catch (error) {
  console.log(error.message + "|" + calls.join(","));
}

Line 3 records the save before line 4 throws an error. The catch block prints offline|tea. So a call record proves the code tried, not that it worked. Check the saved data or the returned value too. The bigger spy helper above also records calls that throw.

Timer code is hard to test when the test must really wait. A fake clock is a stand-in for the real clock. It does three things:

• It stores each setTimeout callback instead of starting a real timer.
• It keeps its own time, which you read with now().
• It runs a callback only when the test moves time forward past that callback's due time.

This section uses only plain timer callbacks, with no promises. The next lesson, Testing async code, adds promises.

const events = [];
const timer = setTimeout(() => events.push("saved"), 10);
clearTimeout(timer);
console.log(events.length);

Line 2 schedules a save in 10 milliseconds and keeps the timer ID that setTimeout gives back. Line 3 cancels that timer at once, so line 4 prints 0. Apps cancel waiting work like this when a page closes or a search box changes. With a fake clock, a test can move time forward and prove the save never runs.

1function createFakeClock(start = 0) {Run2  let current = start;3  let nextId = 1;4  const timers = [];5  const sortTimers = () => timers.sort((a, b) => a.time - b.time || a.id - b.id);6 7  const clock = {8    now: () => current,9    setTimeout(callback, delay = 0) {10      const id = nextId++;11      timers.push({ id, time: current + Math.max(0, delay), callback });12      sortTimers();13      return id;14    },15    clearTimeout(id) {16      const index = timers.findIndex((timer) => timer.id === id);17      if (index >= 0) timers.splice(index, 1);18    },19    advance(ms) {20      const target = current + Math.max(0, ms);21      sortTimers();22      while (timers[0] && timers[0].time <= target) {23        const timer = timers.shift();24        current = timer.time;25        timer.callback();26        sortTimers();27      }28      current = target;29    },30    tick(ms) {31      clock.advance(ms);32    },33    install(target = globalThis) {34      const realSetTimeout = target.setTimeout;35      const realClearTimeout = target.clearTimeout;36      const realNow = target.Date?.now;37      target.setTimeout = (callback, delay = 0, ...args) => clock.setTimeout(() => callback(...args), delay);38      target.clearTimeout = (id) => clock.clearTimeout(id);39      if (target.Date && realNow) target.Date.now = clock.now;40      return () => {41        target.setTimeout = realSetTimeout;42        target.clearTimeout = realClearTimeout;43        if (target.Date && realNow) target.Date.now = realNow;44      };45    },46  };47  return clock;48}49 50const clock = createFakeClock(100);51const log = [];52clock.setTimeout(() => log.push("slow@" + clock.now()), 30);53clock.setTimeout(() => log.push("fast@" + clock.now()), 10);54clock.advance(10);55console.log(log.join(", "));56clock.tick(20);57console.log(log.join(", "));

A test can use the fake clock in two ways:

• Call clock.setTimeout directly. Nothing global changes.
• Call clock.install(). It puts a fake setTimeout, clearTimeout, and Date.now on a target object for a while. It gives back a restore function that puts the real ones back.

Prefer the first way. Install the clock only around code that can't take a clock as a value.

1function createFakeClock(start = 0) {2  let current = start;3  let nextId = 1;4  const timers = [];5  const sortTimers = () => timers.sort((a, b) => a.time - b.time || a.id - b.id);6 7  const clock = {8    now: () => current,9    setTimeout(callback, delay = 0) {10      const id = nextId++;11      timers.push({ id, time: current + Math.max(0, delay), callback });12      sortTimers();13      return id;14    },15    clearTimeout(id) {16      const index = timers.findIndex((timer) => timer.id === id);17      if (index >= 0) timers.splice(index, 1);18    },19    advance(ms) {20      const target = current + Math.max(0, ms);21      sortTimers();22      while (timers[0] && timers[0].time <= target) {23        const timer = timers.shift();24        current = timer.time;25        timer.callback();26        sortTimers();27      }28      current = target;29    },30    tick(ms) {31      clock.advance(ms);32    },33    install(target = globalThis) {34      const realSetTimeout = target.setTimeout;35      const realClearTimeout = target.clearTimeout;36      const realNow = target.Date?.now;37      target.setTimeout = (callback, delay = 0, ...args) => clock.setTimeout(() => callback(...args), delay);38      target.clearTimeout = (id) => clock.clearTimeout(id);39      if (target.Date && realNow) target.Date.now = clock.now;40      return () => {41        target.setTimeout = realSetTimeout;42        target.clearTimeout = realClearTimeout;43        if (target.Date && realNow) target.Date.now = realNow;44      };45    },46  };47  return clock;48}49 50const clock = createFakeClock(100);51const log = [];52clock.setTimeout(() => log.push("slow@" + clock.now()), 30);53clock.setTimeout(() => log.push("fast@" + clock.now()), 10);54clock.advance(10);55console.log(log.join(", "));56clock.tick(20);57console.log(log.join(", "));

const clock = createFakeClock(100);
const host = { setTimeout, clearTimeout, Date: { now: Date.now } };
const restore = clock.install(host);
try {
  host.setTimeout((todo) => console.log(todo + "@" + host.Date.now()), 10, "tea");
  clock.advance(10);
} finally {
  restore();
}
console.log(host.Date.now === Date.now);

Line 2 makes a host object that holds the real timer functions. Line 3 installs the fake clock on it. Line 5 passes "tea" as an extra argument, and the fake clock hands it to the callback. Line 6 moves time forward, so the callback prints tea@110.

The finally block runs even if a check throws an error. Line 8 inside it puts the real functions back, so line 10 prints true. This small clock handles only timer callbacks. It does not handle promises, setInterval, or every rule a browser follows for timers.

A dependency is something your code needs from outside, like fetch or Date.now. Dependency injection means the code gets that thing passed in, instead of reaching for it by itself. You can pass it in three ways:

• as a function parameter;
• as a property of an options object;
• as a constructor argument.

Your code stays ordinary. The real app passes the real thing, and a test passes a safe stand-in.

async function loadTodo(fetcher) {
  const response = await fetcher("/api/todo");
  return response.json();
}
loadTodo(async () => new Response('{"todo":"tea"}'))
  .then((data) => console.log(data.todo));

Line 1 takes a fetcher function as a parameter. Line 2 calls it to get the todo. Line 5 passes a stand-in that hands back a Response right away, with no network request. A Response is the object that fetch normally gives back. Line 3 reads its JSON body, so line 6 prints tea. The real app would pass the real fetch instead.

1async function loadGreeting(userId, {2  fetcher = fetch,3  now = Date.now,4  random = Math.random,5} = {}) {6  const response = await fetcher("/api/users/" + userId);7  const user = await response.json();8  const bucket = random() < 0.5 ? "A" : "B";9  return user.name + " @ " + now() + " #" + bucket;10}11 12const fakeFetch = async () =>13  new Response(JSON.stringify({ name: "Ada" }), {14    headers: { "content-type": "application/json" },15  });16 17loadGreeting(7, {18  fetcher: fakeFetch,19  now: () => 1000,20  random: () => 0.25,21}).then(console.log);

The fake fetcher still gives back a real browser Response. So the code must still call response.json(), just as it would with the real network. The test picks the body, and no request leaves the page. The same idea works for Date.now and Math.random. Both are just functions, so you can pass in your own.

async function loadTodo(fetcher) {
  const response = await fetcher("/api/todo");
  if (!response.ok) return "try again";
  return (await response.json()).todo;
}
const fakeFetch = async (url) => {
  console.log(url);
  return new Response("missing", { status: 404 });
};
loadTodo(fakeFetch).then(console.log);

Line 7 prints the address the code asked for, /api/todo. So the stand-in also shows which address was requested. Line 8 gives back a response with status 404, which means "not found". The promise does not fail. Line 3 sees that response.ok is false and returns try again.

So always check response.ok. The promise from fetch fails only for problems like a lost connection.

1function mulberry32(seed) {2  return function random() {3    seed |= 0;4    seed = (seed + 0x6D2B79F5) | 0;5    let value = Math.imul(seed ^ (seed >>> 15), 1 | seed);6    value = (value + Math.imul(value ^ (value >>> 7), 61 | value)) ^ value;7    return ((value ^ (value >>> 14)) >>> 0) / 4294967296;8  };9}10 11const random = mulberry32(123);12console.log(random().toFixed(3));13console.log(random().toFixed(3));

A seeded generator is a function that makes numbers that look random, starting from a number called the seed. The same seed always gives the same list of numbers. To test just one branch, passing random: () => 0.25 is clearer. When a test needs many random-looking numbers, a seed lets you replay the exact numbers that made a test fail.

Sometimes you can't change the code to take a value. Then a test can replace a global, like Math.random, for a short time. This is called monkey-patching. Every test shares that global, so always put the real one back.

1const realRandom = Math.random;2try {3  Math.random = () => 0.1;4  console.log(Math.random());5} finally {6  Math.random = realRandom;7}8console.log(Math.random === realRandom);

A fake is a small version of the real thing that really works. For example:

• an in-memory repository that can save and find records;
• a fake localStorage that keeps strings in a Map.

A mock, in the strict sense, makes the test fail unless certain calls happen. Both are useful, but they protect different things.

const data = new Map();
const storage = {
  getItem: (key) => data.get(key) ?? null,
  setItem: (key, value) => data.set(key, String(value)),
  removeItem: (key) => data.delete(key),
};
storage.setItem("theme", "dark");
storage.removeItem("theme");
console.log(storage.getItem("theme"));

Line 1 makes a Map to hold the data. Lines 3 to 5 give the fake the three storage methods the app uses. Line 7 saves the theme and line 8 removes it, so line 9 prints null. Make a fresh fake for each test. A shared Map can carry data from one test into the next, just like real storage.

1function createMemoryStorage() {2  const data = new Map();3  return {4    getItem: (key) => data.get(key) ?? null,5    setItem: (key, value) => data.set(key, String(value)),6    removeItem: (key) => data.delete(key),7  };8}9 10function saveTheme(storage, theme) {11  storage.setItem("theme", theme);12  return storage.getItem("theme");13}14 15const fakeStorage = createMemoryStorage();16console.log(saveTheme(fakeStorage, "dark"));17console.log(fakeStorage.getItem("theme"));

Use a fake when the caller shouldn't care which storage methods ran, or how many times. Use a mock when the call itself is the requirement, for example:

• "send exactly one welcome email";
• "record this analytics event with these fields".

A test is over-mocked when it checks calls that users and callers can't see, such as the order of private helper calls.

function showTodo(fetcher, track) {
  track("loaded");
  return "Loading...";
}
const calls = [];
const track = (event) => calls.push(event);
console.log(showTodo(() => ({ todo: "tea" }), track));
console.log(calls.includes("loaded"));

Line 2 records "loaded", but line 3 always returns Loading.... So line 7 prints Loading... and line 8 prints true. A test that checks only the call passes, even though the todo "tea" never shows. Check the shown todo, as well as any call the code must make.

Also keep one test that uses the real service. A fake with the wrong methods could let every small test pass while the real app fails.

A module mock changes what an import gives your code. The test runner does the swap, so you don't change the code itself. That helps with old code you can't change. But it ties the test to file names and to the order of imports.

A test can't do this swap with a plain assignment, for two reasons:

• An imported name is a live binding: a read-only link to a variable inside the module. Your test can't assign a new value to it.
• Imports run before the test body starts.

So test runners give you special functions for module mocks. Browser import maps don't help either. An import map picks module addresses once, when the page loads, not once per test.

Each row of the table lists one test runner, the functions it gives you for doubles, and what to watch out for.

const api = { send: () => "real" };
const original = api.send;
try {
  api.send = () => "fake";
  console.log(api.send());
} finally {
  api.send = original;
}
console.log(api.send === original);

Line 2 saves the real method. Line 4 puts in a stand-in, so line 5 prints fake. Line 7 is inside finally, so it always puts the real method back. Line 9 prints true.

In a test file, put this cleanup for timers and spies in afterEach, which runs after every test. Then a failing check can't leave a stand-in behind for the next test. Restoring spies does not undo a module mock. Each runner has its own way to reset modules.

1import assert from "node:assert/strict";2import { test } from "node:test";3 4test("mock.fn, mock.method, and mock.timers", (t) => {5  const send = t.mock.fn((value) => "sent:" + value);6  assert.equal(send("ok"), "sent:ok");7  console.log(send.mock.callCount());8  console.log(send.mock.calls[0].arguments.join(","));9 10  const api = { now: () => 0 };11  t.mock.method(api, "now", () => 42);12  console.log(api.now());13 14  t.mock.timers.enable({ apis: ["Date", "setTimeout"], now: 100 });15  const events = [];16  setTimeout(() => events.push("timer@" + Date.now()), 50);17  t.mock.timers.tick(50);18  console.log(events.join(","));19});

In Node 22.23.1, t.mock.fn and t.mock.method are stable parts of the test runner. MockTimers and mock.module are still marked Stability 1, which means experimental. mock.module only works with the --experimental-test-module-mocks flag. So use it as a last choice, and write the flag in your test command.

1import assert from "node:assert/strict";2import { test, mock } from "node:test";3 4test("mock.module replaces an ESM import", async () => {5  mock.module("node:readline", {6    namedExports: {7      createInterface: () => ({ question: () => "fake" }),8    },9  });10  const readline = await import("node:readline");11  assert.equal(readline.createInterface().question(), "fake");12  console.log(readline.createInterface().question());13});14 15// Run with: node --experimental-test-module-mocks --test module-mock.test.mjs

1import { afterEach, expect, test, vi } from "vitest";2import { loadUser } from "./load-user.js";3 4vi.mock("./api.js", () => ({5  fetchUser: vi.fn(() => ({ id: 7, name: "Ada" })),6}));7 8afterEach(() => {9  vi.useRealTimers();10  vi.restoreAllMocks();11});12 13test("Vitest doubles", () => {14  vi.useFakeTimers();15  const callback = vi.fn();16  setTimeout(callback, 100);17  vi.advanceTimersByTime(100);18  expect(callback).toHaveBeenCalledOnce();19});

1jest.mock("./api", () => ({2  fetchUser: jest.fn(() => ({ id: 7, name: "Ada" })),3}));4 5afterEach(() => {6  jest.useRealTimers();7  jest.restoreAllMocks();8});9 10test("Jest doubles", () => {11  jest.useFakeTimers();12  const callback = jest.fn();13  setTimeout(callback, 100);14  jest.advanceTimersByTime(100);15  expect(callback).toHaveBeenCalledTimes(1);16});

The Vitest and Jest examples are only for reading, because this project doesn't install those tools. Both tools follow the same steps:

• make mock functions with vi.fn or jest.fn;
• spy on object methods;
• mock modules through the runner;
• use fake timers;
• after each test, turn the real timers back on and restore every spy.

Common misconceptions

• "Mock everything outside the function." Replace only the outside thing that makes the test slow, unreliable, unsafe, or different on each run. With too many mocks, the test checks the wiring, not what the code does.
• "A spy is harmless because it only watches." A spy can still make a test break for no good reason, if you check private calls instead of the public result.
• "Fake timers are only for async tests." They also help with plain setTimeout callbacks. Promises add their own timing rules; the next lesson covers them.
• "Monkey-patching a global is the same as dependency injection." Patching changes something every test shares, so you must put it back. Injection keeps the stand-in inside one call.
• "Fakes are less real than mocks." A fake often tests more real behavior than a mock, because callers use it through the same methods as the real thing.
• "Module mocks are always the best way to swap things." They often depend on import order, the runner's settings, and file paths. Passing the stand-in in as a value is usually simpler.

Use this table to pick the simplest double. Find the question your test asks, then read which double to use and why.

Key takeaways

• Test doubles cut your code off from time, the network, storage, random numbers, and outside services.
• A dummy fills a parameter. A stub answers. A spy records. A mock expects a call. A fake really works.
• Passing the outside thing in (dependency injection) is usually simpler and safer than replacing globals or modules.
• A fake clock runs plain timer callbacks in due order, with no real waiting. Promises need extra care, in the next lesson.
• Over-mocked tests check private calls, so they break when you rearrange code that still works.

Up next: Testing async code, where fake timers meet promises, errors in promises, and tests that pass only some of the time.