Mocks, spies & fakes

Isolation, plainly

A good unit test should fail because your code changed, not because the network is slow, the clock crossed midnight, Math.random() picked a different branch, browser storage leaked from another test, or an analytics call reached the real service.

The previous Unit testing lesson focuses on runners, assertions, Arrange-Act-Assert, and test-driven development. Here we focus on the seams those tests use. You will reuse ideas from closures, higher-order functions, timers, fetch, web storage, and pure functions.

People often say “mock” for every replacement. In precise test language, a mock is only one member of a family. The names matter because they tell you whether the double supplies data, records calls, enforces expectations, or behaves like a small real system.

The table gives you a quick smell test. If the double is never inspected, it is probably a dummy. If it returns a fixed value, it is a stub. If you inspect calls afterward, it is a spy. If the test declares an expected call as the behavior, it is a mock. If it implements a smaller working system, it is a fake.

A spy answers “what happened?” A stub answers “what should happen next?” The tiny helpers below are real JavaScript functions, not a test-library shortcut. They make the mechanics clear before you reach for mock.fn, vi.fn, or jest.fn.

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

Line by line, the spy creates an array, calls the original function, pushes the arguments and return value, then returns the original result. The stub is intentionally simpler: it chooses a canned return value from a list. In a real test you would assert the visible result first, then use the call history only when the interaction is part of the behavior.

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

Timer code is hard to test if the test must really wait. A fake clock stores callbacks, keeps a fake now(), and runs due setTimeout callbacks when the test advances time. This section covers synchronous timer callbacks. The next lesson, Testing async code, adds promises, microtasks, rejections, and flaky async timing.

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) => clock.setTimeout(callback, 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(", "));

The helper has two seams. Calling clock.setTimeout avoids globals entirely. Calling clock.install() temporarily replaces setTimeout, clearTimeout, and Date.now on a target object and returns a restore function. Prefer the explicit clock object; install only around code that cannot accept one.

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) => clock.setTimeout(callback, 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(", "));

Dependency injection means passing the outside thing in: fetcher, now, random, a repository, or a storage object. It can be a function parameter, an options object, or a constructor argument. The code under test stays ordinary, and the test chooses safe replacements.

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

Notice that the fake network still returns a real browser Response. That keeps the consuming code honest: it must still call response.json(). The test controls the body without opening a socket. The same pattern works for Date.now and Math.random because both are just functions when you pass them in.

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 pseudo-random generator is useful when a test needs a stream of random-looking values. For one branch, injected random: () => 0.25 is clearer. For a property test or simulation, a seed lets you reproduce the exact failing sequence.

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 implements enough behavior to test through a boundary. An in-memory repository can save and find records. A fake localStorage can keep strings in a Map. A mock, in the narrow sense, makes exact calls the requirement. Both are useful, but they protect different things.

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

Prefer a fake when callers should not care how many lower-level methods were used. Prefer a mock when the interaction is the contract: “send exactly one welcome email” or “record this analytics event with these fields.” Over-mocking happens when a test asserts internal call order that users and callers cannot observe.

Module mocking is a stronger seam than dependency injection. It changes what an import resolves to, so it can help legacy code but also couples tests to file structure. ESM imports are live bindings and are evaluated before your test body, so test runners provide special APIs rather than plain assignment. Browser import maps choose module URLs up front; they are not a per-test mocking system.

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 Stability 1 APIs. mock.module is only available with --experimental-test-module-mocks, so treat it as a last resort and document 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(() => vi.useRealTimers());9 10test("Vitest doubles", () => {11  vi.useFakeTimers();12  const callback = vi.fn();13  setTimeout(callback, 100);14  vi.advanceTimersByTime(100);15  expect(callback).toHaveBeenCalledOnce();16});

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

Vitest and Jest examples are shown as tooling references only because this project does not install those runners. Their docs use the same pattern: create mock functions with vi.fn or jest.fn, spy on object methods, mock modules through the runner, use fake timers, then restore real timers after each test.

Common misconceptions

• “Mock everything outside the function.” Replace only the boundary that makes the test slow, flaky, unsafe, or nondeterministic. Too many mocks test wiring, not behavior.
• “A spy is harmless because it observes.” A spy can still make a test brittle if you assert internal calls instead of the public result.
• “Fake timers are only for async tests.” They are also useful for synchronous setTimeout callbacks. Promise timing adds microtasks, covered next.
• “Monkey-patching globals is the same as dependency injection.” Patching changes shared state and must be restored. Injection keeps the replacement local.
• “Fakes are less real than mocks.” A fake can be more behavior-focused than a mock because callers exercise it through the same public API.
• “Module mocks are always better seams.” They often depend on import order, runner transforms, and file paths. Passing a collaborator is usually simpler.

Key takeaways

• Test doubles isolate code from time, network, storage, randomness, and side effects.
• Dummies fill unused parameters; stubs answer; spies record; mocks expect; fakes work.
• Dependency injection is usually simpler and safer than monkey-patching globals or modules.
• Fake clocks make synchronous timer callbacks deterministic; promises need extra care next.
• Over-mocking makes tests brittle when they assert private implementation details.

Up next: Testing async code, where fake timers meet promises, rejections, and flaky scheduling.