mock.module is undefined in Node.js v22.9.0 node:test module

I'm trying to mock some module using Node.js v22.9.0 with the built-in node:test mock.module .

While other properties like mock.method work correctly, I get undefined when trying to access mock.module. This leads to a TypeError when I try to use it.

Here's the relevant portion of my code:


import { test, mock } from "node:test";

test("should....", (t) => { 
    mock.module('ioredis', { /* mock implementation */ });
});

However, when I try accessing mock.module, I get the following:

TypeError [Error]: mock.module is not a function

I also tried in the Node.js REPL:

Welcome to Node.js v22.9.0.
Type ".help" for more information.
> const { mock } = require("node:test");
undefined
> mock.method
[Function: method]
> mock.module
undefined

It seems like mock.module is missing. I've tried this on different setups and it's always undefined.

I've:

Verified that mock.method works fine, but mock.module is always undefined.
Checked the documentation for node:test, but haven't found anything specific about mock.module and it's supported in Node 22.9
Tried other Node versions.
Running this code in both the script and the Node.js REPL.

Environment:

Node.js version: 22.9.0
OS: WSL2 Ubuntu on Windows 11

How to get mock.module working in order to mock modules for testing?

Solution

This is a feature in early development, and hidden behind a flag: --experimental-test-module-mocks. The following test (in index.test.mjs):

import assert from "node:assert/strict";
import { mock, test } from "node:test";

test("node:test has a mock with a module property", (t) => {
    assert(mock.module);
});

Fails for even the latest version of Node.js (currently v22.9.0):

node --test
✖ node:test has a mock with a module property (7.442333ms)
  AssertionError [ERR_ASSERTION]: The expression evaluated to a falsy value:

    assert(mock.module)

      at TestContext.<anonymous> (file:///path/to/index.test.mjs:5:2)
      at Test.runInAsyncScope (node:async_hooks:211:14)
      at Test.run (node:internal/test_runner/test:930:25)
      at Test.start (node:internal/test_runner/test:829:17)
      at startSubtestAfterBootstrap (node:internal/test_runner/harness:289:17) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: undefined,
    expected: true,
    operator: '=='
  }

ℹ tests 1
ℹ suites 0
ℹ pass 0
ℹ fail 1
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 86.419333

✖ failing tests:

test at index.test.mjs:4:1
✖ node:test has a mock with a module property (7.442333ms)
  AssertionError [ERR_ASSERTION]: The expression evaluated to a falsy value:

    assert(mock.module)

      at TestContext.<anonymous> (file:///path/to/index.test.mjs:5:2)
      at Test.runInAsyncScope (node:async_hooks:211:14)
      at Test.run (node:internal/test_runner/test:930:25)
      at Test.start (node:internal/test_runner/test:829:17)
      at startSubtestAfterBootstrap (node:internal/test_runner/harness:289:17) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: undefined,
    expected: true,
    operator: '=='
  }

unless the flag is set:

node --test --experimental-test-module-mocks
✔ node:test has a mock with a module property (1.00375ms)
ℹ tests 1
ℹ suites 0
ℹ pass 1
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 84.6655

If the flag isn't set, module is removed from the MockTracker prototype here.