[SimenB]

Summary

A review pass of jest-runtime against Node v26.7.0, follow-up to #16389. The PR grew through several review rounds; this describes the result as a whole.

Automocking and manual __mocks__ files for ESM

Any factory-less ESM mock decision used to crash with Attempting to import a mock without a factory - automock: true made every ESM import fail. On Node 24.9+ the ESM loader now mirrors the CJS mock machinery: a root or sibling __mocks__ file loads as the mock (in its own format, resolved with import conditions), otherwise the real module loads in scratch registries and an automock is generated from its namespace. This covers static imports, dynamic import(), require(esm) and data: URIs, with the usual escape hatches intact: jest.requireActual, unmockedModulePathPatterns, and jest.unmock/jest.deepUnmock - whose CJS decisions, including deepUnmock's transitive scope, block a generated ESM mock. A registered unstable_mockModule factory still wins, since unmocking those is unstable_unmockModule's job.

The details that took iteration to get right:

• The CJS require() machinery routes ESM targets to the ESM loader - including unmarked ESM, .js files whose transformed source has ESM syntax in a CommonJS package - so an .mjs manual mock is never compiled as CommonJS and a factory-less jest.mock('./esm.mjs') automocks instead of returning the real module.
• require() and import share one mock instance whenever both condition sets resolve to the same file; a conditional package whose require/module-sync and import conditions diverge gets a mock of the file each entry point actually resolves - including its sibling __mocks__ file.
• Automock metadata loads the real cyclic graph without recursively automocking its deps, so a synchronously evaluable a.mjs <-> b.mjs cycle links instead of failing on an empty placeholder.
• Metadata generation waits for the importing graph to resolve, so a resolution or import-attribute error surfaces before any real module executes.
• Import attributes validate against the resolved target, so an automocked JSON module reached through an extensionless specifier still passes with { type: 'json' }.
• Known hole, documented in code and docs: graphs that need async evaluation (top-level await), async-only resolvers or transformers, resolvers with distinct sync and async hooks, and Node < 24.9 still throw - serving those needs an async twin of the generated-mock path.

Node parity in the sandbox

• process.getBuiltinModule was the host function by reference: it returned the host process (Node guarantees process.getBuiltinModule('process') === process) and the host node:module, whose createRequire escapes Jest's registry, mocks and transforms. It now dispatches through the requireModule override seam.
• module.register() and module.registerHooks() attached hooks to the loader running Jest itself - they observed Jest's internal requires, never the sandboxed ones, and persisted across test files in the worker. Both now throw an actionable error, alongside the existing syncBuiltinESMExports no-op.

Graph errors surface before anything executes

Building a CJS dep's synthetic executes its body (the export-name merge needs the runtime exports object), and the walker built it the moment the specifier resolved - so import './side-effect.cjs'; import './missing.js'; ran the side effect before erroring, unlike Node's resolve-everything-first loader. CJS builds, automock generation and registered sync mock factories now all defer until the resolution worklist drains; unmarked-ESM files are classified without execution by probing hasEsmSyntax on the transformed source, and a file both parsers reject still surfaces the canonical compile error. Applies to the sync graph walker (Node 24.9+); the legacy loader keeps its linking-time order, as documented.

Resolvers with distinct sync and async hooks

Resolver#hasDistinctAsyncResolver() (new in jest-resolve) reports when a configured resolver exports both a sync and an async hook. Such a resolver never enters a sync-preferred walk: even its successful sync resolutions may disagree with the async hook that resolveModuleAsync selects for imports. require() keeps the sync hook, since it cannot await; mock generation on the async path resolves through the async API before generating; and a mock generated for require() is not reused by a later import.

Source phase imports

import source / import.source() (shipped unflagged in Node for WebAssembly) failed at instantiation with V8's bare Source phase import object is not defined pointing at Jest internals. Node satisfies the phase via the internal ModuleWrap#setModuleSourceObject; node:vm exposes no equivalent, so the phase cannot be implemented on the vm-based loader. Source-phase requests now throw ERR_SOURCE_PHASE_NOT_DEFINED with the gap explained - in the sync walker, the legacy loader, and the dynamic-import callbacks (ESM and CJS alike, which receive the phase as a fourth argument).

require.cache stays path-addressed

Object.keys(require.cache) leaked raw mock-ID strings, @jest/globals synthetics and core specifiers. Mock modules no longer enter the ESM registry (they are served from the module-mock registry), and the proxy answers only for absolute-path keys - Node lists absolute file paths only.

Cleanup

• import.meta.resolve's divergence from Node (the full jest-resolve pipeline answers, resolution-only in Node) is pinned in a comment.
• data: URI decoding and import-attribute validation moved out of EsmLoader into dataUri.ts and importAttributes.ts. The attribute validator's warned-pairs set moved from module scope to the instance, so the JSON-without-attribute deprecation warning fires once per test file instead of once per worker.
• The ESM docs gained the new divergences and the automock section.

Test plan

~65 new regression tests across runtime_esm_sync_graph.test.ts, runtime_environment.test.js, cjsRequire.test.ts, resolve.test.ts and the extracted importAttributes.test.ts, backed by new fixtures (conditional packages, dual- and disagreeing-hook resolvers, root/sibling mocks, cycles, data: URIs, source-phase imports). Every fix was reproduced against the built CLI before the change and re-run after, with plain node output as the baseline where Node has the behavior natively. yarn jest packages/jest-runtime, yarn jest-runtime-vm-modules, yarn typecheck:tests and yarn lint are green on Node v26.7.0.

[netlify]

✅ Deploy Preview for jestjs ready!

Name	Link
🔨 Latest commit	2385310
🔍 Latest deploy log	https://app.netlify.com/projects/jestjs/deploys/6a88b4c8c4b1d200087c8ddb
😎 Deploy Preview	https://deploy-preview-16391--jestjs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

Improves jest-runtime ESM parity with Node by supporting automocks, sandboxing loader APIs, preserving graph-error ordering, and clarifying unsupported source-phase imports.

Changes:

• Adds ESM automock and manual mock generation.
• Sandboxes builtin-module access and rejects unsafe loader hooks.
• Defers CJS execution and adds source-phase/import-attribute handling.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
CHANGELOG.md	Records runtime changes.
docs/ECMAScriptModules.md	Documents ESM behavior and divergences.
eslint.config.mjs	Excludes unsupported source-phase syntax.
packages/jest-runtime/src/index.ts	Wires ESM loading and sandbox builtins.
packages/jest-runtime/src/internals/EsmLoader.ts	Implements primary ESM behavior changes.
packages/jest-runtime/src/internals/ModuleExecutor.ts	Propagates dynamic import phases.
packages/jest-runtime/src/internals/MockState.ts	Supports metadata rollback.
packages/jest-runtime/src/internals/cjsRequire.ts	Rejects host loader hooks.
packages/jest-runtime/src/internals/dataUri.ts	Extracts data URI parsing.
packages/jest-runtime/src/internals/importAttributes.ts	Extracts instance-scoped validation.
packages/jest-runtime/src/internals/__tests__/EsmLoader.test.ts	Updates loader test setup.
packages/jest-runtime/src/internals/__tests__/cjsRequire.test.ts	Tests hook rejection.
packages/jest-runtime/src/internals/__tests__/importAttributes.test.ts	Tests attribute validation.
packages/jest-runtime/src/__tests__/runtime_environment.test.js	Tests sandbox builtin access.
packages/jest-runtime/src/__tests__/runtime_esm_sync_graph.test.ts	Tests automock, graph errors, and phases.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/automock-cjs-dep.cjs	Provides CJS automock fixture.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/automock-dep.mjs	Provides ESM automock fixture.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/automock-dynamic.mjs	Provides dynamic import fixture.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/automock-manual-dep.mjs	Provides real manual-mock target.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/__mocks__/automock-manual-dep.mjs	Provides manual ESM mock.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/cjs-sideeffect.cjs	Tracks premature CJS execution.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/dynamic-source-phase.mjs	Exercises import.source().
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/import-automock-cjs-dep.mjs	Imports an automocked CJS dependency.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/import-automock-dep.mjs	Imports an automocked ESM dependency.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/import-cjs-bad-attribute.mjs	Tests attribute-error ordering.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/import-cjs-then-missing.mjs	Tests resolution-error ordering.
packages/jest-runtime/src/__tests__/test_esm_sync_graph_root/import-source-phase.mjs	Exercises static source imports.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[pkg-pr-new]

Open in StackBlitz

babel-jest

npm i https://pkg.pr.new/babel-jest@16391

babel-plugin-jest-hoist

npm i https://pkg.pr.new/babel-plugin-jest-hoist@16391

babel-preset-jest

npm i https://pkg.pr.new/babel-preset-jest@16391

create-jest

npm i https://pkg.pr.new/create-jest@16391

@jest/diff-sequences

npm i https://pkg.pr.new/@jest/diff-sequences@16391

expect

npm i https://pkg.pr.new/expect@16391

@jest/expect-utils

npm i https://pkg.pr.new/@jest/expect-utils@16391

jest

npm i https://pkg.pr.new/jest@16391

jest-changed-files

npm i https://pkg.pr.new/jest-changed-files@16391

jest-circus

npm i https://pkg.pr.new/jest-circus@16391

jest-cli

npm i https://pkg.pr.new/jest-cli@16391

jest-config

npm i https://pkg.pr.new/jest-config@16391

@jest/console

npm i https://pkg.pr.new/@jest/console@16391

@jest/core

npm i https://pkg.pr.new/@jest/core@16391

@jest/create-cache-key-function

npm i https://pkg.pr.new/@jest/create-cache-key-function@16391

jest-diff

npm i https://pkg.pr.new/jest-diff@16391

jest-docblock

npm i https://pkg.pr.new/jest-docblock@16391

jest-each

npm i https://pkg.pr.new/jest-each@16391

@jest/environment

npm i https://pkg.pr.new/@jest/environment@16391

jest-environment-jsdom

npm i https://pkg.pr.new/jest-environment-jsdom@16391

@jest/environment-jsdom-abstract

npm i https://pkg.pr.new/@jest/environment-jsdom-abstract@16391

jest-environment-node

npm i https://pkg.pr.new/jest-environment-node@16391

@jest/expect

npm i https://pkg.pr.new/@jest/expect@16391

@jest/fake-timers

npm i https://pkg.pr.new/@jest/fake-timers@16391

@jest/get-type

npm i https://pkg.pr.new/@jest/get-type@16391

@jest/globals

npm i https://pkg.pr.new/@jest/globals@16391

jest-haste-map

npm i https://pkg.pr.new/jest-haste-map@16391

jest-jasmine2

npm i https://pkg.pr.new/jest-jasmine2@16391

jest-leak-detector

npm i https://pkg.pr.new/jest-leak-detector@16391

jest-matcher-utils

npm i https://pkg.pr.new/jest-matcher-utils@16391

jest-message-util

npm i https://pkg.pr.new/jest-message-util@16391

jest-mock

npm i https://pkg.pr.new/jest-mock@16391

@jest/pattern

npm i https://pkg.pr.new/@jest/pattern@16391

jest-phabricator

npm i https://pkg.pr.new/jest-phabricator@16391

jest-regex-util

npm i https://pkg.pr.new/jest-regex-util@16391

@jest/reporters

npm i https://pkg.pr.new/@jest/reporters@16391

jest-resolve

npm i https://pkg.pr.new/jest-resolve@16391

jest-resolve-dependencies

npm i https://pkg.pr.new/jest-resolve-dependencies@16391

jest-runner

npm i https://pkg.pr.new/jest-runner@16391

jest-runtime

npm i https://pkg.pr.new/jest-runtime@16391

@jest/schemas

npm i https://pkg.pr.new/@jest/schemas@16391

jest-snapshot

npm i https://pkg.pr.new/jest-snapshot@16391

@jest/snapshot-utils

npm i https://pkg.pr.new/@jest/snapshot-utils@16391

@jest/source-map

npm i https://pkg.pr.new/@jest/source-map@16391

@jest/test-result

npm i https://pkg.pr.new/@jest/test-result@16391

@jest/test-sequencer

npm i https://pkg.pr.new/@jest/test-sequencer@16391

@jest/transform

npm i https://pkg.pr.new/@jest/transform@16391

@jest/types

npm i https://pkg.pr.new/@jest/types@16391

jest-util

npm i https://pkg.pr.new/jest-util@16391

jest-validate

npm i https://pkg.pr.new/jest-validate@16391

jest-watcher

npm i https://pkg.pr.new/jest-watcher@16391

jest-worker

npm i https://pkg.pr.new/jest-worker@16391

pretty-format

npm i https://pkg.pr.new/pretty-format@16391

commit: 2385310

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated no new comments.

Suppressed comments (5)

packages/jest-runtime/src/internals/EsmLoader.ts:1075

• This eagerly builds a factory-less automock while the graph is still resolving, and automock generation executes the real target to collect metadata. With automock: true, a graph that imports a side-effecting CJS module before a missing sibling will therefore run that CJS body before the later resolution error; an invalid attribute is also validated only after this call. Defer mock generation until all requests have resolved and their attributes have been validated, just as the new pending-CJS path does.

      const mocked = this.importMockSync(
        referencingIdentifier,
        specifierPath,
        moduleID,
        context,

packages/jest-runtime/src/index.ts:480

• A normal CommonJS require() enters requireModuleOrMock() and _requireMockWithId(). When a sibling manual mock exists, the branch at line 463 loads that .mjs file directly through CjsLoader.loadModule, so this new ESM delegation is never reached and the manual mock is compiled as CommonJS. The added test calls runtime.requireModule() directly and therefore misses the user-facing path. Route ESM manual mocks through the ESM loader as well, and cover requireModuleOrMock() so documented require() support works.

      mockRegistry.set(moduleID, this._generateMockForTarget(from, moduleName));

CHANGELOG.md:14

• The release note promises this for ESM generally, but the new fallback explicitly still throws when the target graph requires async evaluation (for example, top-level await) on Node 24.9+. Qualify the entry to synchronously evaluable ESM graphs unless the async generated-mock path is implemented.

- `[jest-runtime]` Apply automocking and manual `__mocks__` files to ESM on Node 24.9+ - static imports, dynamic `import()` and `require()` of an ESM file now generate an automock from the real module's namespace instead of failing with "Attempting to import a mock without a factory" ([#16391](https://github.com/jestjs/jest/pull/16391))

packages/jest-runtime/src/internals/tests/EsmLoader.test.ts:88

• Avoid the untyped any cast for this new mock; it discards the requireModule signature and can hide incorrect calls in these loader tests. Instantiate jest.fn with the function type, matching the repository's typed-mock requirement.

    requireModule: jest.fn() as any,

docs/ECMAScriptModules.md:85

• This statement is broader than the implementation: importMock() still throws Attempting to import a mock without a factory when the real module graph requires async evaluation, including top-level await (EsmLoader.ts:2072-2078), even on Node 24.9+. Either implement the async generated-mock path or document that support is limited to synchronously evaluable ESM graphs.

On Node 24.9+, [automocking](Configuration.md#automock-boolean) and manual `__mocks__` files also apply to ESM: an automock is generated from the real module's namespace, and a sibling `__mocks__` file replaces it, for static imports, dynamic `import()` and `require()` alike.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

packages/jest-runtime/src/index.ts:517

• Runtime is a public subclassing extension point, but this callback bypasses an overridden requireModule and calls the internal provider directly. Consequently process.getBuiltinModule() behaves differently from require() for consumers that customize module loading through the documented override seam. Dispatch the builtin through this.requireModule(this._testPath, id) instead.

    sandboxProcess.getBuiltinModule = (id: string) =>
      nativeModule.isBuiltin(id) ? this.coreModule.require(id) : undefined;

packages/jest-runtime/src/internals/EsmLoader.ts:1173

• A configured resolver may legitimately export distinct sync and async hooks; canResolveSync() only confirms that sync exists, while resolveModuleAsync explicitly prefers the separate async hook. Making the sync failure authoritative therefore regresses dynamic imports whose sync hook cannot resolve a specifier but whose async hook can. Preserve the legacy fallback for dual-hook resolvers (while keeping failures authoritative for default/sync-only resolvers), which likely requires exposing whether a distinct async hook is configured.

    // Both walker entries gate on `canResolveSync()`, so the sync resolver's
    // failure is authoritative in either mode - the async resolver runs the
    // same algorithm. Bailing to the legacy path instead would execute
    // already-resolved CJS deps before rediscovering the same error, where
    // Node runs nothing when the graph fails to resolve.
    const resolved = this.resolution.resolveEsm(
      referencingIdentifier,
      specifierPath,
    );

[Copilot]

Pull request overview

Copilot reviewed 60 out of 70 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

packages/jest-resolve/src/resolver.ts:432

• An async-only resolver also satisfies this condition, so hasDistinctAsyncResolver() returns true even though there is no sync interface to differ from. That contradicts the method's documented contract; require both hooks here (and cover the existing async-only resolver fixture in the test).

      result =
        typeof resolverModule !== 'function' &&
        typeof resolverModule.async === 'function';

[Copilot]

Pull request overview

Copilot reviewed 62 out of 72 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 63 out of 73 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

packages/jest-runtime/src/internals/EsmLoader.ts:1374

• jest.deepUnmock() is recorded only in the CJS transitive map, but this bridge checks only the root's explicit-unmock bit. The root ESM module therefore loads for real while its ESM dependencies are still automocked, violating deepUnmock's documented guarantee that the module and its dependencies remain real. Propagate the CJS transitive-unmock state to the corresponding ESM module ID before walking the real graph.
  packages/jest-runtime/src/internals/EsmLoader.ts:2247
• This distinct-resolver guard is bypassed when a module mock already exists: importMock returns the cached entry above before reaching this branch. If require() first generated that entry with the sync hook, a later dynamic import reuses the sync target's mock even when the async hook resolves the same specifier elsewhere, contradicting the documented factory-less-mock exclusion for dual-hook resolvers. Apply the distinct-resolver check before reusing a cached generated mock (registered factories can still be reused).

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.