Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js mock.module() method (node:test)

Reference for mock.module() in node:test: replace what an import returns, the exports option, cache, restore, and the experimental flag you need to enable it.

mock.module(specifier[, options]) replaces a module with fake exports for the rest of a test. Code that imports the module after the mock is installed receives your fake instead of the real thing. This lets you test code that imports a database client, a config loader or a Node.js built-in without touching the real one.

The feature is experimental. It is only available when Node.js starts with the --experimental-test-module-mocks flag, and it prints an experimental warning. Without the flag, mock.module is simply not a function. In this reference the examples start the test file with the flag through run().

NODE
// run with: node --test --experimental-test-module-mocks
import { test } from 'node:test';

test('uses a fake config', async (t) => {
  t.mock.module('./config.mjs', { exports: { default: { debug: true } } });
  const { run } = await import('./app.mjs'); // imported after the mock
});

Try it

The helper writes the test file to disk and starts it with run(), passing the experimental flag through execArgv. It prints what the tests log.

Node.js Replacing a local module

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 Mocking a built-in module and restoring

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
const context = mock.module(specifier[, options])
const context = t.mock.module(specifier[, options])
Name Description
specifier The module to replace: a relative path (resolved from the file that calls mock.module), a bare package name, or a node: built-in.
options.exports An object whose properties become the module's named exports. A property called default becomes the default export.
options.cache true to cache the mocked module so repeated import calls return the same namespace. Default false.
options.namedExports, options.defaultExport Older spellings that still work but are deprecated in favor of exports. Node prints a deprecation warning when you use them.

Returns: a mock module context with a restore() method.

Errors: calling mock.module() without the flag fails because the function does not exist.

Usage notes

  • Install the mock before the import. A module that was imported earlier keeps the real bindings it already received. In the first example the second import uses checkout.mjs?mocked to force a fresh load; in real test files you simply use dynamic await import() after the mock, and in a separate file per scenario.
  • Use dynamic imports in the test. A static import at the top of the test file is evaluated before mock.module() runs and therefore gets the real module.
  • Mocks and spies combine. Put mock.fn() functions inside exports to also record how the fake was called, as the second example shows.
  • CommonJS and ESM both work. A CommonJS file can be mocked as well; both import and require() of it see the mock in current releases. Check the result for your own module shapes.
  • Restoring. Use the returned context, or rely on t.mock to restore at the end of the test. Mocks created through the global mock stay until mock.restoreAll().
  • Prefer dependency injection when you can. Passing a dependency as an argument needs no mocking at all and keeps working when tooling changes. Module mocking is for code you cannot restructure.
  • Experimental means it can change. Pin your Node.js version in CI and watch the release notes. The exports option replaced two older options in recent releases.