test_runner: add exports option for module mocks

Add options.exports support in mock.module() and normalize option

shapes through a shared exports path.

Keep defaultExport and namedExports as aliases, emit runtime

deprecation warnings for legacy options, and update docs and tests,

including output fixtures and coverage snapshots.

Refs: #58443
PR-URL: #61727
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jacob Smith <jacob@frende.me>
Reviewed-By: Pietro Marchini <pietro.marchini94@gmail.com>
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Author: Han5991

doc/api/test.md

@@ -2480,16 +2480,32 @@ changes:
     generates a new mock module. If `true`, subsequent calls will return the same
     module mock, and the mock module is inserted into the CommonJS cache.
     **Default:** false.
+  * `exports` {Object} Optional mocked exports. The `default` property, if
+    provided, is used as the mocked module's default export. All other own
+    enumerable properties are used as named exports.
+    **This option cannot be used with `defaultExport` or `namedExports`.**
+    * If the mock is a CommonJS or builtin module, `exports.default` is used as
+      the value of `module.exports`.
+    * If `exports.default` is not provided for a CommonJS or builtin mock,
+      `module.exports` defaults to an empty object.
+    * If named exports are provided with a non-object default export, the mock
+      throws an exception when used as a CommonJS or builtin module.
   * `defaultExport` {any} An optional value used as the mocked module's default
     export. If this value is not provided, ESM mocks do not include a default
     export. If the mock is a CommonJS or builtin module, this setting is used as
     the value of `module.exports`. If this value is not provided, CJS and builtin
     mocks use an empty object as the value of `module.exports`.
+    **This option cannot be used with `options.exports`.**
+    This option is deprecated and will be removed in a later version.
+    Prefer `options.exports.default`.
   * `namedExports` {Object} An optional object whose keys and values are used to
     create the named exports of the mock module. If the mock is a CommonJS or
     builtin module, these values are copied onto `module.exports`. Therefore, if a
     mock is created with both named exports and a non-object default export, the
     mock will throw an exception when used as a CJS or builtin module.
+    **This option cannot be used with `options.exports`.**
+    This option is deprecated and will be removed in a later version.
+    Prefer `options.exports`.
 * Returns: {MockModuleContext} An object that can be used to manipulate the mock.
 
 This function is used to mock the exports of ECMAScript modules, CommonJS modules, JSON modules, and
@@ -2506,10 +2522,10 @@ The following example demonstrates how a mock is created for a module.
 
 ```js
 test('mocks a builtin module in both module systems', async (t) => {
-  // Create a mock of 'node:readline' with a named export named 'fn', which
+  // Create a mock of 'node:readline' with a named export named 'foo', which
   // does not exist in the original 'node:readline' module.
   const mock = t.mock.module('node:readline', {
-    namedExports: { fn() { return 42; } },
+    exports: { foo: () => 42 },
   });
 
   let esmImpl = await import('node:readline');

lib/internal/test_runner/mock/loader.js

@@ -113,10 +113,10 @@ function defaultExportSource(useESM, hasDefaultExport) {
   if (!hasDefaultExport) {
     return '';
   } else if (useESM) {
-    return 'export default $__exports.defaultExport;';
+    return 'export default $__exports.moduleExports.default;';
   }
 
-  return 'module.exports = $__exports.defaultExport;';
+  return 'module.exports = $__exports.moduleExports.default;';
 }
 
 function namedExportsSource(useESM, exportNames) {
@@ -134,9 +134,9 @@ if (module.exports === null || typeof module.exports !== 'object') {
     const name = exportNames[i];
 
     if (useESM) {
-      source += `export let ${name} = $__exports.namedExports[${JSONStringify(name)}];\n`;
+      source += `export let ${name} = $__exports.moduleExports[${JSONStringify(name)}];\n`;
     } else {
-      source += `module.exports[${JSONStringify(name)}] = $__exports.namedExports[${JSONStringify(name)}];\n`;
+      source += `module.exports[${JSONStringify(name)}] = $__exports.moduleExports[${JSONStringify(name)}];\n`;
     }
   }
 

lib/internal/test_runner/mock/mock.js

@@ -1,10 +1,12 @@
 'use strict';
 const {
+  ArrayPrototypeFilter,
   ArrayPrototypePush,
   ArrayPrototypeSlice,
   Error,
   FunctionPrototypeBind,
   FunctionPrototypeCall,
+  ObjectAssign,
   ObjectDefineProperty,
   ObjectGetOwnPropertyDescriptor,
   ObjectGetPrototypeOf,
@@ -33,6 +35,7 @@ const {
   URLParse,
 } = require('internal/url');
 const {
+  deprecateProperty,
   emitExperimentalWarning,
   getStructuredStack,
   kEmptyObject,
@@ -61,6 +64,14 @@ const kSupportedFormats = [
   'module',
 ];
 let sharedModuleState;
+const deprecateNamedExports = deprecateProperty(
+  'namedExports',
+  'mock.module(): options.namedExports is deprecated. Use options.exports instead.',
+);
+const deprecateDefaultExport = deprecateProperty(
+  'defaultExport',
+  'mock.module(): options.defaultExport is deprecated. Use options.exports.default instead.',
+);
 const {
   hooks: mockHooks,
   mocks,
@@ -185,20 +196,16 @@ class MockModuleContext {
     baseURL,
     cache,
     caller,
-    defaultExport,
     format,
     fullPath,
-    hasDefaultExport,
-    namedExports,
+    moduleExports,
     sharedState,
     specifier,
   }) {
     const config = {
       __proto__: null,
       cache,
-      defaultExport,
-      hasDefaultExport,
-      namedExports,
+      moduleExports,
       caller,
     };
 
@@ -230,8 +237,8 @@ class MockModuleContext {
         __proto__: null,
         url: baseURL,
         cache,
-        exportNames: ObjectKeys(namedExports),
-        hasDefaultExport,
+        exportNames: ArrayPrototypeFilter(ObjectKeys(moduleExports), (k) => k !== 'default'),
+        hasDefaultExport: 'default' in moduleExports,
         format,
         localVersion,
         active: true,
@@ -241,8 +248,7 @@ class MockModuleContext {
     delete Module._cache[fullPath];
     sharedState.mockExports.set(baseURL, {
       __proto__: null,
-      defaultExport,
-      namedExports,
+      moduleExports,
     });
   }
 
@@ -627,14 +633,9 @@ class MockTracker {
     debug('module mock entry, specifier = "%s", options = %o', specifier, options);
 
     const {
-      cache = false,
-      namedExports = kEmptyObject,
-      defaultExport,
-    } = options;
-    const hasDefaultExport = 'defaultExport' in options;
-
-    validateBoolean(cache, 'options.cache');
-    validateObject(namedExports, 'options.namedExports');
+      cache,
+      moduleExports,
+    } = normalizeModuleMockOptions(options);
 
     const sharedState = setupSharedModuleState();
     const mockSpecifier = StringPrototypeStartsWith(specifier, 'node:') ?
@@ -673,11 +674,9 @@ class MockTracker {
       baseURL: baseURL.href,
       cache,
       caller,
-      defaultExport,
       format,
       fullPath,
-      hasDefaultExport,
-      namedExports,
+      moduleExports,
       sharedState,
       specifier: mockSpecifier,
     });
@@ -816,6 +815,73 @@ class MockTracker {
   }
 }
 
+function normalizeModuleMockOptions(options) {
+  const { cache = false } = options;
+  validateBoolean(cache, 'options.cache');
+
+  const hasExports = 'exports' in options;
+  const hasNamedExports = 'namedExports' in options;
+  const hasDefaultExport = 'defaultExport' in options;
+
+  deprecateNamedExports(options);
+  deprecateDefaultExport(options);
+
+  const moduleExports = { __proto__: null };
+
+  if (hasExports) {
+    validateObject(options.exports, 'options.exports');
+  }
+
+  if (hasNamedExports) {
+    validateObject(options.namedExports, 'options.namedExports');
+  }
+
+  if (hasExports && (hasNamedExports || hasDefaultExport)) {
+    let reason = "cannot be used with 'options.namedExports'";
+
+    if (hasDefaultExport) {
+      reason = hasNamedExports ?
+        "cannot be used with 'options.namedExports' or 'options.defaultExport'" :
+        "cannot be used with 'options.defaultExport'";
+    }
+
+    throw new ERR_INVALID_ARG_VALUE('options.exports', options.exports, reason);
+  }
+
+  if (hasExports) {
+    copyOwnProperties(options.exports, moduleExports);
+  }
+
+  if (hasNamedExports) {
+    copyOwnProperties(options.namedExports, moduleExports);
+  }
+
+  if (hasDefaultExport) {
+    ObjectDefineProperty(
+      moduleExports,
+      'default',
+      ObjectAssign({ __proto__: null }, ObjectGetOwnPropertyDescriptor(options, 'defaultExport')),