fix(jest-runtime, jest-resolver): Allow core models to be mocked with "node:" URL paths (#14297)

Allow modules imported and mocked with 'node:*' URLs to be manually mocked by resolving just the path when generating module ID's for setting and checking mocks, and when resolving module names when importing mocks.

Author: KhaledElmorsy

CHANGELOG.md

@@ -223,6 +223,7 @@
 
 ### Fixes
 
+- `[jest-runtime, jest-resolve]` Allow core modules to be mocked with the `node:` URL scheme ([#14297](https://github.com/jestjs/jest/pull/14297))
 - `[jest-circus]` Prevent false test failures caused by promise rejections handled asynchronously ([#14110](https://github.com/jestjs/jest/pull/14110))
 - `[jest-config]` Handle frozen config object ([#14054](https://github.com/facebook/jest/pull/14054))
 - `[jest-config]` Allow `coverageDirectory` and `collectCoverageFrom` in project config ([#14180](https://github.com/jestjs/jest/pull/14180))

e2e/__tests__/__snapshots__/moduleNameMapper.test.ts.snap

@@ -41,7 +41,7 @@ exports[`moduleNameMapper wrong array configuration 1`] = `
       12 | module.exports = () => 'test';
       13 |
 
-      at createNoMappedModuleFoundError (../../packages/jest-resolve/build/index.js:1177:17)
+      at createNoMappedModuleFoundError (../../packages/jest-resolve/build/index.js:1184:17)
       at Object.require (index.js:10:1)
       at Object.require (__tests__/index.js:10:20)"
 `;
@@ -71,7 +71,7 @@ exports[`moduleNameMapper wrong configuration 1`] = `
       12 | module.exports = () => 'test';
       13 |
 
-      at createNoMappedModuleFoundError (../../packages/jest-resolve/build/index.js:1177:17)
+      at createNoMappedModuleFoundError (../../packages/jest-resolve/build/index.js:1184:17)
       at Object.require (index.js:10:1)
       at Object.require (__tests__/index.js:10:20)"
 `;

e2e/__tests__/nodeURLManualMocks.test.js

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import runJest from '../runJest';
+
+test('supports node url manual mocks', () => {
+  const result = runJest('node-url-manual-mocks');
+  expect(result.exitCode).toBe(0);
+});

e2e/node-url-manual-mocks/__mocks__/fs.js

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const {mock} = require('../testUtils');
+console.log(mock);
+module.exports = mock;

e2e/node-url-manual-mocks/__tests__/importAndMock.test.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const fs = require('node:fs');
+const {expectModuleMocked} = require('../testUtils');
+
+jest.mock('node:fs');
+
+it('correctly mocks the module', () => {
+  expectModuleMocked(fs);
+});

e2e/node-url-manual-mocks/__tests__/importOnly.test.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const fs = require('node:fs');
+const {expectModuleMocked} = require('../testUtils');
+
+jest.mock('fs');
+
+it('correctly mocks the module', () => {
+  expectModuleMocked(fs);
+});

e2e/node-url-manual-mocks/__tests__/mockOnly.test.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const fs = require('fs');
+const {expectModuleMocked} = require('../testUtils');
+
+jest.mock('node:fs');
+
+it('correctly mocks the module', () => {
+  expectModuleMocked(fs);
+});

e2e/node-url-manual-mocks/package.json

@@ -0,0 +1,5 @@
+{
+  "jest": {
+    "testEnvironment": "node"
+  }
+}

e2e/node-url-manual-mocks/testUtils.js

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const mock = {};
+module.exports.mock = mock;
+
+module.exports.expectModuleMocked = module => {
+  // eslint-disable-next-line no-undef
+  expect(module).toBe(mock);
+};

jest.config.mjs

@@ -30,6 +30,7 @@ export default {
     'packages/jest-runtime/src/__tests__/test_root.*',
     'website/.*',
     'e2e/runtime-internal-module-registry/__mocks__',
+    'e2e/node-url-manual-mocks/__mocks__',
   ],
   projects: ['<rootDir>', '<rootDir>/examples/*/'],
   snapshotFormat: {

packages/jest-resolve/src/resolver.ts

@@ -459,6 +459,12 @@ export default class Resolver {
     );
   }
 
+  normalizeCoreModuleSpecifier(specifier: string): string {
+    return specifier.startsWith('node:')
+      ? specifier.slice('node:'.length)
+      : specifier;
+  }
+
   getModule(name: string): string | null {
     return this._moduleMap.getModule(
       name,
@@ -491,9 +497,9 @@ export default class Resolver {
     if (mock) {
       return mock;
     } else {
-      const moduleName = this.resolveStubModuleName(from, name, options);
-      if (moduleName) {
-        return this.getModule(moduleName) || moduleName;
+      const resolvedName = this.resolveStubModuleName(from, name, options);
+      if (resolvedName) {
+        return this._moduleMap.getMockModule(resolvedName) ?? null;
       }
     }
     return null;
@@ -508,13 +514,13 @@ export default class Resolver {
     if (mock) {
       return mock;
     } else {
-      const moduleName = await this.resolveStubModuleNameAsync(
+      const resolvedName = await this.resolveStubModuleNameAsync(
         from,
         name,
         options,
       );
-      if (moduleName) {
-        return this.getModule(moduleName) || moduleName;
+      if (resolvedName) {
+        return this._moduleMap.getMockModule(resolvedName) ?? null;
       }
     }
     return null;
@@ -626,7 +632,7 @@ export default class Resolver {
     options: ResolveModuleConfig,
   ): string | null {
     if (this.isCoreModule(moduleName)) {
-      return moduleName;
+      return this.normalizeCoreModuleSpecifier(moduleName);
     }
     if (moduleName.startsWith('data:')) {
       return moduleName;
@@ -793,6 +799,11 @@ export default class Resolver {
     moduleName: string,
     options?: Pick<ResolveModuleConfig, 'conditions'>,
   ): Promise<string | null> {
+    // Strip node URL scheme from core modules imported using it
+    if (this.isCoreModule(moduleName)) {
+      return this.normalizeCoreModuleSpecifier(moduleName);
+    }
+
     const dirname = path.dirname(from);
 
     const {extensions, moduleDirectory, paths} = this._prepareForResolution(

packages/jest-runtime/src/index.ts

@@ -1062,20 +1062,28 @@ export default class Runtime {
       return module as T;
     }
 
-    const manualMockOrStub = this._resolver.getMockModule(
-      from,
-      moduleName,
-      options,
-    );
+    /** Resolved mock module path from (potentially aliased) module name. */
+    const manualMockPath: string | null = (() => {
+      // Attempt to get manual mock path when moduleName is a:
+
+      // A. Core module specifier i.e. ['fs', 'node:fs']:
+      // Normalize then check for a root manual mock '<rootDir>/__mocks__/'
+      if (this._resolver.isCoreModule(moduleName)) {
+        const moduleWithoutNodePrefix =
+          this._resolver.normalizeCoreModuleSpecifier(moduleName);
+        return this._resolver.getMockModule(
+          from,
+          moduleWithoutNodePrefix,
+          options,
+        );
+      }
 
-    let modulePath =
-      this._resolver.getMockModule(from, moduleName, options) ||
-      this._resolveCjsModule(from, moduleName);
+      // B. Node module specifier i.e. ['jest', 'react']:
+      // Look for root manual mock
+      const rootMock = this._resolver.getMockModule(from, moduleName, options);
+      if (rootMock) return rootMock;
 
-    let isManualMock =
-      manualMockOrStub &&
-      !this._resolver.resolveStubModuleName(from, moduleName, options);
-    if (!isManualMock) {
+      // C. Relative/Absolute path:
       // If the actual module file has a __mocks__ dir sitting immediately next
       // to it, look to see if there is a manual mock for this file.
       //
@@ -1087,7 +1095,7 @@ export default class Runtime {
       // Where some other module does a relative require into each of the
       // respective subDir{1,2} directories and expects a manual mock
       // corresponding to that particular my_module.js file.
-
+      const modulePath = this._resolveCjsModule(from, moduleName);
       const moduleDir = path.dirname(modulePath);
       const moduleFileName = path.basename(modulePath);
       const potentialManualMock = path.join(
@@ -1096,26 +1104,28 @@ export default class Runtime {
         moduleFileName,
       );
       if (fs.existsSync(potentialManualMock)) {
-        isManualMock = true;
-        modulePath = potentialManualMock;
+        return potentialManualMock;
       }
-    }
-    if (isManualMock) {
+
+      return null;
+    })();
+
+    if (manualMockPath) {
       const localModule: InitialModule = {
         children: [],
         exports: {},
-        filename: modulePath,
-        id: modulePath,
+        filename: manualMockPath,
+        id: manualMockPath,
         isPreloading: false,
         loaded: false,
-        path: path.dirname(modulePath),
+        path: path.dirname(manualMockPath),
       };
 
       this._loadModule(
         localModule,
         from,
         moduleName,
-        modulePath,
+        manualMockPath,
         undefined,
         mockRegistry,
       );
@@ -1747,9 +1757,7 @@ export default class Runtime {
 
   private _requireCoreModule(moduleName: string, supportPrefix: boolean) {
     const moduleWithoutNodePrefix =
-      supportPrefix && moduleName.startsWith('node:')
-        ? moduleName.slice('node:'.length)
-        : moduleName;
+      supportPrefix && this._resolver.normalizeCoreModuleSpecifier(moduleName);
 
     if (moduleWithoutNodePrefix === 'process') {
       return this._environment.global.process;