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().
// 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.
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
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?mockedto force a fresh load; in real test files you simply use dynamicawait import()after the mock, and in a separate file per scenario. - Use dynamic imports in the test. A static
importat the top of the test file is evaluated beforemock.module()runs and therefore gets the real module. - Mocks and spies combine. Put
mock.fn()functions insideexportsto 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
importandrequire()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.mockto restore at the end of the test. Mocks created through the globalmockstay untilmock.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
exportsoption replaced two older options in recent releases.