test_runner: add exports option to mock.module by Han5991 · Pull Request #61727 · nodejs/node

Han5991 · 2026-02-08T00:25:31Z

Summary

add mock.module(..., { exports }) and normalize option shapes through a shared exports path
keep defaultExport and namedExports as aliases, and emit runtime DeprecationWarning when legacy options are used
update docs, tests, and output fixtures/snapshots to reflect deprecation signaling and the new preferred option shape

Legacy Option Mixing Behavior

Mixed usage of options.exports with legacy options is currently allowed.
Values are normalized/merged into the same internal exports structure.
Legacy options are deprecated, but still supported for compatibility during migration.

Scope

This PR is intentionally scoped to Step 2 of the mock.module: consolidate defaultExport + namedExports into exports #58443 plan.
Userland migration tooling and legacy option removal are deferred to follow-up work.

Testing

make lint-js
python3 tools/test.py test/parallel/test-runner-module-mocking.js
python3 tools/test.py test/test-runner/test-output-coverage-with-mock.mjs test/test-runner/test-output-typescript-coverage.mjs

Refs: #58443

nodejs-github-bot · 2026-02-08T00:25:36Z

Review requested:

@nodejs/test_runner

JakobJingleheimer · 2026-02-08T00:57:50Z

Related: #58443

(I haven't read through this PR yet though)

Han5991 · 2026-02-08T01:04:52Z

Related: #58443

(I haven't read through this PR yet though)

@JakobJingleheimer

I was working on it with that in mind.
I'm planning to proceed only up to Step 2 of the plan. Is that okay?

JakobJingleheimer · 2026-02-08T01:20:55Z

Yes, sounds good go me!

It would be ideal (but not required or anything) to land this with a userland migration ready to go. I think it could be done fairly easily.

Cc @Ceres6 this should make your Jest → node:test migration easier 🙂

Han5991 · 2026-02-08T01:26:42Z

Thanks for the feedback. I will scope this PR to Step 2 of the plan: introduce options.exports, keep defaultExport/namedExports as aliases (with deprecation signaling), and defer userland migration + removal to follow-up work.

codecov · 2026-02-08T02:44:20Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.72%. Comparing base (0777dcc) to head (13b13b8).
⚠️ Report is 124 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #61727      +/-   ##
==========================================
- Coverage   89.73%   89.72%   -0.01%     
==========================================
  Files         675      676       +1     
  Lines      204525   206034    +1509     
  Branches    39310    39499     +189     
==========================================
+ Hits       183529   184865    +1336     
- Misses      13287    13302      +15     
- Partials     7709     7867     +158

Files with missing lines	Coverage Δ
lib/internal/test_runner/mock/loader.js	`99.35% <100.00%> (ø)`
lib/internal/test_runner/mock/mock.js	`98.78% <100.00%> (+0.05%)`	⬆️

... and 182 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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: nodejs#58443

JakobJingleheimer

Thanks for picking this up!

doc/api/test.md

lib/internal/test_runner/mock/mock.js

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

JakobJingleheimer · 2026-02-25T20:55:55Z

lib/internal/test_runner/mock/mock.js

+  if ('exports' in options) {
+    validateObject(options.exports, 'options.exports');
+    copyOwnProperties(options.exports, moduleExports);
+  }


Since last-wins, I think the "new" should win (and be moved below namedExports and defaultExport copying).

Or maybe when exports exists, the others should be ignored? I feel like there's some kind of back-version compatibility thing here. @ljharb thoughts?

lib/internal/test_runner/mock/mock.js

JakobJingleheimer · 2026-02-25T21:07:49Z

lib/internal/test_runner/mock/mock.js

+    copyOwnProperties(options.namedExports, moduleExports);
+  }
+
+  if ('defaultExport' in options) {
+    emitLegacyMockOptionWarning('defaultExport');
+    moduleExports.default = options.defaultExport;


namedExports copies the descriptors, but defaultExport does direct assignment. Why the difference?

The difference is intentional — namedExports copies descriptors of the properties of the provided object (so getters/setters are preserved per export slot), while defaultExport receives the value itself, not an
object whose property structure matters. Copying ObjectGetOwnPropertyDescriptor(options, 'defaultExport') is semantically equivalent to direct assignment in practice. That said, if you'd prefer we align the two
for visual consistency, happy to apply ObjectDefineProperty for defaultExport as well.

I think that's only true for the original module. MockModuleOptions.defaultExport could be a getter:

mock.module('…', { get defaultExport() { return mock.fn() }, });

But I see you already made the switch to ObjectDefineProperty + ObjectGetOwnPropertyDescriptor.

Could you please add a test-case to cover this scenario so nobody comes along in future and unwittingly breaks that?

Rename the named export in the mock.module() example from `fn` to `foo` for improved readability.

- Unify internal export representation into a single `moduleExports` object, removing the split into `defaultExport`, `hasDefaultExport`, and `namedExports`. - DRY up `emitLegacyMockOptionWarning` with a lookup map instead of a switch statement with separate flag variables. - Use `ObjectDefineProperty` for `defaultExport` option to be consistent with descriptor copying in `namedExports`.

JakobJingleheimer

I think this is looking pretty good :)

lib/internal/test_runner/mock/mock.js

JakobJingleheimer · 2026-02-26T17:28:08Z

lib/internal/test_runner/mock/mock.js

+    copyOwnProperties(options.namedExports, moduleExports);
+  }
+
+  if ('defaultExport' in options) {
+    emitLegacyMockOptionWarning('defaultExport');
+    moduleExports.default = options.defaultExport;


I think that's only true for the original module. MockModuleOptions.defaultExport could be a getter:

mock.module('…', { get defaultExport() { return mock.fn() }, });

But I see you already made the switch to ObjectDefineProperty + ObjectGetOwnPropertyDescriptor.

Could you please add a test-case to cover this scenario so nobody comes along in future and unwittingly breaks that?

avivkeller · 2026-02-26T20:51:05Z

doc/api/test.md

+    This option is deprecated and will be removed in a future major release.
+    Prefer `options.exports.default`.


Do we need to wait for a future major release? the feature is experimental and may not follow Semver?

True. This could probably be more vague, like "a later version".

avivkeller · 2026-02-26T20:53:17Z

lib/internal/test_runner/mock/mock.js

+function emitLegacyMockOptionWarning(option) {
+  if (warnedLegacyOptions[option]) return;
+  warnedLegacyOptions[option] = true;
+  process.emitWarning(
+    `mock.module(): options.${option} is deprecated. ` +
+    `Use ${kLegacyOptionReplacements[option]} instead.`,
+    'DeprecationWarning',
+  );
+}


lib/internal/util provides a deprecateProperty utility. Can't we use that?

nodejs-github-bot added needs-ci PRs that need a full CI run. test_runner Issues and PRs related to the test runner subsystem. labels Feb 8, 2026

Han5991 marked this pull request as draft February 8, 2026 00:27

Han5991 force-pushed the test-runner-mock-exports branch from 3d95c0c to fa99ada Compare February 8, 2026 00:35

Han5991 force-pushed the test-runner-mock-exports branch from 73c4cf1 to 715c12c Compare February 8, 2026 01:11

Han5991 marked this pull request as ready for review February 8, 2026 01:33

jasnell approved these changes Feb 8, 2026

View reviewed changes

Han5991 force-pushed the test-runner-mock-exports branch from 715c12c to 424675e Compare February 8, 2026 02:47

Han5991 force-pushed the test-runner-mock-exports branch from 424675e to 0498de3 Compare February 8, 2026 07:24

JakobJingleheimer reviewed Feb 25, 2026

View reviewed changes

Han5991 added 2 commits February 26, 2026 23:05

doc: improve mock.module example clarity

f956d87

Rename the named export in the mock.module() example from `fn` to `foo` for improved readability.

JakobJingleheimer reviewed Feb 26, 2026

View reviewed changes

avivkeller reviewed Feb 26, 2026

View reviewed changes

		This option is deprecated and will be removed in a future major release.
		Prefer `options.exports.default`.

Uh oh!

Conversation

Han5991 commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Legacy Option Mixing Behavior

Scope

Testing

Uh oh!

nodejs-github-bot commented Feb 8, 2026

Uh oh!

JakobJingleheimer commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Han5991 commented Feb 8, 2026

Uh oh!

JakobJingleheimer commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Han5991 commented Feb 8, 2026

Uh oh!

codecov bot commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

JakobJingleheimer left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JakobJingleheimer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Han5991 commented Feb 8, 2026 •

edited

Loading

JakobJingleheimer commented Feb 8, 2026 •

edited

Loading

JakobJingleheimer commented Feb 8, 2026 •

edited

Loading

codecov bot commented Feb 8, 2026 •

edited

Loading

JakobJingleheimer left a comment •

edited

Loading