In the last lesson you wrote a stub API by hand, with a counter. It worked, and it was about fifteen lines. Vitest’s vi helpers do the same in one line, and they add a lot of power. That power is the problem: mocking is the fastest way to write a test that passes while the real code is broken. This lesson covers the tools and the judgement.
All of these are test doubles, stand-ins for a real collaborator:
\nIn Vitest, vi.fn() gives you a stub and a spy in one object, and people call all of them “mocks”. The names matter less than the question each answers: what does this collaborator return? (stub) and how was it called? (spy).
Splitwise-lite sends a reminder to everyone who owes money. The sender is passed in, so a test can replace it:
\nimport { test, expect, vi } from 'vitest';\nimport { remindDebtors } from './remind.js';\n\ntest('reminds people who owe money, with the amount', () => {\n const sendReminder = vi.fn();\n\n const sent = remindDebtors({ Ana: 1500, Ben: -500, Cai: 0 }, sendReminder);\n\n expect(sent).toBe(1);\n expect(sendReminder).toHaveBeenCalledTimes(1);\n expect(sendReminder).toHaveBeenCalledWith('Ben', 'You owe $5.00 to the group');\n});vi.fn() returns undefined by default. Give it behaviour when the code under test needs an answer:
const post = vi.fn().mockResolvedValue({ id: 'e1' }); // async success\nconst failing = vi.fn().mockRejectedValue(new Error('Offline')); // async failure\nconst send = vi.fn().mockImplementation((name) => {\n if (name === 'Ben') throw new Error('Mailbox full');\n});Every call is recorded in send.mock.calls, an array of argument arrays, for the rare case the matchers don’t cover.
Sometimes the collaborator is a method on an existing object, like console.warn. vi.spyOn wraps it: by default the real method still runs, and the spy records calls. Chain mockImplementation to silence or replace it:
import { afterEach, test, expect, vi } from 'vitest';\n\nafterEach(() => {\n vi.restoreAllMocks(); // put console.warn back\n});\n\ntest('warns and carries on when one reminder fails', () => {\n const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});\n const send = vi.fn().mockImplementationOnce(() => { throw new Error('Mailbox full'); });\n\n const sent = remindDebtors({ Ben: -500, Dee: -300 }, send);\n\n expect(sent).toBe(1);\n expect(send).toHaveBeenCalledTimes(2);\n expect(warn).toHaveBeenCalledWith('Could not remind Ben: Mailbox full');\n});A spy replaces a method on a shared object. Forget to restore it and every later test in the file runs with a silent console.warn. vi.restoreAllMocks() in afterEach, or restoreMocks: true in the config, makes cleanup automatic.
Code that waits (debounced autosave, retry back-off, “undo” toasts) is painful to test in real time. Fake timers replace setTimeout, setInterval and Date with a clock the test controls:
import { afterEach, test, expect, vi } from 'vitest';\n\nafterEach(() => vi.useRealTimers());\n\ntest('autosaves the draft 2 seconds after the last change', () => {\n vi.useFakeTimers();\n const save = vi.fn();\n const draft = createDraft({ save, delayMs: 2000 }); // debounced\n\n draft.update({ description: 'Din' });\n draft.update({ description: 'Dinner' });\n vi.advanceTimersByTime(1999);\n expect(save).not.toHaveBeenCalled();\n\n vi.advanceTimersByTime(1);\n expect(save).toHaveBeenCalledWith({ description: 'Dinner' });\n});vi.advanceTimersByTime(ms) runs every timer due within that window, instantly. vi.setSystemTime(date) pins new Date(), which is how you test “reminders go out on the first of the month”. When timers schedule promises, use the async variants such as vi.advanceTimersByTimeAsync. (The playground runs real timers only, so this one stays on the page.)
Every mock is a claim about how the real thing behaves. When reality drifts from the claim, the test keeps passing. The patterns that bite:
\nparseAmount inside a form test means the form and parser are never tested together, which was the point of the test. Your own pure code is fast; use it.remindDebtors while testing remindDebtors, you are testing the spy.{ id }; the real one returns { data: { id } }. Unit tests green, app broken. The next section’s network mocking and the end-to-end tests in section 4 exist to catch exactly this.A quick sanity check for any mock you write: delete one line of the real code it stands in for. If no test fails anywhere in the suite, that mock was hiding the behaviour instead of testing around it, and somewhere you need a test that runs the real thing.
\nMy rule: mock at the boundaries of your system (network, email, payment, time, randomness) and run the real code everywhere inside.
\nIn the exercise, use vi.fn and vi.spyOn to catch four bugs in remindDebtors. Section 3 moves from functions to the DOM.
vi.fn() creates a function that records every call, and you can tell it what to return with mockReturnValue, mockResolvedValue or mockImplementation.","vi.spyOn(object, 'method') watches a real method and can override it; always restore spies, for example with vi.restoreAllMocks() in afterEach.","Mock at the boundaries of your system (network, email, time, randomness) and use the real code for your own modules.","Fake timers (vi.useFakeTimers, vi.advanceTimersByTime) let a test skip ahead through delays instead of waiting for them.","Every mock is a claim about how the real thing behaves; when that claim drifts, the test stays green while production breaks."],"further":[{"title":"Vitest — Mocking guide","url":"https://vitest.dev/guide/mocking"},{"title":"Vitest — Mock functions API","url":"https://vitest.dev/api/mock"},{"title":"Vitest — Fake timers","url":"https://vitest.dev/guide/mocking/timers"}],"quiz":[{"q":"You want to check that remindDebtors calls sendReminder('Ben', 'You owe $5.00 to the group'). Which assertion fits?
expect(sendReminder).toHaveBeenCalledWith('Ben', 'You owe $5.00 to the group')","why":"Correct. toHaveBeenCalledWith passes if any recorded call used exactly those arguments, in that order."},{"text":"expect(sendReminder('Ben')).toBe('You owe $5.00 to the group')","why":"This calls the mock yourself and checks its return value; it says nothing about what remindDebtors did."},{"text":"expect(sendReminder).toHaveBeenCalled()","why":"It passes even if the arguments are wrong or swapped, so it would miss most of the bugs you care about."}],"answer":0},{"q":"A test for the expense form mocks the in-house parseAmount module so that it always returns 1250. The real parseAmount gets a bug. What happens to that form test?
vi.mock can replace any module, yours included, which is exactly the danger here."},{"text":"It stays green, because it never runs the real parser; the form and parser are no longer tested together.","why":"Correct. Mocking your own pure modules buys little speed and removes the integration you wanted to check."}],"answer":2},{"q":"A draft autosaves 2 seconds after the last keystroke. With vi.useFakeTimers() on, how does the test get the save to happen?
await new Promise((r) => setTimeout(r, 2000)).","why":"Under fake timers that setTimeout is fake too, so it never fires on its own and the test hangs until it times out."},{"text":"Call vi.advanceTimersByTime(2000) after the last keystroke, then assert the save happened.","why":"Correct. Advancing the fake clock runs every timer due within that window, instantly."},{"text":"Set the test timeout to 3 seconds so the real timer has time to fire.","why":"With fake timers installed there is no real timer; a longer timeout only delays the failure."}],"answer":1},{"q":"Why do you call vi.restoreAllMocks() (or set restoreMocks) after tests that use vi.spyOn?
vi.fn() mocks to zero.","why":"Clearing call history is what mockClear does; restoring is about putting the original method back."},{"text":"To put the original methods back so a spy from one test can’t change behaviour in another.","why":"Correct. A spy replaces a real method on a shared object such as console; without restoring, the override leaks into later tests."},{"text":"Because Vitest refuses to run a second test while a spy exists.","why":"Vitest runs happily with leaked spies, which is exactly why leaks cause confusing failures in unrelated tests."}],"answer":1}],"exercise":{"kind":"web","mode":"test","subject":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Sends a reminder to everyone who owes money (a negative balance).\n// - Calls sendReminder(name, message) once per debtor, with a message\n// such as \"You owe $5.00 to the group\".\n// - Skips debts smaller than minimumCents (default 100, i.e. $1.00);\n// a debt of exactly minimumCents IS reminded.\n// - People who are owed money or are settled up get nothing.\n// - If sendReminder throws for someone, logs\n// console.warn(\"Could not remind remindDebtors(balances, sendReminder) calls sendReminder(name, message) for each person who owes at least $1.00, warns with console.warn when a reminder fails, and returns how many it sent. Positive balances are owed money; negative balances owe. The rules are in the subject’s comment.
The starter already spies on console.warn (and restores it after each test). Use vi.fn() for sendReminder and add tests until your suite catches four hidden bugs: one reminds people who are owed money, one swaps the two arguments, one skips a debt of exactly $1.00, and one stops at the first failed reminder.
vi.fn() and check it with toHaveBeenCalledWith('Ben', 'You owe $5.00 to the group') and toHaveBeenCalledTimes(1). The exact argument order matters.","Boundary: a balance of -100 must be reminded, -99 must not.","For the failure case, make the mock throw for one name: vi.fn().mockImplementation((name) => { if (name === 'Ben') throw new Error('Mailbox full'); }), then assert that the next debtor was still called and that warn was called with the message."],"explanation":"toHaveBeenCalledWith checks the arguments in order, so it catches the swapped version, and toHaveBeenCalledTimes(1) with a creditor in the balances catches the version that reminds everyone. The boundary test uses -100 and -99, one on each side of the limit; -100, exactly on it, is the input that tells < from <=. The failure test makes the mock throw for one person and checks that the next person was still reminded; the version that rethrows never gets there and the test fails. The console.warn spy turns a side effect you would normally ignore into something you can assert, and restoring it in afterEach keeps it from leaking into other tests.