Node.js Reference ยท util, assert and the Test Runner
Node.js mock.fn() method (node:test)
Reference for mock.fn() in node:test: create a mock function or spy, read calls and results from mock.calls, change behavior with mockImplementation, and reset.
mock.fn([original[, implementation]][, options]) creates a function that records every call made to it. It can wrap a real function (a spy: the call still happens, and you also get a record), replace it with another implementation (a stub), or be empty and return undefined.
The returned function has a .mock property, the mock context, with the list of calls and methods to change behavior later. mock is exported by node:test, and every test context has its own t.mock that restores itself when the test ends.
import { mock } from 'node:test'; const double = mock.fn((n) => n * 2); double(21); console.log(double.mock.callCount()); // 1
Try it
Mocks do not need the test runner to work, so these examples call them directly.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
mock.fn([original[, implementation]][, options]) t.mock.fn(...)
| Name | Description |
|---|---|
original |
The function to mock. With no implementation, calls run it (spy). Default: an empty function. |
implementation |
A function used in place of original for the first options.times calls (or all calls when times is not set). |
options.times |
How many calls use implementation; after that, calls go to original. Default: unlimited. |
Returns: the mock function. Its .mock property contains:
| Member | Description |
|---|---|
calls |
Array of call records. Each has arguments, result, error, this, stack and target. |
callCount() |
Number of calls made so far. |
mockImplementation(fn) |
Replace the behavior for all following calls. |
mockImplementationOnce(fn[, onCall]) |
Use fn for the next call (or for the call with zero-based index onCall). |
resetCalls() |
Clear calls (and so callCount()); keeps the behavior. |
restore() |
Put the original behavior back. For mock.fn this means calling original again. |
Edge cases
- If the function throws, the record has
errorset andresultisundefined. If it returns normally,errorisundefined. - For a mock of an async function,
resultis the returned promise, not the resolved value. Awaitcall.resultto read it. - For a call made with
new, the record'stargetis the original function (the class); for ordinary calls it isundefined.
Usage notes
- Assert on the record, not on the mock itself. Compare
mock.calls[0].argumentswithassert.deepStrictEqual(), and checkcallCount()for how often it ran. - Spy first, stub only when needed. Passing only
originalkeeps real behavior and still records calls, which makes tests less brittle than replacing everything. t.mock.fn()cleans up for you. Mocks created on the test context are restored when that test finishes. Mocks from the globalmockobject live until you callmock.restoreAll()ormock.reset().- Mocks are plain functions. You can pass them as callbacks:
[1, 2].map(spy)records every call, including the index and array arguments. - They do not replace modules or object methods by themselves. Use mock.method() for methods and mock.module() for imports.
- Avoid sharing one mock across tests unless you call
resetCalls()inbeforeEach(); leftover calls make later assertions fail in confusing ways. - Version notes.
mock.fn()is stable together withnode:testfrom Node.js 20.