Jest Testing skill for Codex

A healthy Jest suite starts fast, isolates mocks per test automatically, never waits on real timers, and exits on its own without --forceExit.

Inspect first

1. Read AGENTS.md and package.json scripts: the real test command may add flags (--runInBand, --selectProjects, env vars).
2. Find the config: jest.config.{js,ts,mjs,cjs} or the "jest" key in package.json. Note testEnvironment, transform, moduleNameMapper, setupFilesAfterEnv, projects, and the mock-reset flags.
3. Check the installed version: npx jest --version. Jest 30 removed matcher aliases and renamed --testPathPattern to --testPathPatterns.
4. Check "type": "module" in package.json and tsconfig.json module setting; they decide the ESM path below.
5. If the project is Vite-based and has no Jest investment yet, recommend Vitest instead ($vitest-testing); do not start a new Jest setup there.

Baseline config

// jest.config.ts (loading a TS config needs ts-node; otherwise use jest.config.mjs)
import type { Config } from "jest";

const config: Config = {
  testEnvironment: "node",            // "jsdom" only for DOM tests; install jest-environment-jsdom
  transform: { "^.+\\.(t|j)sx?$": ["@swc/jest", {}] },
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
    "\\.(css|scss)$": "identity-obj-proxy",
  },
  setupFilesAfterEnv: ["<rootDir>/test/setup.ts"],
  restoreMocks: true,                 // restore spies and reset mocks before each test
  clearMocks: true,
  coverageProvider: "v8",
  collectCoverageFrom: ["src/**/*.{ts,tsx}", "!src/**/*.d.ts", "!src/**/index.ts"],
  coverageThreshold: { global: { branches: 75, lines: 80 } },
};
export default config;

Transform choice

Need	Use
Fast TS/JSX, no type checking in tests	@swc/jest
Type errors must fail tests	ts-jest (slower; or run tsc --noEmit separately and keep swc)
Existing Babel config (React Native, legacy)	babel-jest (default when a Babel config exists)

Run tsc --noEmit in CI regardless; transforms that strip types do not check them.

Mocking

Module mocks

jest.mock() calls are hoisted above imports by the transform. Factories may only reference variables whose names start with mock.

import { sendEmail } from "../src/mailer";
import { registerUser } from "../src/register";

jest.mock("../src/mailer", () => ({
  sendEmail: jest.fn().mockResolvedValue({ id: "msg_1" }),
}));

it("sends a welcome email after registration", async () => {
  await registerUser({ email: "[email protected]" });

  expect(sendEmail).toHaveBeenCalledTimes(1);
  expect(sendEmail).toHaveBeenCalledWith(expect.objectContaining({ to: "[email protected]" }));
});

Partial mock, keeping the rest real:

jest.mock("../src/config", () => ({
  ...jest.requireActual("../src/config"),
  featureFlags: { newCheckout: true },
}));

Spies

const spy = jest.spyOn(paymentGateway, "charge").mockResolvedValueOnce({ ok: false });

With restoreMocks: true the spy is undone before the next test. Without it, call jest.restoreAllMocks() in afterEach, or a spy from one test leaks into the next.

Flag	Effect before each test
clearMocks	wipes mock.calls and results
resetMocks	also removes implementations (factory mockResolvedValue is lost)
restoreMocks	restores original methods behind jest.spyOn

Gotcha: resetMocks: true erases implementations set inside jest.mock factories, so tests that relied on them suddenly get undefined. Prefer clearMocks + restoreMocks and set per-test behavior with mockResolvedValueOnce.

Typing mocks

import { fetchUser } from "../src/api";
jest.mock("../src/api");
const mockedFetchUser = jest.mocked(fetchUser);
mockedFetchUser.mockResolvedValue({ id: "u1", name: "Ada" });

Fake timers

beforeEach(() => jest.useFakeTimers());
afterEach(() => jest.useRealTimers());

it("retries after 2 seconds", async () => {
  const promise = fetchWithRetry(url);
  await jest.advanceTimersByTimeAsync(2000);   // flushes promises between timer callbacks
  await expect(promise).resolves.toEqual(data);
});

it("stamps the current date", () => {
  jest.setSystemTime(new Date("2026-03-01T12:00:00Z"));
  expect(makeInvoice().issuedAt).toBe("2026-03-01");
});

• Use the ...Async timer functions whenever the code awaits between timers; the sync versions leave promise callbacks unrun and the test hangs or times out.
• jest.runAllTimers() loops forever on setInterval; use runOnlyPendingTimers().
• Libraries that capture setTimeout at import time are not faked; enable fake timers before importing them or inject a scheduler.

ESM

Pick one path and state it in the config comments.

Situation	Path
Source is TS/ESM syntax but compiled by a transform	Keep CJS output from the transform; nothing special
Dependency in node_modules ships ESM only	Add it to transformIgnorePatterns exceptions so it is transformed
Project runs native ESM ("type": "module", no transform)	Run Jest with --experimental-vm-modules

// transformIgnorePatterns exception for ESM-only packages
transformIgnorePatterns: ["/node_modules/(?!(nanoid|uuid|@scope/esm-lib)/)"],

{ "scripts": { "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js" } }

In native ESM, jest.mock is not hoisted. Mock first, then import dynamically:

import { jest } from "@jest/globals";

jest.unstable_mockModule("../src/mailer.js", () => ({ sendEmail: jest.fn() }));
const { sendEmail } = await import("../src/mailer.js");
const { registerUser } = await import("../src/register.js");

If ESM pain dominates the work, say so and propose migrating the suite to Vitest rather than stacking workarounds.

Running and debugging

npx jest path/to/file.test.ts -t "sends a welcome email"   # one test
npx jest --testPathPatterns checkout                        # Jest 30 flag name
npx jest --onlyChanged                                      # files touched since last commit
npx jest --findRelatedTests src/cart.ts src/tax.ts          # tests that import these
npx jest --runInBand --detectOpenHandles                     # find what keeps Jest alive
npx jest --ci --shard=2/4 --coverage                         # CI: no snapshot writes, one shard

• --ci makes missing snapshots fail instead of being written. Always use it in CI.
• “Jest did not exit one second after the test run” means open handles: close servers, DB pools and timers in afterAll. Do not add --forceExit as the fix.
• Memory growth across a big suite: try --workerIdleMemoryLimit=512MB and look for module-level caches.

Jest 30 upgrade checklist

• Node 18+ and TypeScript 5.4+ for type definitions
• Replace removed matcher aliases (toBeCalled -> toHaveBeenCalled, toThrowError -> toThrow, lastCalledWith -> toHaveBeenLastCalledWith); eslint-plugin-jest can autofix these
• Rename --testPathPattern to --testPathPatterns in scripts and CI
• Re-run snapshots with --ci first to see real diffs before updating any
• Check that newly matched .mts/.cts files are intended tests

Gotchas

• jest.mock paths are resolved relative to the test file, and must match how the unit imports the module (an alias import and a relative import can resolve to the same file but a mismatch in moduleNameMapper creates two module instances).
• Mocking a module after it has been imported by another module in the same file has no effect; use jest.isolateModules or reorder.
• expect(asyncFn()).rejects... without await passes silently. Always await expect(...).
• testEnvironment: "jsdom" for the whole repo slows pure logic tests; use a per-file docblock /** @jest-environment jsdom */ or projects.

Verification

1. Run the target file, then the full suite with the project command.
2. Run the changed tests with --runInBand and again in parallel to expose shared state.
3. Confirm the process exits without --forceExit and --detectOpenHandles is silent.
4. For mock changes, temporarily break the mocked behavior and confirm a test fails.