MockTracker.module method | Node.js node:test module | Bun

This function is used to mock the exports of ECMAScript modules, CommonJS modules, JSON modules, and Node.js builtin modules. Any references to the original module prior to mocking are not impacted. In order to enable module mocking, Node.js must be started with the --experimental-test-module-mocks command-line flag.

Note: module customization hooks registered via the synchronous API effect resolution of the specifier provided to mock.module. Customization hooks registered via the asynchronous API are currently ignored (because the test runner's loader is synchronous, and node does not support multi-chain / cross-chain loading).

The following example demonstrates how a mock is created for a module.

test('mocks a builtin module in both module systems', async (t) => {
// Create a mock of 'node:readline' with a named export named 'foo', which
// does not exist in the original 'node:readline' module.
const mock = t.mock.module('node:readline', {
exports: { foo: () => 42 },
});

let esmImpl = await import('node:readline');
let cjsImpl = require('node:readline');

// cursorTo() is an export of the original 'node:readline' module.
assert.strictEqual(esmImpl.cursorTo, undefined);
assert.strictEqual(cjsImpl.cursorTo, undefined);
assert.strictEqual(esmImpl.fn(), 42);
assert.strictEqual(cjsImpl.fn(), 42);

mock.restore();

// The mock is restored, so the original builtin module is returned.
esmImpl = await import('node:readline');
cjsImpl = require('node:readline');

assert.strictEqual(typeof esmImpl.cursorTo, 'function');
assert.strictEqual(typeof cjsImpl.cursorTo, 'function');
assert.strictEqual(esmImpl.fn, undefined);
assert.strictEqual(cjsImpl.fn, undefined);
});

A string identifying the module to mock.

Optional configuration options for the mock module.