@jest/pattern

On a personal note: King Harald V of Norway passed away this morning. He ascended the throne 35 years ago, two months before I was born. This release is dedicated to his memory. Hvil i fred 🇳🇴

This is a big release. It touches jest-runtime, jest-resolve and jest-haste-map in many places, and with this many changes there might be regressions 😬. If your suite behaves differently after upgrading, please open an issue.

Highlights

whenCalledWith

Mock functions can now configure return values per argument list, contributed by @timkindberg (#16053):

const fn = jest.fn();
fn.whenCalledWith('apple').mockReturnValue('red');
fn.whenCalledWith('banana').mockReturnValue('yellow');
fn.whenCalledWith(expect.any(Number)).mockReturnValue('numeric');

fn('apple'); // 'red'
fn('banana'); // 'yellow'
fn(42); // 'numeric'
fn('grape'); // undefined

The returned object is a real Mock, so mockReturnValueOnce, mockResolvedValue, mockImplementation etc. all chain here too. Argument slots accept literals or any asymmetric matcher, with the same equality semantics as toHaveBeenCalledWith(). Calls that match nothing fall through to the base mock. See the Mock Functions docs for matching and precedence details.

Describe-level retries

jest.retryTimes() can now retry a whole describe block instead of a single test, contributed by @soltonigiri (#16322). Each attempt reruns the block's beforeAll/afterAll hooks, child tests and nested describes, which helps when tests in a block depend on shared state:

describe('workflow', () => {
  jest.retryTimes(3, {entireDescribe: true});

  test('first step', () => {});
  test('second step', () => {}); // a failure retries the entire block
});

New file watcher

The non-watchman path of jest-haste-map is rewritten. @parcel/watcher replaces the homegrown NodeWatcher and FSEventsWatcher (#16188), and fdir replaces the hand-rolled directory recursion in the crawler (#16187). A batch of fixes also makes watching and indexing survive locked files on Windows, watchman failures, and duplicate manual mocks (#16295, #16358, #16355, #16360).

If you can, please run your suite with --no-watchman (in and out of watch mode) to exercise the new crawler and watchers, and report anything odd 👍

Long-requested dependency updates

• babel-plugin-istanbul is updated to v8

• glob is updated to v13

• source-map-support is replaced with an implementation in @jest/source-map (#16327). This fixes a memory leak where source-map-support's process-global caches pinned every finished test file's sandbox. Source maps also survive environment teardown, --testLocationInResults looks up the right column, and scheme-prefixed sources like webpack:/// are kept as-is.

Performance

• Warm module resolution costs about a third of what it did, and repeated work is gone from the resolution hot path (#16373, #16371).

• Per-require overhead in jest-runtime is cut: module ID resolution is skipped when no mock can apply, and core modules answer before the manual-mock probe (#16376).

• jest-snapshot loads babel, semver and synckit lazily, so every test process loads ~200 fewer modules (#16387).

• jest-haste-map caches the watchman socket path, so warm runs spawn no watchman processes (#16386), and reuses cached metadata for duplicated haste names instead of re-parsing them on every startup (#16351).

More new APIs

• Snapshot failures expose the .snap file path as matcherResult.snapshotPath in failureDetails (#16374).

• --collectTests expands test.each/describe.each cases and reports per-status counts plus a summary line that matches a real run (#16259).

• AggregateError inner errors and nested cause chains render with code frames and per-level indentation, and are included in --json output, retryReasons and reporter annotations (#16316).

ESM

A long list of fixes brings jest-runtime's module system closer to Node's:

• Automocking and manual __mocks__ files now apply to ESM on Node 24.9+. Static imports, dynamic import() and require() of an ESM file generate an automock from the real module's namespace instead of failing with "Attempting to import a mock without a factory" (#16391).

• Many jest.unstable_mockModule gaps are closed: mocks apply when the mocked file is require()d directly, async factories run once and fail the import instead of crashing the worker 😅, and mocks made inside jest.isolateModules stay scoped to that block (#16389, #16365).

• require(esm), CJS/ESM interop, import.meta, data: URIs and error ordering now match Node in dozens of edge cases. See the Fixes section for the full list (#16364 through #16391).

• The module-sync export condition resolves, so packages that expose their ESM entry point for require() load the same file Node picks (#16336).

The intentional divergences from Node's module system are now documented on the ECMAScript Modules page (#16368).

Resolver

• The default resolver honors Node's --preserve-symlinks / NODE_PRESERVE_SYMLINKS (#16260).

• moduleNameMapper applies to both spellings of core module specifiers (fs and node:fs), and builtins that only exist prefixed (node:sqlite, node:test) resolve asynchronously (#16390, #16388).

• A user resolver can be written as an ES module (#16332).

On top of the highlights there are ~60 fixes across jest-circus, jest-haste-map, jest-config, jest-mock and the transform cache keys. See the full changelog below 😀

Features

• @jest/expect-utils, jest-mock: Add mockFn.whenCalledWith(...args) for configuring return values per argument list, with first-class asymmetric-matcher support

• @jest/expect-utils: Export AsymmetricMatcher and FunctionParameters types (previously private to expect)

• [jest-circus, jest-core, jest-jasmine2, jest-test-result, jest-types] --collectTests now expands test.each/describe.each cases and reports per-status counts (skipped/todo via the new wouldRun flag for selected tests) plus a summary line that match a real run, including under --testNamePattern and .only/fdescribe focus on both the circus and jasmine2 runners

• [jest-circus, jest-environment, jest-runtime, jest-types] Add describe-level retries via jest.retryTimes(..., {entireDescribe: true})

• [jest-circus, jest-message-util, jest-reporters, jest-types] Add retryMessages to AssertionResult and export formatErrorStack, so the retry log renders nested cause and AggregateError sections with code frames instead of serialized [cause]:/[errors]: markers

• jest-circus, jest-types: Add unhandledErrorsDetailed to Circus.RunResult, so an unhandled rejection reports its cause chain and AggregateError entries with code frames instead of a pre-serialized stack

• jest-haste-map: Replace NodeWatcher and FSEventsWatcher with @parcel/watcher for the non-watchman watch path

• jest-resolve: Bump unrs-resolver to 1.12.1, remove jest-pnp-resolver and unnecessary checks

• jest-resolve: Honor Node's --preserve-symlinks / NODE_PRESERVE_SYMLINKS in the default resolver by passing symlinks: false to unrs-resolver

• jest-runtime: Apply automocking and manual __mocks__ files to synchronously evaluable ESM graphs 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". Graphs that need async evaluation (top-level await) or an async-only resolver or transformer still throw

• jest-runtime: Route process.getBuiltinModule through the sandbox, so it returns the sandbox process and the hooked node:module instead of the host's

• jest-runtime: Throw an actionable error from module.register() and module.registerHooks() inside a test - the hooks attached to the loader running Jest itself, never saw the sandboxed requires they were meant for, and stayed registered for every later test file in the worker

• jest-runtime: Surface resolution and import-attribute errors in an ESM graph before executing any of its CJS dependencies on Node 24.9+, matching Node's run-nothing-on-a-broken-graph behavior; the legacy loader on older versions keeps its linking-time execution order

• jest-runtime: Throw ERR_SOURCE_PHASE_NOT_DEFINED with an actionable message for import source and import.source(), instead of failing at instantiation with V8's bare "Source phase import object is not defined"

• jest-runtime: Emit the JSON-without-import-attribute deprecation warning once per test file instead of once per worker, so it is no longer silently swallowed for every file after the first

• jest-runtime: Set import.meta.main to true in the test file and false in every module it loads, matching Node 24+

• jest-runtime: Resolve the module-sync export condition, so a package that exposes its ESM entry point for require() loads the same file Node would

• jest-snapshot: Add external snapshot paths to custom reporter failure details

Fixes

• jest-console, jest-reporters: CustomConsole now buffers console output so TestResult.console is populated for reporters when verbose is enabled, while GitHubActionsReporter avoids replaying buffered output in verbose mode

• [expect, jest-message-util, jest-pattern, jest-regex-util, jest-util] Revert node: protocol imports to restore webpack/browser-bundle compatibility

• expect: Widen toMatchObject and objectContaining parameter type from Record<string, unknown> to object so class instances are accepted

• jest-circus: Call a generator test body with the shared test context, so this matches what a regular test function receives

• jest-circus: Capture the error listeners of the parent process instead of the in-sandbox process, so listeners registered before the test file survive teardown and sandbox listeners no longer leak onto the parent

• jest-circus: Clear currentlyRunningTest after skipped and todo tests

• jest-circus: Prevent late done() callbacks from affecting later test or hook invocations

• jest-circus, jest-jasmine2: Honor --expand when formatting node:assert failures, instead of always collapsing the diff

• jest-circus, jest-jasmine2, jest-message-util: Serialize the inner errors of an AggregateError into failureMessages, retryReasons and unhandledErrors, so --json output and reporter annotations include them

• jest-circus, jest-snapshot: Keep snapshot state and counts correct when a test retries

• @jest/create-cache-key-function: Include the caller support flags in the generated key, so a transformer that emits ESM or CJS based on them no longer shares one cache entry between the two

• @jest/create-cache-key-function: Include the stringified project config in the generated key, so editing a transformer's own settings invalidates what it cached

• @jest/transform: Include the caller support flags in a transform's cache key, so a file transformed both as ESM and as CJS no longer serves one shape's output for the other

• jest-config: Add missing findRelatedTests, outputFile, and replname entries to ValidConfig so they no longer trigger spurious "Unknown option" warnings

• jest-config: Use --config for the global config when multiple --projects are specified

• jest-core: Serialize bigint values in --json and --outputFile output as their literal form (4n), instead of failing the run with TypeError: Do not know how to serialize a BigInt

• jest-core: Do not report a CustomGC async resource (used by N-API addons such as napi-rs for per-isolate GC bookkeeping) as an open handle, since it is napi_unref'd by the addon and can never keep the event loop alive

• jest-each: Keep a $&, $`, $' or $$ inside a %p param value out of the replacement, so the title shows the value instead of the text around it

• jest-each: Interpolate a bigint into a %j title as its literal form ("4n") at any depth, instead of throwing TypeError: Do not know how to serialize a BigInt while collecting the tests

• jest-environment, jest-runtime: Bind sandboxInjectedGlobals to the right values when injectGlobals is false, instead of shifting every one of them by a position

• jest-environment-node, jest-util: Only warn about a conflicting globalsCleanup mode when one was explicitly configured, and follow the mode that is actually in effect

• jest-environment-node, jest-util: Stop resolving lazy globals when setting up an environment, so Node 26's builtin module globals are no longer loaded (and no longer emit their deprecation warnings) for every test file

• jest-haste-map: Keep watch mode alive when an outside process briefly makes a file unreadable on Windows, instead of tearing the watcher down on EPERM

• jest-haste-map: Keep indexing when an outside process holds a file open on Windows, instead of failing the whole crawl on EPERM

• jest-haste-map: Keep a duplicated manual mock resolving when the file it pointed at is deleted in watch mode

• jest-haste-map: Shut the worker farm down when a duplicate manual mock aborts the build under throwOnModuleCollision

• jest-haste-map: Attach the watchman client's error listener before the first command, so a watchman failure falls back to the node crawler instead of crashing on an unhandled error event, and always end the client

• jest-haste-map: Stop delivering watch events after WatchmanWatcher is closed, and route its warnings through the configured console

• jest-haste-map: Restore the nested duplicates index correctly in ModuleMap.fromJSON, so a haste collision reported inside a test worker raises DuplicateHasteCandidatesError instead of a TypeError

• breaking

  jest-haste-map: Match watched files on a full extension, so moduleFileExtensions: ['js'] no longer accepts foo.mjs

• jest-haste-map: Delimit the fields that make up the haste map cache key, so two different option sets cannot hash to the same cache file

• jest-message-util: Print the inner errors of an AggregateError thrown inside a test

• jest-message-util: Indent nested cause and AggregateError sections of a test failure by one level per depth, so the nesting is legible instead of rendering flat

• jest-message-util: Color stack traces line by line so blank lines stay blank

• jest-message-util: Detect Jest's own frames without assuming the checkout directory's name, and cover @jest/* packages, so stack traces and code frames point at user code

• jest-mock: mockResolvedValue / mockRejectedValue now see all overload return types, so a Promise-returning overload survives even when a later overload returns a non-Promise (e.g. pg.Client['end'])

• @jest-environment/jsdom-abstract: Make @types/jsdom a peer dependency

• jest-mock: Remove the leftover own accessor descriptor when restoring a spyOn of an inherited getter or setter, so the instance keeps reflecting the prototype

• jest-resolve: Include extensionsToTreatAsEsm in the shouldLoadAsEsm cache key, so projects with different extension lists don't read each other's answers

• jest-resolve: Make getModuleIDAsync build and cache data: URI module IDs the same way as getModuleID

• jest-resolve: Keep the node: prefix when resolving a core module asynchronously, so a builtin that only exists prefixed (node:sea, node:sqlite, node:test, node:test/reporters) resolves instead of failing as a missing bare package

• jest-resolve: Look up manual mocks for node: protocol specifiers under the unprefixed name they are stored as

• jest-resolve: Apply moduleNameMapper consistently to both spellings of core module specifiers (fs vs node:fs)

• jest-resolve: Keep virtual and ordinary mock module IDs isolated across test files

• jest-resolve: Guard missing require.resolve.paths

• jest-resolve, jest-config, jest-runner: Support a user resolver written as an ES module

• jest-resolve, jest-runtime: Throw the CJS parse error for ESM syntax in a "type": "commonjs" package or a .cjs file instead of loading it as ESM, matching Node

• @jest/source-map: Keep source map sources that name a scheme, such as webpack:///, instead of resolving them into a path that does not exist

• @jest/source-map: Look up --testLocationInResults positions at the right column, and keep a mapping to the first column instead of discarding it

• @jest/source-map: Warn when a source map cannot be parsed, instead of silently leaving its frames untranslated

• jest-runner, @jest/source-map: Keep a source-mapped stack for an error thrown after the test environment was torn down

• jest-runtime, @jest/source-map: Keep source maps past teardown and past the next test file's install, so a stack from a file no earlier stack mentioned still points at the original source

• jest-runtime: Report that no coverage was collected when getAllV8CoverageInfoCopy is called after teardown, instead of returning an empty result

• jest-runtime: Cache a CJS module's parsed exports before walking its re-exports, so two modules that re-export each other no longer overflow the stack when imported from ESM

• jest-runtime: Keep a re-exported ES module's parse failure from marking the re-exporting CommonJS file as ESM, so module.exports = require('./dep.mjs') loads instead of failing with module is not defined

• jest-runtime: Scope module mocks instantiated inside jest.isolateModules/isolateModulesAsync to that block, so a mock first imported there no longer outlives it - matching how CommonJS mocks already behave

• jest-runtime: Suspend module isolation while generating an automock, so loading the real module to read its shape no longer populates the isolated registry

• jest-runtime: Check a cached ES module's status before require() returns it, so a module whose evaluation threw rethrows that error and one left linked by a failed sibling is evaluated instead of returning uninitialized bindings

• jest-runtime: Report the original ERR_REQUIRE_ASYNC_MODULE when a require() of a top-level-await graph is retried, instead of a spurious "concurrent import()" error

• jest-runtime: Throw the evaluation error when another caller's import() of the same module failed while we awaited it, instead of resolving with the errored module

• jest-runtime: Mark the result of require()ing an ES module that has a default export with __esModule: true through a live-binding facade, and serve the same object from require.cache, matching Node

• jest-runtime: Provide a CommonJS module's exports under the 'module.exports' named export when imported from ESM, matching Node 23+

• jest-runtime: Give the test file itself a non-null require.main

• jest-runtime: Populate module.children with the modules a file loads, matching Node

• jest-runtime: Provide import.meta.resolve and import.meta.jest in data: URI modules, accept any-case mediatype parameters, and use Node's error codes for invalid data: URIs

• jest-runtime: Key ES modules by full URL, so query and fragment suffixes create the same module instances as Node and show up in import.meta.url

• jest-runtime: Share modules between overlapping graphs when a CommonJS module require()s an ES module mid-load, instead of evaluating shared dependencies twice

• jest-runtime: Throw ERR_REQUIRE_CYCLE_MODULE like Node when a CommonJS module require()s an ES module that is still being loaded, instead of evaluating the module a second time

• jest-runtime: Key builtin modules in the ESM registry by one canonical specifier

• jest-runtime: import.meta.resolve() for a builtin uses its node: specifier

• jest-runtime: Fall back to native ESM when a .js file contains ESM syntax but has no "type":"module" marker

• jest-runtime: Allow require() of ESM-marked files on Node < 24.9 via transform fallback

• jest-runtime, @jest/transform: Surface actionable ERR_REQUIRE_ESM error for files with untransformed ESM syntax instead of the generic "unexpected token" message

• jest-runtime: Support older test environments whose moduleMocker does not implement clearMocksOnScope

• jest-runtime: Apply jest.unstable_mockModule when the mocked file itself is require()d, not only when it is imported as a dependency

• jest-runtime: Apply jest.unstable_mockModule to statically imported data: URIs on Node 24.9+, matching dynamic import()

• jest-runtime: Run an async jest.unstable_mockModule factory once per module instead of twice, and fail the import instead of crashing the worker when the factory rejects

• jest-runtime: Hide a require(esm) module that failed to evaluate from require.cache, as Node does, instead of exposing a namespace with uninitialized bindings

• jest-runtime: Strip the byte-order mark when importing a JSON module, matching require() and Node

• jest-runtime: Throw ERR_REQUIRE_ASYNC_MODULE when require(esm) runs under an async-only custom resolver, instead of silently resolving with the default resolver

• jest-runtime: Parse imported JSON modules with the test realm's JSON, so their objects pass instanceof Object inside the test like require()d JSON does

• jest-runtime: Accept every file: URL string in the sandboxed module.createRequire, including one with a localhost authority, as Node does

• jest-runtime: Point at {virtual: true} when jest.mock or jest.unstable_mockModule is given a module that cannot be resolved

• jest-reporters: Fix coverage report table formatting in CI/GitHub Actions environments where process.stdout.columns is undefined by falling back to the COLUMNS env var or 80 columns in CI, preserving existing behaviour in other non-TTY environments

• jest-runtime: Support CJS-in-ESM exports via "module.exports" named exports

• jest-snapshot: Keep a skipped or failed test's hinted snapshots, instead of reporting them obsolete

• jest-util: Stop globsToMatcher reusing a cached matcher compiled with different picomatch options, and keep its dot: true default when dot is passed as undefined

• pretty-format: Move the react-is aliases into the @jest scope, so they cannot be shadowed by unrelated packages published under the alias names

Chore & Maintenance

• deprecated

  @jest/source-map: Deprecate getCallsite in favour of SourceMapSupport#getCallsite

Big release! 😀

Main feature is a rewrite of our custom runtime in preparation for stabilisation of native support of ESM. As part of that work require(esm) module is now supported on Node 24.9+ (still requires --experimental-vm-modules like before).

In addition we now support fake timers for the recently released Temporal API in Node v26.

React 19 is also supported properly in pretty-format, meaning snapshots of React components now work like they should.

Due to all the changes, there might be regressions that snuck in. Please report them!

Full list of changes below

Features

• babel-jest: Support collecting coverage from .mts, .cts (and other) files

• [jest-circus, jest-cli, jest-config, jest-core, jest-jasmine2, jest-types] Add --collect-tests flag to discover and list tests without executing them

• jest-config, jest-runner, jest-worker: Add workerGracefulExitTimeout config option to control how long workers are given to exit before being force-killed

• jest-config: Add support for jest.config.mts as a valid configuration file

• [jest-config, jest-core, jest-reporters, jest-runner] verbose and silent can now be set per-project; the project-level value overrides the global value for that project's tests

• @jest/fake-timers: Accept Temporal.Duration in jest.advanceTimersByTime() and jest.advanceTimersByTimeAsync()

• @jest/fake-timers: Accept Temporal.Instant and Temporal.ZonedDateTime in jest.setSystemTime() and useFakeTimers({now})

• @jest/fake-timers: Support faking Temporal.Now.*

• jest-mock: Add clearMocksOnScope(scope) on ModuleMocker for clearing every mock function exposed on a scope object

• jest-resolve: Add canResolveSync() on Resolver so callers can detect when a user-configured resolver only exports an async hook

• jest-runtime: Use synchronous evaluate() for ES modules without top-level await on Node versions that support it (v24.9+), and prefer the synchronous transform path when a sync transformer is configured

• jest-runtime: Support require() of ES modules on Node v24.9+

• jest-runtime: Validate TC39 import attributes (with { type: 'json' }) on ESM imports

• @jest/transform: Add canTransformSync(filename) on ScriptTransformer so callers can pick the sync vs async transform path

• jest-util: Add isError helper

• pretty-format: Support React 19

Fixes

• expect-utils: Fix toStrictEqual failing on structuredClone results due to cross-realm constructor mismatch

• @jest/expect-utils: Prevent toMatchObject/subset matching from throwing when encountering exotic iterables

• fake-timers: Convert Date to milliseconds before passing to @sinonjs/fake-timers

• jest: Export GlobalConfig and ProjectConfig TypeScript types

• jest-circus: Prevent crash when asyncError is undefined for non-Error throws

• jest-circus, jest-jasmine2: Include Error.cause in JSON failureMessages output

• jest-config: Fix preset path resolution on Windows when the preset uses subpath exports

• jest-config: Allow collectCoverage and coverageProvider in project config without a validation warning

• jest-config: Project config validator now emits "is not supported in an individual project configuration" instead of "probably a typing mistake" for known global-only options

• jest-environment-node: Fix --localstorage-file warning on Node 25+

• jest-reporters: Apply global coverage threshold to unmatched pattern files in addition to glob/path thresholds

• [jest-reporters, jest-runner, jest-runtime, jest-transform] Fix coverage report not showing correct code coverage when using projects config option

• jest-runtime: Resolve expect and @jest/expect from the internal module registry so test-file imports share the same JestAssertionError as the global expect

• jest-runtime: Improve CJS-from-ESM interop: __esModule/Babel default unwrap, broader named-export coverage, and shared CJS singleton across importers

• jest-runtime: Load .js files with ESM syntax but no "type":"module" marker as native ESM

• jest-runtime: Extend the .js-with-ESM-syntax fallback to require() on Node v24.9+ - falls back to require(esm) when the CJS parser rejects ESM syntax

• jest-runtime: Fix deadlocks and double-evaluation in concurrent ESM and wasm imports

• jest-runtime: Fix error when require() is called after the Jest environment has been torn down

• jest-runtime: Fix missing error when import() is called after the Jest environment has been torn down

• jest-runtime: Fix virtual unstable_mockModule registrations not respected in ESM

• jest-runtime: Apply moduleNameMapper when resolving modules with require.resolve() and the paths option

What's Changed

Features

• jest-resolver: Implement the defaultAsyncResolver

Fixes

• jest-resolver: Resolve builtin modules correctly

• jest-environment-node, jest-util: Avoid setting globals cleanup protection symbol when feature is off

Chore & Maintenance

• deprecated

  *: Remove and deprecate jest-repl package