Agent Skills: Jest Knowledge Patch

Jest Knowledge Patch

Use this skill when upgrading, configuring, or debugging Jest 30 projects. Load the reference that matches the task before changing configuration, tests, custom environments, runners, sequencers, transforms, or integrations.

Reference index

| Reference | Topics | | --- | --- | | references/migration-and-runtime.md | Runtime requirements, removed APIs, renamed CLI options, package boundaries, path behavior | | references/configuration-and-cli.md | Configuration helpers, project settings, discovery commands, reporting, coverage, runners | | references/modules-transforms-and-environments.md | ESM/CJS interop, TypeScript, Babel, import attributes, JSDOM environments | | references/assertions-mocks-and-snapshots.md | Matcher behavior, mock hooks, spies, data-driven tests, snapshots, formatting | | references/execution-and-timers.md | Rejections, retries, fake timers, cleanup, leak detection, worker shutdown, setup hooks |

Working method

1. Inspect the installed Jest, Node.js, TypeScript, transformer, and test environment versions.
2. Read the relevant reference file before editing code.
3. Search for removed names and invalid configuration shapes.
4. Update behavior-sensitive tests separately from mechanical renames.
5. Run focused tests, then the full suite, coverage, and snapshot review.
6. Treat failures in custom runners, environments, sequencers, and reporters as possible public-contract changes before blaming test code.

Breaking changes first

Check the runtime

Jest 30 does not support Node.js 14, 16, 19, 21, or 23. Its type definitions require TypeScript 5.4 or newer. Confirm CI images, local toolchains, editor TypeScript, and package-manager constraints before investigating test failures.

The bundled JSDOM environment moved from JSDOM 21 to 26. Recheck DOM behavior, especially tests that mock window.location. A custom environment can use a different JSDOM version through @jest/environment-jsdom-abstract.

Replace removed matcher aliases

Use the canonical matcher names:

| Removed | Replacement | | --- | --- | | toBeCalled | toHaveBeenCalled | | toBeCalledTimes | toHaveBeenCalledTimes | | toBeCalledWith | toHaveBeenCalledWith | | lastCalledWith | toHaveBeenLastCalledWith | | nthCalledWith | toHaveBeenNthCalledWith | | toReturn | toHaveReturned | | toReturnTimes | toHaveReturnedTimes | | toReturnWith | toHaveReturnedWith | | lastReturnedWith | toHaveLastReturnedWith | | nthReturnedWith | toHaveNthReturnedWith | | toThrowError | toThrow |

Called-with matchers now infer the mocked function's parameter types. A previously running assertion can become a TypeScript error when its expected arguments do not match the mock signature.

Migrate CLI path filters

Rename --testPathPattern to plural --testPathPatterns; it accepts multiple patterns:

jest --testPathPatterns "unit/.*" "integration/.*"

Programmatic watch integrations must construct TestPathPatterns. CLI paths are matched against relative test-file paths, so remove assumptions that they match absolute paths.

jest --init is gone; initialize with:

npm init jest@latest

Pass explicit values to options such as --maxWorkers and --selectProjects. A custom --filter must return {filtered: Array<string>}, not an array.

Replace removed mock APIs and types

Replace jest.genMockFromModule() with jest.createMockFromModule(). Replace uses of jest.SpyInstance with jest.Spied; the public MockFunctionMetadata, MockFunctionMetadataType, and SpyInstance types were removed.

Match jest.mock() paths to the filename's exact casing even on case-insensitive file systems.

Stop deep-importing Jest packages

Import public package entry points. Jest packages are bundled and expose ESM wrappers through package exports, so a path such as jest-runner/build/testWorker is not a stable import.

Recheck custom glob patterns after the move to glob v10, particularly brace expansion and extglob behavior.

High-value behavior changes

Equality and subset matching

toEqual and objectContaining ignore non-enumerable properties by default. Equality includes symbol-keyed properties. toStrictEqual accepts compatible cross-realm constructors produced by structuredClone, and subset matching no longer throws on exotic iterables.

Review failures and newly passing tests as semantic changes; do not update expectations mechanically.

Snapshots and formatting

Snapshot text can change because:

• serialized errors include cause;
• React empty-string children are omitted;
• ArrayBuffer and DataView have readable formatting;
• React 19 values have formatter support;
• the deprecated goo.gl documentation URL is replaced by the full URL.

Review every snapshot update. Use static SERIALIZABLE_PROPERTIES on a custom object when only selected properties should appear in snapshots and matcher errors.

Module interop

Native ESM supports import.meta.*, file://, and validated import attributes. On supported Node.js versions, require() can load ES modules.

When ESM imports CommonJS, the complete module.exports value is the default export. Do not expect Babel-style __esModule default unwrapping. Named imports can see own properties on a function assigned to module.exports, and all importers share the same CommonJS singleton.

Test discovery

Default module extensions and test matching include .mjs, .cjs, .mts, and .cts. If non-test files now match, constrain testMatch or testRegex.

Discover tests without executing them:

jest --collect-tests

Write test-file discovery to a file with:

jest --listTests --outputFile test-files.json

Project configuration

Project entries can set testTimeout, coverageReporters, reporters, verbose, silent, collectCoverage, and coverageProvider. Project-level verbose and silent override the corresponding global settings.

The jest field in package.json may be a path to a configuration file:

{"jest": "./config/jest.config.js"}

Use defineConfig and mergeConfig from jest-config for typed configuration declaration and composition. Import GlobalConfig and ProjectConfig types from jest.

Useful APIs

Auto-restoring spies

With explicit resource management, using restores a spy at block exit:

using warnSpy = jest.spyOn(console, 'warn');

Generated mock customization

Each jest.onGenerateMock() callback must return the mock:

jest.onGenerateMock((modulePath, moduleMock) => {
  if (modulePath.includes('Database')) moduleMock.connect = jest.fn();
  return moduleMock;
});

Retry controls

Configure delay or immediate retry:

jest.retryTimes(3, {waitBeforeRetry: 1000});
jest.retryTimes(3, {retryImmediately: true});

Data-driven tests

Use %$ for the test-case sequence number. Readonly tables are accepted and receive improved callback argument inference:

const cases = [[1, 2, 3]] as const;
test.each(cases)('case %$: %i + %i = %i', (a, b, total) => {
  expect(a + b).toBe(total);
});

Fake timers

Run pending animation-frame callbacks with advanceTimersToFrame(). Timer advancement and clock setup also accept supported Temporal values. Consult the execution reference before mixing fake timers, asynchronous work, and retries.

Verification checklist

• Confirm supported Node.js and TypeScript versions in every environment.
• Search for removed matcher, mock, type, and CLI names.
• Check mock path casing and package deep imports.
• Revalidate .mjs, .cjs, .mts, and .cts discovery.
• Review relative CLI path filters and custom filter return values.
• Exercise custom runners, sequencers, environments, transformers, and reporters.
• Review changed equality semantics instead of blindly accepting results.
• Inspect snapshots for error, React, binary-data, and URL formatting changes.
• Test ESM/CJS boundaries and JSON import attributes.
• Run discovery-only commands and confirm selected test files.
• Validate per-project reporting and coverage behavior.
• Check cleanup warnings, leak detection, and worker shutdown behavior.
• Run the full suite after focused migration checks pass.