test_runner: fix virtual mock to resolve canonical URL before mocking

Author: geeksilva97

lib/internal/test_runner/mock/loader.js

@@ -18,23 +18,28 @@ const mocks = new SafeMap();
 function resolve(specifier, context, nextResolve) {
   debug('resolve hook entry, specifier = "%s", context = %o', specifier, context);
 
-  // Virtual mocks - skip resolution, the module may not exist on disk.
-  const virtualMock = mocks.get(specifier);
-  if (virtualMock?.virtual && virtualMock?.active === true) {
-    const url = new URL(virtualMock.url);
-    url.searchParams.set(kMockSearchParam, virtualMock.localVersion);
-    if (!virtualMock.cache) {
-      virtualMock.localVersion++;
+  // Try normal resolution first. If it fails, check for a virtual mock
+  // of a non-existent module.
+  let nextResolveResult;
+  try {
+    nextResolveResult = nextResolve(specifier, context);
+  } catch (resolveError) {
+    // Resolution failed - check if there's a virtual mock for this specifier.
+    const virtualMock = mocks.get(specifier);
+    if (virtualMock?.active === true && virtualMock?.virtual) {
+      const url = new URL(virtualMock.url);
+      url.searchParams.set(kMockSearchParam, virtualMock.localVersion);
+      if (!virtualMock.cache) {
+        virtualMock.localVersion++;
+      }
+      const { href } = url;
+      debug('resolve hook finished (virtual), url = "%s"', href);
+      return { __proto__: null, url: href, format: virtualMock.format, shortCircuit: true };
     }
-
-    const { href } = url;
-    debug('resolve hook finished (virtual), url = "%s"', href);
-    return { __proto__: null, url: href, format: virtualMock.format, shortCircuit: true };
+    throw resolveError;
   }
 
-  const nextResolveResult = nextResolve(specifier, context);
   const mockSpecifier = nextResolveResult.url;
-
   const mock = mocks.get(mockSpecifier);
   debug('resolve hook, specifier = "%s", mock = %o', specifier, mock);
 
@@ -53,7 +58,7 @@ function resolve(specifier, context, nextResolve) {
 
   const { href } = url;
   debug('resolve hook finished, url = "%s"', href);
-  return { __proto__: null, url: href, format: nextResolveResult.format };
+  return { __proto__: null, url: href, format: mock.format || nextResolveResult.format };
 }
 
 function load(url, context, nextLoad) {

lib/internal/test_runner/mock/mock.js

@@ -209,7 +209,8 @@ class MockModuleContext {
     if (fullPath) {
       sharedState.mockMap.set(fullPath, config);
     } else if (virtual) {
-      // Virtual mock - store under raw specifier for CJS resolution fallback.
+      // Virtual mock for a non-existent module - store under raw specifier
+      // so CJS resolution fallback can find it.
       sharedState.mockMap.set(specifier, config);
     }
 
@@ -278,7 +279,7 @@ class MockModuleContext {
 
       this.#sharedState.mockMap.delete(this.#restore.fullPath);
     } else if (this.#restore.specifier !== undefined) {
-      // Virtual mock - clean up specifier key.
+      // Virtual mock for non-existent module - clean up specifier key.
       this.#sharedState.mockMap.delete(this.#restore.specifier);
     }
 
@@ -673,35 +674,27 @@ class MockTracker {
     // If the caller is already a file URL, use it as is. Otherwise, convert it.
     const hasFileProtocol = StringPrototypeStartsWith(filename, 'file://');
     const caller = hasFileProtocol ? filename : pathToFileURL(filename).href;
-    if (virtual) {
-      const url = `mock:///${encodeURIComponent(mockSpecifier)}`;
-      const format = 'module';
-      const baseURL = URLParse(url);
-      const ctx = new MockModuleContext({
-        __proto__: null,
-        baseURL: baseURL.href,
-        cache,
-        caller,
-        defaultExport,
-        format,
-        fullPath: null,
-        hasDefaultExport,
-        namedExports,
-        sharedState,
-        specifier: mockSpecifier,
-        virtual,
-      });
+    const request = { __proto__: null, specifier: mockSpecifier, attributes: kEmptyObject };
 
-      ArrayPrototypePush(this.#mocks, {
-        __proto__: null,
-        ctx,
-        restore: restoreModule,
-      });
-      return ctx;
+    // Try to resolve the specifier. For virtual mocks, if the module exists
+    // on disk, use its canonical URL so that all resolution paths to that
+    // module are properly intercepted. Only fall back to a synthetic URL
+    // if the module truly doesn't exist.
+    let format, url;
+    if (virtual) {
+      try {
+        ({ url } = sharedState.moduleLoader.resolveSync(caller, request));
+      } catch {
+        // Module doesn't exist - use a synthetic URL.
+        url = `mock:///${encodeURIComponent(mockSpecifier)}`;
+      }
+      // Virtual mocks always use 'module' format since the generated source
+      // is ESM regardless of the original module's format.
+      format = 'module';
+    } else {
+      ({ format, url } = sharedState.moduleLoader.resolveSync(caller, request));
     }
 
-    const request = { __proto__: null, specifier: mockSpecifier, attributes: kEmptyObject };
-    const { format, url } = sharedState.moduleLoader.resolveSync(caller, request);
     debug('module mock, url = "%s", format = "%s", caller = "%s"', url, format, caller);
     if (format) { // Format is not yet known for ambiguous files when detection is enabled.
       validateOneOf(format, 'format', kSupportedFormats);
@@ -896,13 +889,20 @@ function setupSharedModuleState() {
 function cjsMockModuleLoad(request, parent, isMain) {
   let resolved;
 
-  // Virtual mock - skip resolution, the module doesn't exist on disk.
-  if (this.mockMap.get(request)?.virtual) {
-    resolved = request;
-  } else if (isBuiltin(request)) {
+  if (isBuiltin(request)) {
     resolved = ensureNodeScheme(request);
   } else {
-    resolved = _resolveFilename(request, parent, isMain);
+    try {
+      resolved = _resolveFilename(request, parent, isMain);
+    } catch (resolveError) {
+      // Resolution failed - check if there's a virtual mock for this specifier.
+      const virtualConfig = this.mockMap.get(request);
+      if (virtualConfig?.virtual) {
+        resolved = request;
+      } else {
+        throw resolveError;
+      }
+    }
   }
 
   const config = this.mockMap.get(resolved);

test/fixtures/test-runner/mock-virtual-paths.js

@@ -0,0 +1,27 @@
+'use strict';
+const assert = require('node:assert');
+const { test } = require('node:test');
+
+// This test verifies that a virtual mock of an existing package intercepts
+// ALL resolution paths to that module, not just the exact specifier used
+// to create the mock. This is critical to avoid multiple sources of truth.
+
+test('virtual mock intercepts all resolution paths to the same module', async (t) => {
+  t.mock.module('reporter-cjs', {
+    virtual: true,
+    namedExports: { fn() { return 'mocked'; } },
+  });
+
+  // Access via package name (the specifier used to create the mock).
+  const byName = require('reporter-cjs');
+  assert.strictEqual(byName.fn(), 'mocked');
+
+  // Access via relative path to the actual file on disk. This resolves to
+  // the same canonical file:// URL, so it must also return the mock.
+  const byRelativePath = require('./node_modules/reporter-cjs/index.js');
+  assert.strictEqual(byRelativePath.fn(), 'mocked');
+
+  // Access via import() by package name.
+  const byImport = await import('reporter-cjs');
+  assert.strictEqual(byImport.fn(), 'mocked');
+});

test/parallel/test-runner-module-mocking.js

@@ -759,9 +759,30 @@ test('virtual mock overrides an existing module', async (t) => {
     namedExports: { custom() { return 'virtual'; } },
   });
 
+  // Both 'readline' and 'node:readline' should resolve to the mock
+  // because the specifier resolves to the same canonical URL.
   const mocked = await import('readline');
   assert.strictEqual(mocked.custom(), 'virtual');
   assert.strictEqual(mocked.cursorTo, undefined);
+
+  const mockedWithPrefix = await import('node:readline');
+  assert.strictEqual(mockedWithPrefix.custom(), 'virtual');
+  assert.strictEqual(mockedWithPrefix.cursorTo, undefined);
+});
+
+test('virtual mock intercepts all resolution paths to the same module', async (t) => {
+  const cwd = fixtures.path('test-runner');
+  const fixture = fixtures.path('test-runner', 'mock-virtual-paths.js');
+  const args = ['--experimental-test-module-mocks', fixture];
+  const {
+    code,
+    stdout,
+    signal,
+  } = await common.spawnPromisified(process.execPath, args, { cwd });
+
+  assert.strictEqual(code, 0);
+  assert.strictEqual(signal, null);
+  assert.match(stdout, /pass 1/);
 });
 
 test('input validation for virtual option', async (t) => {