jest-consistency

Jest — consistent, modern idioms

Jest is stable and ubiquitous in training data — which means generated tests reproduce the ecosystem's classic mistakes: hoisting-violating mock factories, mock state bleeding across tests, unawaited async assertions that pass vacuously, and matchers chosen by habit rather than semantics. This skill pins one canonical idiom set — Jest 29 semantics — built around mock hygiene and honest async tests.

Canonical idioms — always X, never Y

Always	Never	Why
jest.mock("./mod") at top level, config in the test via jest.mocked(mod).fn.mockReturnValue(...)	a jest.mock factory referencing variables declared next to it	jest.mock is hoisted above imports; out-of-scope captures throw (only mock*-prefixed vars are exempt).
clearMocks: true in config (or beforeEach(() => jest.clearAllMocks()))	trusting test order to leave mocks clean	Call counts/results otherwise leak between tests — false greens and order-dependent failures.
jest.spyOn(obj, "m").mockImplementation(...) + afterEach(() => jest.restoreAllMocks())	obj.m = jest.fn() reassignment	spyOn is restorable; manual reassignment permanently mutates the module for later tests.
await expect(fn()).rejects.toThrow("boom")	try { await fn(); } catch (e) { expect(e)... }	The try/catch form passes silently when nothing throws (unless you add expect.assertions).
it("...", async () => { await ... }) — await every assertion-bearing promise	mixing done callbacks with promises / forgetting await	An unawaited rejection escapes the test: it passes now, fails the run later (or never).
toStrictEqual for object equality (house default)	reflexive toEqual everywhere	toEqual ignores undefined props and class identity; toStrictEqual doesn't. toBe only for primitives/identity.
jest.useFakeTimers() + jest.advanceTimersByTime(n) / await jest.advanceTimersByTimeAsync(n), then jest.useRealTimers() in afterEach	real setTimeout + bigger test timeouts	Real waits are slow and flaky; unrestored fake timers break later tests and libraries.
test.each([[in1, out1], [in2, out2]])("f(%s)", ...)	copy-pasted near-identical tests or a for loop inside one test	A loop is one test that stops at the first failure; each reports each case.
small toMatchInlineSnapshot() with intent	sprawling file snapshots of whole component trees	Big snapshots get blindly -u-updated; they assert nothing.

House style for a mocked async test:

import { fetchUser } from "./api";
import { getUserName } from "./user";

jest.mock("./api");
const mockFetchUser = jest.mocked(fetchUser);

describe("getUserName", () => {
  it("returns the fetched name", async () => {
    mockFetchUser.mockResolvedValue({ id: 1, name: "Ada" });
    await expect(getUserName(1)).resolves.toBe("Ada");
    expect(mockFetchUser).toHaveBeenCalledWith(1);
  });

  it("propagates API failures", async () => {
    mockFetchUser.mockRejectedValue(new Error("503"));
    await expect(getUserName(1)).rejects.toThrow("503");
  });
});

Pitfalls that produce false-green tests

• Missing await before expect(p).resolves/rejects... makes the assertion float; the test ends first and passes regardless. These two matchers must always be awaited.
• Error-path tests that never throw: guard with expect.assertions(1) if you must use try/catch; prefer rejects/toThrow forms.
• expect(fn(badInput)).toThrow() — wrong: the call throws before expect runs. Pass a function: expect(() => fn(badInput)).toThrow().
• clear vs reset vs restore: clearAllMocks zeroes calls/results; resetAllMocks also removes implementations (mockReturnValue is gone!); restoreAllMocks only restores spyOn originals. Choosing reset when you meant clear silently strips configured return values mid-suite.
• Module-level state persists across tests in a file (modules are cached per file); use jest.isolateModules/jest.resetModules when testing module init.
• Fake timers + promises: a setTimeout wrapped in a promise needs advanceTimersByTimeAsync (or interleaved microtask flushes); plain advanceTimersByTime leaves the promise pending.
• "Jest did not exit": open handles (servers, intervals); fix the leak, don't reach for --forceExit.

Version notes

Target Jest 29. Notables on the way here: jest.mocked built in (27+), fake timers modern by default (27), advanceTimersByTimeAsync (29), snapshot format changes (29). ESM support is still experimental — under real ESM, prefer dependency injection or jest.unstable_mockModule; flag it rather than pretending jest.mock works the same.

Workflow

1. Decide each dependency's treatment: real, jest.mock (whole module), or spyOn (one method, restorable). Mock at the boundary you own.
2. Configure mock behavior inside each test, not at module scope; rely on clearMocks: true for hygiene.
3. Make every async path explicit: await all resolves/rejects, return nothing else.
4. Choose matchers by semantics: toBe identity, toStrictEqual structure, toMatchObject partial, toThrow with a message/class.
5. When reviewing, hunt: unawaited promises, factory-capture errors, reset-vs-clear misuse, snapshot sprawl, done callbacks in promise code.

For the fuller mock-type reference, timer recipes, async matrices, and config defaults, read references/jest-patterns.md.