Jest: Matchers, Mocks, Spies, Async and Snapshot Testing Reference Guide

# Install (npm / pnpm / yarn — pick one)
npm i -D jest @types/jest ts-jest @jest/globals
# For React or DOM tests
npm i -D jest-environment-jsdom @testing-library/jest-dom @testing-library/react

# Init a jest.config.* (interactive)
npx jest --init

# package.json
{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:cov":   "jest --coverage"
  }
}

# Run
npx jest                              # all tests
npx jest path/to/file.test.ts         # one file
npx jest -t "login"                   # name filter (regex)
npx jest --watch                      # rerun on file change (uses git)
npx jest --watchAll                   # rerun on any change
npx jest --updateSnapshot             # -u, accept current output as truth
npx jest --runInBand                  # serial (debug / shared state)
npx jest --coverage --collectCoverageFrom='src/**/*.{ts,tsx}'
npx jest --detectOpenHandles          # find async leaks

import { jest } from "@jest/globals";
import * as db from "./db";

// 1. Plain mock function
const cb = jest.fn((x: number) => x * 2);
cb(3);
expect(cb).toHaveBeenCalledWith(3);
expect(cb).toHaveReturnedWith(6);

// 2. Stage return values per-call
const fetchUser = jest
  .fn()
  .mockResolvedValueOnce({ id: 1 })   // first call
  .mockResolvedValueOnce({ id: 2 })   // second
  .mockRejectedValue(new Error("nope")); // rest

// 3. Spy on a real method (keeps original by default)
const spy = jest.spyOn(console, "warn").mockImplementation(() => {});
// ...code under test...
spy.mockRestore();                     // undo

// 4. Module mock — must be top-level, hoisted above imports
jest.mock("./db", () => ({
  getUser: jest.fn(async (id: number) => ({ id, name: "Mock" })),
}));

// 5. Reset between tests (or set globally via jest.config)
afterEach(() => {
  jest.clearAllMocks();                // wipe call history
  // jest.resetAllMocks();              // also remove implementations
  // jest.restoreAllMocks();            // restore spies to originals
});

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

// Async/await — return or await the promise
test("resolves user", async () => {
  await expect(getUser(1)).resolves.toEqual({ id: 1 });
  await expect(getUser(-1)).rejects.toThrow("not found");
});

// done() callback — only when you can't return a promise
test("emits done", (done) => {
  emitter.once("ready", (v) => {
    try { expect(v).toBe(42); done(); } catch (e) { done(e); }
  });
});

// Fake timers — control setTimeout / setInterval / Date
jest.useFakeTimers();
test("debounce fires after 250ms", () => {
  const fn = jest.fn();
  const d = debounce(fn, 250);
  d(); d(); d();
  jest.advanceTimersByTime(249);
  expect(fn).not.toHaveBeenCalled();
  jest.advanceTimersByTime(1);
  expect(fn).toHaveBeenCalledTimes(1);
});
// Flush all pending timers + microtasks
// await jest.runAllTimersAsync();

afterAll(() => jest.useRealTimers());

// src/cart.ts
export const total = (items: { price: number; qty: number }[]) =>
  items.reduce((s, i) => s + i.price * i.qty, 0);

export async function checkout(items, pay) {     // pay: (cents) => Promise<{ok:boolean}>
  if (!items.length) throw new Error("empty cart");
  const cents = Math.round(total(items) * 100);
  const res = await pay(cents);
  if (!res.ok) throw new Error("payment failed");
  return { paid: cents };
}

// src/cart.test.ts
import { jest } from "@jest/globals";
import { total, checkout } from "./cart";

describe("cart", () => {
  test("total sums price*qty", () => {
    expect(total([{ price: 2, qty: 3 }, { price: 1.5, qty: 2 }])).toBe(9);
  });

  test("checkout calls pay with cents and returns receipt", async () => {
    const pay = jest.fn().mockResolvedValue({ ok: true });
    await expect(checkout([{ price: 9.99, qty: 1 }], pay)).resolves.toEqual({ paid: 999 });
    expect(pay).toHaveBeenCalledWith(999);
  });

  test("checkout rejects empty cart", async () => {
    await expect(checkout([], jest.fn())).rejects.toThrow("empty cart");
  });
});