Test doubles: stubs, spies, mocks and fakes in Vitest

A test double stands in for something the code under test talks to, so the test controls it or can see what happened to it. Here's code with three collaborators:

async function checkout(order: Order, { rates, orders, mailer }: Deps) {
  const rate = await rates.get(order.currency);                   // needs an answer
  const saved = await orders.save({ ...order, total: Math.round(order.subtotal * rate) });
  await mailer.send(order.email, `Receipt #${saved.id}`);         // a side effect
  return saved;
}

Each collaborator gets a double doing a different job:

// order = { subtotal: 1000, currency: "EUR", email: "ada@example.com" }
const rates = { get: async () => 1.1 };          // STUB: feeds a canned answer in

const orders = new InMemoryOrders();             // FAKE: a real, simpler implementation
                                                 // (a Map instead of Postgres)
const mailer = { send: vi.fn() };                // SPY: records every call

const saved = await checkout(order, { rates, orders, mailer });

expect(await orders.find(saved.id)).toMatchObject({ total: 1100 });
expect(mailer.send).toHaveBeenCalledWith("ada@example.com", `Receipt #${saved.id}`);

These words describe the role a double plays in one test, not a type in Vitest. Vitest calls nearly everything a mock: vi.fn() gives you "a function that does nothing by default (returns undefined), but tracks every call made to it". Give it a return value and it's acting as a stub; assert on its calls and it's acting as a spy or a mock. vi.spyOn(obj, "method") "wraps an existing method", and "the original implementation still works by default".

Prefer the job that asserts least about how your code works. A fake you check the state of survives refactors; an exact list of expected calls breaks on every reshuffle.

When the code under test imports its collaborator, you can't pass a double in — you replace the module:

// profile.ts
import { fetchUser } from "./api";
export async function displayName(id: number) {
  return (await fetchUser(id)).name.toUpperCase();
}

// profile.test.ts
import { displayName } from "./profile";
import { fetchUser } from "./api";

vi.mock("./api"); // written below the imports, but runs before them

it("uppercases the name", async () => {
  vi.mocked(fetchUser).mockResolvedValue({ id: 1, name: "ada" });
  expect(await displayName(1)).toBe("ADA");
});

profile.ts imports ./api before the test body ever runs, so Vitest hoists vi.mock to the top of the file and turns static imports into dynamic ones behind it. That's what makes the replacement visible to profile.ts. With no factory, Vitest automocks the module: every exported function becomes a mock returning undefined, objects are deeply cloned (their methods mocked too), arrays are emptied, and primitives stay as they are — so an enum's values survive.

The hoisting trap

const fetchUserMock = vi.fn();
vi.mock("./api", () => ({ fetchUser: fetchUserMock }));

Under Vitest 4 the whole file fails to load:

Error: [vitest] There was an error when mocking a module. If you are using "vi.mock" factory,
make sure there are no top level variables inside, since this call is hoisted to top of the file.
Caused by: ReferenceError: Cannot access 'fetchUserMock' before initialization

The factory now runs before const fetchUserMock exists. Hoist the variable with it:

const { fetchUserMock } = vi.hoisted(() => ({ fetchUserMock: vi.fn() }));
vi.mock("./api", () => ({ fetchUser: fetchUserMock }));

A factory replaces the whole module

Whatever the factory returns is the module. If ./api also exports formatDate and the factory doesn't return it, the code under test gets nothing — Vitest 4 throws No "formatDate" export is defined on the "./api" mock. Keep the rest of the real module with importOriginal:

vi.mock(import("./api"), async (importOriginal) => ({
  ...(await importOriginal()),
  fetchUser: vi.fn(), // replace only this
}));

One limit no factory fixes: Vitest's docs say "it is not possible to mock calls to methods that are called inside other methods of the same file". If displayName and fetchUser live in one module, the internal call always hits the real function. The designing-for-testability unit covers what to do instead.

A test that restates the implementation

it("checks out", async () => {
  const rates = { get: vi.fn().mockResolvedValue(1.1) };
  const orders = { save: vi.fn().mockResolvedValue({ id: 1 }) };
  const mailer = { send: vi.fn() };

  await checkout(order, { rates, orders, mailer });

  expect(rates.get).toHaveBeenCalledWith("EUR");
  expect(orders.save).toHaveBeenCalledWith({ ...order, total: 1100 });
  expect(mailer.send).toHaveBeenCalledWith("ada@example.com", "Receipt #1");
  expect(rates.get.mock.invocationCallOrder[0])
    .toBeLessThan(orders.save.mock.invocationCallOrder[0]);
});

Every line mirrors a line of checkout. Cache the exchange rate, batch the save, send the email from a queue — behaviour unchanged, test red. And because orders.save is a stub, nothing checks that the saved order can actually be read back. This is over-mocking: doubles for your own modules, verified call by call, so the test can only pass for this exact implementation.

What to do instead:

• Replace only what you don't own or can't run in a test — the network, the clock, email, a payment provider. Use your own modules for real.
• Prefer a fake to a call log for your own storage: an in-memory orders you read back (expect(await orders.find(1)).toMatchObject({ total: 1100 })) checks the outcome, not the steps.
• Assert calls only where the call is the behaviour — "the receipt email was sent once, to this address" is the feature; "rates were fetched before saving" is not.

Replace the network, not your client

Stubbing fetch (or mocking your api.ts) skips your own client code: the URL you build, the headers, the res.ok check, the JSON parsing. Vitest's docs recommend Mock Service Worker for requests: it intercepts at the network layer, so your real client runs.

import { setupServer } from "msw/node";
import { http, HttpResponse } from "msw";

const server = setupServer(
  http.get("https://api.example.test/users/:id", ({ params }) =>
    HttpResponse.json({ id: Number(params.id), name: "ada" })),
);

beforeAll(() => server.listen({ onUnhandledRequest: "error" })); // unknown calls fail loudly
afterEach(() => server.resetHandlers());                          // drop per-test overrides
afterAll(() => server.close());

it("surfaces a 500", async () => {
  server.use(http.get("https://api.example.test/users/:id", () =>
    new HttpResponse(null, { status: 500 })));
  await expect(displayName(1)).rejects.toThrow("HTTP 500");
});

(Checked running under Vitest 4 with MSW 2.15 and with MSW 3.0, which shipped in September 2026 — the same code works on both.) onUnhandledRequest: "error" turns "the code called an endpoint nobody planned for" into a failure instead of a real request.

Cleanup semantics changed in Vitest 4

vi.restoreAllMocks() now only puts back originals for spies made with vi.spyOn. It no longer resets vi.fn() mocks or clears call history — checked on 4.1.12: after it, a vi.fn given mockReturnValue("override") still returns "override", and a spy keeps its recorded calls (Vitest 3.2 reset both). Use vi.clearAllMocks() (history) or vi.resetAllMocks() (history and implementations) for those. The config switches clearMocks, mockReset and restoreMocks all default to false in Vitest 4; Vitest 5 turns clearMocks on by default, so call counts stop carrying over between tests after the upgrade.