test_runner: support mocking non-existent modules

[SahinurDEV]

Fixes: #55891
Refs: #62298

This picks up #62298 by @geeksilva97, which was auto-closed as stale after it had addressed the only review feedback. The approach and the virtual option name come from that PR, so the commit credits Edy Silva with Co-authored-by. It is rebased onto current main, where mock.module() has since gained options.exports and dual-package (cjsPath) handling, and it changes a few things described below.

Problem

t.mock.module('obsidian', { … }) throws ERR_MODULE_NOT_FOUND when obsidian isn't installed. Use cases from the issue: host-provided modules such as obsidian/electron that only exist at runtime, user code that a function wrapper loads, and optional peer dependencies.

Root cause

mock.module() first resolves the specifier with the real resolver (moduleLoader.resolveSync), so that it can key the mock by the module's canonical URL. Both interception points also resolve normally before they look up a mock: the loader resolve hook calls nextResolve(), and the CJS Module._load patch calls _resolveFilename(). A module that doesn't exist therefore fails in all three places before any mock lookup happens. This is by design. Mocks are keyed by resolved URL so that every specifier pointing at the same file gets the same mock (cjihrig: "no technical reason we couldn't do it"). There was just no key for something that doesn't resolve.

Fix

New option virtual (boolean, default false). It is opt-in, so mocking a missing module without it still throws, and typos keep failing loudly, as pmarchini asked for in the issue.

• Registering (mock.js): if resolveSync throws ERR_MODULE_NOT_FOUND and virtual is true, the mock is keyed by getVirtualMockURL(specifier, callerURL) with format module:
  • bare specifier → node-test-mock:///<encodeURIComponent(specifier)>;
  • ./, ../, / or file: → the file URL it would resolve to, so ./x.js, ../dir/x.js and an absolute path to the same missing file share one mock.
• ESM/hooks (loader.js resolve): only when nextResolve throws ERR_MODULE_NOT_FOUND, compute the same key from context.parentURL. If there is an active virtual mock under that key, resolve to it. After that, the existing versioning and caching path runs unchanged. load short-circuits virtual mocks without calling nextLoad, because there is nothing on disk.
• CJS (Module._load patch): only when _resolveFilename throws MODULE_NOT_FOUND, compute the same key from parent.filename. If it names a virtual mock, use it. Otherwise the original error is rethrown.
• Existing modules: if the specifier does resolve, virtual has no effect and the module is mocked through the normal path. This addresses @ljharb's review comment on test_runner: support mocking non-existent modules #62298: a mock must not shadow only some of the specifiers (pkg/foo, ./foo/index.js, ./foo, …) that reach a real module, because that would leave two sources of truth. Since the fallback only runs when resolution fails, a virtual mock can never take effect for a module that exists.
• node: specifiers are never treated as virtual.

Changes compared with #62298:

• The fallback only triggers on not-found errors. test_runner: support mocking non-existent modules #62298 caught any resolution error, including errors such as ERR_PACKAGE_PATH_NOT_EXPORTED for modules that do exist.
• Relative and absolute paths are keyed by their resolved file URL. In test_runner: support mocking non-existent modules #62298 they were keyed by the raw specifier string, so ./x imported from two different directories would have collided.
• One URL helper is shared by the registration path, the ESM path and the CJS path. test_runner: support mocking non-existent modules #62298 kept separate raw-specifier entries in both maps.
• A bare virtual mock uses its synthetic URL as its CJS cache key. That way cache: true followed by restore() cleans up correctly, and a later re-mock doesn't see stale exports.
• Includes the documentation in doc/api/test.md, which test_runner: support mocking non-existent modules #62298 did not have.

Tests

New test/parallel/test-runner-module-mocking-virtual.js: validation of virtual; a missing module without virtual still throws; node: specifiers are rejected; a bare virtual mock works with import and require, default and named exports, and restore() brings back ERR_MODULE_NOT_FOUND/MODULE_NOT_FOUND; relative, absolute and file-URL paths to one missing file share a mock; virtual: true on an existing file intercepts both the path and the relative specifier; cache: true plus restore/re-mock.
Existing test/parallel/test-runner-module-mocking*.js pass. [fill in actual results]

Notes for reviewers

• semver-minor (new option on an experimental API).
• Once the PR number is known, add a changes: YAML entry for mock.module in doc/api/test.md (version: REPLACEME, this PR's URL, "Added virtual option.").

---

AI-assistance disclosure: I used an AI coding assistant to help investigate the issue and the earlier PR, and to draft the code, tests and this description. I reviewed, tested and understand all of the changes. The original approach is by @geeksilva97 (credited via Co-authored-by).

[nodejs-github-bot]

Review requested:

• @nodejs/test_runner

[github-actions]

Welcome to Node.js, and thank you for your first contribution!

Before review, please take a moment to read:

• the guide for first-time contributors
• the contribution and automation policies
• the pull request guide
• the AI use policy
• the Code of Conduct

Please make sure every commit is signed off. For a first pull request, GitHub Actions require collaborator approval and Jenkins CI must be started by a collaborator or triager, so an initial wait is normal.

[inoway46]

As noted in the first-time contribution guidelines, we recommend focusing on one PR at a time until the first one is approved.
Could you close one of your two PRs for now?

[SahinurDEV]

Thanks @inoway46, I missed that guideline. Closing this one for now so #66669 can go first; I'll reopen it once that one is approved. The branch stays on my fork.