Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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.

Node.js Recording calls, results and errors

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.

Node.js Changing behavior, times and resetting

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

NODE
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 error set and result is undefined. If it returns normally, error is undefined.
  • For a mock of an async function, result is the returned promise, not the resolved value. Await call.result to read it.
  • For a call made with new, the record's target is the original function (the class); for ordinary calls it is undefined.

Usage notes

  • Assert on the record, not on the mock itself. Compare mock.calls[0].arguments with assert.deepStrictEqual(), and check callCount() for how often it ran.
  • Spy first, stub only when needed. Passing only original keeps 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 global mock object live until you call mock.restoreAll() or mock.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() in beforeEach(); leftover calls make later assertions fail in confusing ways.
  • Version notes. mock.fn() is stable together with node:test from Node.js 20.