Jest & RTL
Jest matchers, mocks, React Testing Library queries, user-event, MSW, and Next.js testing. · 26 lessons · click a card to expand
Testing pyramid & philosophy
3 items01The testing pyramid and where frontend tests live
/\
/E2E\ ← few (Playwright, Cypress)
/------\
/ Integr \ ← moderate (RTL + Jest)
/----------\
/ Unit \ ← many (pure functions, hooks, utils)
/----------------\Unit tests verify one function or hook in isolation. Integration tests render a component tree with providers, fire events, and check visible results. E2E tests drive a real browser against a deployed or local app.
For React, RTL is integration-first: you import a component, render it with render(), interact like a user, and assert what appears on screen. You do not test that setState was called or that a child received a specific prop unless that prop drives user-visible behavior.
// utils/formatPrice.test.js — unit test (pure function)
import { formatPrice } from "./formatPrice";
test("formats cents as USD currency", () => {
expect(formatPrice(1999)).toBe("$19.99");
});
// ProductCard.test.jsx — integration test (RTL)
import { render, screen } from "@testing-library/react";
import { ProductCard } from "./ProductCard";
test("shows formatted price to the shopper", () => {
render(<ProductCard name="Mug" priceCents={1999} />);
expect(screen.getByText("$19.99")).toBeInTheDocument();
});02Test behavior, not implementation
useState for useReducer even though the UI behaves identically. Behavior tests survive refactors because they describe the contract from the user's perspective.// ❌ Implementation detail — brittle
import { render } from "@testing-library/react";
import Counter from "./Counter";
test("increments count state", () => {
const { container } = render(<Counter />);
const instance = container.firstChild as any;
// reaching into internals or enzyme-style state
expect(instance._reactInternals?.memoizedState?.count).toBe(0);
});
// ✅ Behavior — resilient
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import Counter from "./Counter";
test("shows updated count after user clicks increment", async () => {
const user = userEvent.setup();
render(<Counter initial={0} />);
expect(screen.getByRole("status")).toHaveTextContent("0");
await user.click(screen.getByRole("button", { name: /increment/i }));
expect(screen.getByRole("status")).toHaveTextContent("1");
});The RTL guiding principle (Kent C. Dodds): *"The more your tests resemble the way your software is used, the more confidence they can give you."*
getByRole work — that helps both tests and real users.screen queries and user-visible assertions.03Arrange, Act, Assert (AAA) and test naming
test (alias it) blocks map naturally to AAA:import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import LoginForm from "./LoginForm";
describe("LoginForm", () => {
test("shows validation error when user submits empty email", async () => {
// Arrange
const user = userEvent.setup();
const onSubmit = jest.fn();
render(<LoginForm onSubmit={onSubmit} />);
// Act
await user.click(screen.getByRole("button", { name: /sign in/i }));
// Assert
expect(screen.getByRole("alert")).toHaveTextContent(/email is required/i);
expect(onSubmit).not.toHaveBeenCalled();
});
});Naming patterns that scale in large repos:
shows X when Ycalls Z with payload after user does Wdoes not render delete button when user lacks permission
Avoid vague names like works correctly or renders without crashing. Empty render smoke tests catch almost nothing useful.
shows/calls/does not pattern.Jest setup & matchers
4 items04Jest configuration for React and TypeScript
ts-jest or @swc/jest, jest-environment-jsdom, and a setup file that imports @testing-library/jest-dom for DOM-specific matchers.npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event
# TypeScript
npm install -D @types/jest ts-jest
# or faster: @swc/jest @swc/coreMinimal jest.config.ts:
import type { Config } from "jest";
const config: Config = {
testEnvironment: "jsdom",
setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],
moduleNameMapper: {
// Next.js / path aliases
"^@/(.*)$": "<rootDir>/src/$1",
// CSS modules and static assets
"\\.(css|less|scss)$": "identity-obj-proxy",
"\\.(jpg|jpeg|png|gif|svg)$": "<rootDir>/__mocks__/fileMock.js",
},
testPathIgnorePatterns: ["/node_modules/", "/.next/"],
collectCoverageFrom: ["src/**/*.{ts,tsx}", "!src/**/*.d.ts"],
};
export default config;jest.setup.ts:
import "@testing-library/jest-dom";
// Optional: fail tests on unexpected console.error
const originalError = console.error;
beforeAll(() => {
console.error = (...args: unknown[]) => {
originalError(...args);
throw new Error(`console.error: ${args.join(" ")}`);
};
});
afterAll(() => {
console.error = originalError;
});Add to package.json:
{
"scripts": {
"test": "jest",
"test:watch": "jest --watch",
"test:coverage": "jest --coverage"
}
}moduleNameMapper — unresolved imports are the most common first-run failure.jest.config.ts, jest.setup.ts, and run a single passing test that uses toBeInTheDocument(). Fix any module resolution errors until green.05Core matchers: equality, truthiness, and exceptions
toBe for primitives (strict equality), toEqual for deep object/array comparison, toBeTruthy/toBeFalsy sparingly, and toThrow for expected errors. Prefer specific matchers over generic ones.// Primitives — Object.is semantics (handles NaN)
expect(2 + 2).toBe(4);
expect("hello").not.toBe("world");
// Objects & arrays — deep equality
expect({ a: 1, b: { c: 2 } }).toEqual({ a: 1, b: { c: 2 } });
expect([1, 2, 3]).toEqual([1, 2, 3]);
// Same reference vs equal value
const obj = { x: 1 };
expect(obj).toBe(obj); // same reference — passes
expect({ x: 1 }).not.toBe(obj); // different object — passes
// Truthiness — avoid for strings/numbers; use toBe(true) or explicit value
expect("").toBeFalsy();
expect("text").toBeTruthy();
// Exceptions
function divide(a, b) {
if (b === 0) throw new Error("Division by zero");
return a / b;
}
expect(() => divide(10, 0)).toThrow("Division by zero");
expect(() => divide(10, 0)).toThrow(/division by zero/i);
// Async rejection
async function fetchBad() {
throw new Error("Network down");
}
await expect(fetchBad()).rejects.toThrow("Network down");toEqual (value) or toBe (reference). For floating point, use toBeCloseTo.parseQueryString utility covering normal input, empty string, and malformed input that throws. Use at least four different matcher types.06DOM matchers from jest-dom
@testing-library/jest-dom adds readable assertions for visibility, attributes, form state, and accessibility — toBeInTheDocument, toBeVisible, toHaveAttribute, toHaveTextContent, toBeDisabled, and more.expect(el).not.toBeNull() checks:import { render, screen } from "@testing-library/react";
import Modal from "./Modal";
test("open modal is visible and labelled for screen readers", () => {
render(<Modal open title="Confirm delete" onClose={() => {}} />);
const dialog = screen.getByRole("dialog", { name: /confirm delete/i });
expect(dialog).toBeInTheDocument();
expect(dialog).toBeVisible();
expect(dialog).toHaveAttribute("aria-modal", "true");
expect(dialog).toHaveTextContent(/this action cannot be undone/i);
});
test("submit button is disabled while form is invalid", () => {
render(<SignupForm />);
expect(screen.getByRole("button", { name: /create account/i })).toBeDisabled();
});Common matchers cheat sheet:
| Matcher | Use when |
|---|---|
toBeInTheDocument() | Element exists in DOM (may be hidden) |
toBeVisible() | Element is visible to the user |
toHaveTextContent() | Text matches (substring or regex) |
toHaveValue() | Input/textarea/select value |
toHaveClass() | CSS class present |
toHaveFocus() | Element has focus |
toHaveAccessibleName() | Computed accessible name |
expect(screen.getByLabelText(/email/i)).toHaveValue("dev@example.com");
expect(screen.getByRole("checkbox", { name: /newsletter/i })).toBeChecked();
expect(screen.getByTestId("toast")).toHaveClass("toast--success");toHaveAccessibleName over toHaveTextContent when the visible label comes from aria-label or associated <label>.07Grouping tests with describe, beforeEach, and test isolation
describe blocks to group related scenarios. Reset mocks and DOM between tests with beforeEach/afterEach. Each test must be independent — order must not matter.import { render, screen, cleanup } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import TodoList from "./TodoList";
describe("TodoList", () => {
const user = userEvent.setup();
beforeEach(() => {
jest.clearAllMocks();
});
afterEach(() => {
cleanup(); // RTL auto-cleans if using @testing-library/react v13+ with jest, but explicit is fine
});
describe("when list is empty", () => {
test("shows empty state message", () => {
render(<TodoList items={[]} />);
expect(screen.getByText(/no todos yet/i)).toBeInTheDocument();
});
});
describe("when list has items", () => {
const items = [{ id: "1", text: "Buy milk", done: false }];
test("renders each todo text", () => {
render(<TodoList items={items} />);
expect(screen.getByText("Buy milk")).toBeInTheDocument();
});
test("marks item complete after checkbox click", async () => {
const onToggle = jest.fn();
render(<TodoList items={items} onToggle={onToggle} />);
await user.click(screen.getByRole("checkbox", { name: /buy milk/i }));
expect(onToggle).toHaveBeenCalledWith("1");
});
});
});Jest runs each test file in its own scope. Avoid shared mutable state:
// ❌ Leaky shared state
let counter = 0;
test("first", () => { counter += 1; expect(counter).toBe(1); });
test("second", () => { counter += 1; expect(counter).toBe(2); }); // fails if order changes
// ✅ Local state per test
test("increments locally", () => {
let counter = 0;
counter += 1;
expect(counter).toBe(1);
});describe.each / test.each for table-driven tests when the same assertion applies to many inputs.test.each table with columns [input, expectedError].Mocking modules, timers & fetch
3 items08jest.mock for modules and manual mocks
jest.mock() replaces a module with an auto-mock or your factory. Use __mocks__ folders for reusable mocks. Call jest.mock() at the top level (hoisted) before imports that depend on the mock.// src/lib/analytics.ts
export function trackEvent(name: string, props?: Record<string, unknown>) {
window.analytics?.track(name, props);
}
// src/components/BuyButton.test.tsx
jest.mock("@/lib/analytics", () => ({
trackEvent: jest.fn(),
}));
import { trackEvent } from "@/lib/analytics";
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import BuyButton from "./BuyButton";
test("tracks purchase click", async () => {
const user = userEvent.setup();
render(<BuyButton sku="ABC" />);
await user.click(screen.getByRole("button", { name: /buy now/i }));
expect(trackEvent).toHaveBeenCalledWith("purchase_click", { sku: "ABC" });
});Partial mock — keep real exports, replace one function:
jest.mock("@/lib/api", () => ({
...jest.requireActual("@/lib/api"),
fetchProduct: jest.fn(),
}));Manual mock at src/lib/__mocks__/analytics.ts is picked up when you call jest.mock("@/lib/analytics") without a factory.
Spy on a method without replacing the whole module:
import * as api from "@/lib/api";
test("retries on failure", async () => {
const spy = jest.spyOn(api, "fetchProduct").mockRejectedValueOnce(new Error("fail"));
// ... exercise retry logic
spy.mockRestore();
});beforeEach with jest.clearAllMocks() and restore spies in afterEach with mockRestore() to prevent cross-test leakage.useRouter hook from Next.js and assert navigation after a button click. Use a factory mock that returns { push: jest.fn() }.09Fake timers for setTimeout, setInterval, and debounce
jest.useFakeTimers() replaces real timers with controllable fakes. Advance time with jest.advanceTimersByTime(ms) or jest.runAllTimers(). Always restore real timers after the test.import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import SearchInput from "./SearchInput";
jest.useFakeTimers();
afterEach(() => {
jest.clearAllTimers();
});
test("debounces search callback by 300ms", async () => {
const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
const onSearch = jest.fn();
render(<SearchInput onSearch={onSearch} debounceMs={300} />);
const input = screen.getByRole("searchbox");
await user.type(input, "react");
// Typing fired onChange but debounce has not elapsed
expect(onSearch).not.toHaveBeenCalled();
jest.advanceTimersByTime(299);
expect(onSearch).not.toHaveBeenCalled();
jest.advanceTimersByTime(1);
expect(onSearch).toHaveBeenCalledTimes(1);
expect(onSearch).toHaveBeenCalledWith("react");
});For modern @testing-library/user-event, pass advanceTimers so typing and fake timers cooperate.
Async patterns with fake timers:
jest.useFakeTimers();
test("polls until success", async () => {
const fetchStatus = jest
.fn()
.mockResolvedValueOnce({ status: "pending" })
.mockResolvedValueOnce({ status: "done" });
const promise = pollUntilDone(fetchStatus, { intervalMs: 1000 });
await jest.advanceTimersByTimeAsync(1000);
await jest.advanceTimersByTimeAsync(1000);
await expect(promise).resolves.toEqual({ status: "done" });
});fetch often causes hangs. Either mock fetch or use MSW (Lessons 19–20) alongside fake timers.10Mocking fetch and global APIs
global.fetch with jest.fn() for simple cases. For realistic HTTP behavior, prefer MSW (covered later). Mock globals like localStorage, matchMedia, and ResizeObserver in setup files when components depend on them.beforeEach(() => {
global.fetch = jest.fn();
});
afterEach(() => {
jest.resetAllMocks();
});
test("shows user name after profile load", async () => {
(fetch as jest.Mock).mockResolvedValueOnce({
ok: true,
json: async () => ({ name: "Ada Lovelace" }),
});
render(<ProfilePage userId="42" />);
expect(screen.getByText(/loading/i)).toBeInTheDocument();
expect(await screen.findByText("Ada Lovelace")).toBeInTheDocument();
expect(fetch).toHaveBeenCalledWith("/api/users/42");
});localStorage mock:
const store: Record<string, string> = {};
beforeEach(() => {
jest.spyOn(Storage.prototype, "getItem").mockImplementation(
(key) => store[key] ?? null
);
jest.spyOn(Storage.prototype, "setItem").mockImplementation((key, value) => {
store[key] = value;
});
});matchMedia (common in responsive hooks):
// jest.setup.ts
Object.defineProperty(window, "matchMedia", {
writable: true,
value: jest.fn().mockImplementation((query: string) => ({
matches: false,
media: query,
addEventListener: jest.fn(),
removeEventListener: jest.fn(),
})),
});ok, status, json()) so production parsing code paths execute realistically.RTL philosophy & queries
4 items11The RTL query priority: role, label, text, test id
getByRole → getByLabelText → getByPlaceholderText → getByText → getByDisplayValue → getByAltText → getByTitle → last resort getByTestId.| Prefix | Behavior |
|---|---|
getBy* | Returns element or throws — use for assertions |
queryBy* | Returns null if missing — use to assert absence |
findBy* | Returns Promise — use for async appearance |
import { render, screen } from "@testing-library/react";
import CheckoutForm from "./CheckoutForm";
test("accessible queries locate form controls", () => {
render(<CheckoutForm />);
// Best — role + accessible name
expect(screen.getByRole("heading", { name: /checkout/i })).toBeInTheDocument();
expect(screen.getByRole("textbox", { name: /card number/i })).toBeInTheDocument();
// Label association (also resolves to textbox role)
expect(screen.getByLabelText(/expiry date/i)).toBeInTheDocument();
// Placeholder — weaker, no visible label
expect(screen.getByPlaceholderText(/mm\/yy/i)).toBeInTheDocument();
// Visible text
expect(screen.getByText(/order total: \$49/i)).toBeInTheDocument();
// Last resort — implementation hook for dynamic lists
expect(screen.getByTestId("order-summary")).toBeInTheDocument();
});
test("assert element is not rendered", () => {
render(<CheckoutForm showCoupon={false} />);
expect(screen.queryByLabelText(/coupon code/i)).not.toBeInTheDocument();
});Use Testing Playground or screen.logTestingPlaygroundURL() after render() to discover recommended queries.
getByTestId first, ask whether adding a <label> or aria-label would improve production accessibility.12getByRole deep dive: name, hidden, and multiple matches
getByRole(role, { name, hidden }) is the most powerful query. name matches accessible name (label text, aria-label, alt text). Use hidden: true only when testing off-screen or aria-hidden content intentionally.<nav aria-label="Main">
<a href="/">Home</a>
<a href="/docs">Docs</a>
</nav>
<button aria-label="Close dialog">×</button>
<ul role="list">
<li>Item</li>
</ul>test("roles and names", () => {
render(<App />);
expect(screen.getByRole("navigation", { name: /main/i })).toBeInTheDocument();
expect(screen.getByRole("link", { name: /home/i })).toHaveAttribute("href", "/");
expect(screen.getByRole("button", { name: /close dialog/i })).toBeInTheDocument();
expect(screen.getByRole("list")).toBeInTheDocument();
expect(screen.getAllByRole("listitem")).toHaveLength(3);
});When multiple elements match, getByRole throws. Options:
// Specific name
screen.getByRole("button", { name: /save draft/i });
// getAll + index (prefer narrowing by name first)
const buttons = screen.getAllByRole("button");
expect(buttons).toHaveLength(2);
// within() to scope
import { within } from "@testing-library/react";
const dialog = screen.getByRole("dialog");
expect(within(dialog).getByRole("button", { name: /confirm/i })).toBeEnabled();Common roles: button, link, textbox, checkbox, radio, combobox, dialog, alert, status, progressbar, tab, tabpanel.
<button> is button, <a href> is link, <input type="checkbox"> is checkbox. A <div onClick> has no role unless you add role="button" and keyboard support.getByRole("tab"), getByRole("tabpanel"), and keyboard navigation assertions.13Custom renders and provider wrappers
render helper. Pass wrapper option or extend RTL's render once in test-utils.tsx.// test-utils.tsx
import { ReactElement, ReactNode } from "react";
import { render, RenderOptions } from "@testing-library/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ThemeProvider } from "@/context/ThemeContext";
function createTestQueryClient() {
return new QueryClient({
defaultOptions: {
queries: { retry: false, gcTime: Infinity },
mutations: { retry: false },
},
});
}
type Props = { children: ReactNode };
function AllProviders({ children }: Props) {
const client = createTestQueryClient();
return (
<QueryClientProvider client={client}>
<ThemeProvider defaultTheme="light">{children}</ThemeProvider>
</QueryClientProvider>
);
}
function customRender(ui: ReactElement, options?: Omit<RenderOptions, "wrapper">) {
return render(ui, { wrapper: AllProviders, ...options });
}
export * from "@testing-library/react";
export { customRender as render };Usage in tests — import render from ./test-utils, not @testing-library/react:
import { render, screen } from "@/test-utils";
import UserProfile from "./UserProfile";
test("loads profile with react-query", async () => {
render(<UserProfile userId="1" />);
expect(await screen.findByText(/ada lovelace/i)).toBeInTheDocument();
});Per-test override:
render(<Modal />, {
wrapper: ({ children }) => <AuthProvider user={adminUser}>{children}</AuthProvider>,
});retry: false) so failures surface immediately instead of timing out.test-utils.tsx for your stack (at minimum a Router wrapper). Migrate one test file to use it.14Debugging failing queries and using screen.debug
screen.debug(), log suggested queries with screen.logTestingPlaygroundURL(), and check for async timing issues before weakening the query.test("debug workflow", async () => {
render(<Dashboard />);
// Prints formatted DOM to console (optionally pass an element to limit output)
screen.debug(undefined, 100000);
// Opens Testing Playground with current DOM
screen.logTestingPlaygroundURL();
// Common failure: element exists but name mismatch
// ❌ fails if accessible name is "Settings menu" not "Settings"
// screen.getByRole("button", { name: /settings/i }); // might still pass with regex
// Common failure: async — use findBy
const heading = await screen.findByRole("heading", { name: /dashboard/i });
expect(heading).toBeVisible();
});Typical error messages:
- Unable to find role — wrong role, missing accessible name, or element not rendered yet.
- Found multiple elements — narrow with
name,within, orgetAllBy. - Not wrapped in act(...) — state update after async; use
waitFororfindBy.
import { waitFor } from "@testing-library/react";
await waitFor(() => {
expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
});debug() — large DOM dumps slow CI logs. Debug one subtree: screen.debug(within(container).getByRole("form")).debug() output, and document what misled you.user-event
2 items15userEvent.setup() and realistic interactions
@testing-library/user-event simulates pointer, keyboard, and clipboard behavior more faithfully than fireEvent. Always call const user = userEvent.setup() and await user.click() / await user.type() — events are async.import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import CommentBox from "./CommentBox";
test("submits comment on Enter with meta key", async () => {
const user = userEvent.setup();
const onSubmit = jest.fn();
render(<CommentBox onSubmit={onSubmit} />);
const field = screen.getByRole("textbox", { name: /comment/i });
await user.type(field, "Great post!");
await user.keyboard("{Meta>}{Enter}{/Meta}");
expect(onSubmit).toHaveBeenCalledWith("Great post!");
});
test("selects option from dropdown", async () => {
const user = userEvent.setup();
render(<CountrySelect />);
await user.selectOptions(
screen.getByRole("combobox", { name: /country/i }),
"IN"
);
expect(screen.getByRole("combobox")).toHaveValue("IN");
});
test("uploads file", async () => {
const user = userEvent.setup();
const file = new File(["hello"], "hello.png", { type: "image/png" });
render(<AvatarUpload />);
const input = screen.getByLabelText(/upload avatar/i);
await user.upload(input, file);
expect(await screen.findByAltText(/preview/i)).toBeInTheDocument();
});fireEvent vs userEvent:
import { fireEvent } from "@testing-library/react";
// fireEvent — dispatches single synthetic event (low-level escape hatch)
fireEvent.change(input, { target: { value: "x" } });
// userEvent — full interaction sequence (focus, keydown, input, keyup, blur)
await user.type(input, "x");userEvent. Reach for fireEvent only when simulating unsupported edge cases or third-party libraries that bypass normal input events.user.click, and assert type switches between password and text.16Keyboard navigation, pointer hover, and special keys
tab, keyboard, hover, and pointer APIs for accessibility-critical flows — modals, menus, comboboxes, and trap focus behavior.test("modal traps focus and closes on Escape", async () => {
const user = userEvent.setup();
const onClose = jest.fn();
render(<ConfirmModal open onClose={onClose} />);
const cancel = screen.getByRole("button", { name: /cancel/i });
const confirm = screen.getByRole("button", { name: /confirm/i });
expect(cancel).toHaveFocus();
await user.tab();
expect(confirm).toHaveFocus();
await user.tab();
expect(cancel).toHaveFocus(); // focus trapped
await user.keyboard("{Escape}");
expect(onClose).toHaveBeenCalledTimes(1);
});
test("opens submenu on hover when configured", async () => {
const user = userEvent.setup();
render(<NavMenu />);
const products = screen.getByRole("button", { name: /products/i });
await user.hover(products);
expect(await screen.findByRole("menu")).toBeVisible();
expect(screen.getByRole("menuitem", { name: /widgets/i })).toBeInTheDocument();
});
test("clears input with ctrl+a and backspace", async () => {
const user = userEvent.setup();
render(<SearchBar defaultValue="old query" />);
const input = screen.getByRole("searchbox");
await user.click(input);
await user.keyboard("{Control>}a{/Control}{Backspace}");
expect(input).toHaveValue("");
});Special character syntax reference:
await user.keyboard("{Shift>}{Tab}{/Shift}"); // Shift+Tab
await user.keyboard("[ArrowDown][ArrowDown][Enter]");
await user.clear(input); // dedicated clear helper@headlessui/react or Radix, combine role queries with realistic keyboard sequences — these libraries often bind to keydown, not click alone.Async & waitFor
2 items17findBy queries and waiting for elements
findBy* (alias for waitFor + getBy*) when elements appear after fetch, animation, or state transition. Default timeout is 1000ms; extend with { timeout: 3000 } for slow operations.import { render, screen } from "@testing-library/react";
import PostsList from "./PostsList";
test("renders posts after fetch resolves", async () => {
render(<PostsList />);
// Loading state — synchronous
expect(screen.getByRole("status")).toHaveTextContent(/loading/i);
// Async appearance — MUST await findBy
expect(await screen.findByRole("heading", { name: /posts/i })).toBeInTheDocument();
expect(screen.getByText(/first post title/i)).toBeInTheDocument();
// Loading gone
expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
});findBy vs manual waitFor:
// Equivalent patterns
const el = await screen.findByText(/saved/i);
await waitFor(() => expect(screen.getByText(/saved/i)).toBeInTheDocument());
// waitFor when asserting non-existence after delay
await waitFor(() => {
expect(screen.queryByRole("alert")).not.toBeInTheDocument();
});Multiple async elements:
const [title, author] = await Promise.all([
screen.findByRole("heading", { level: 1 }),
screen.findByText(/by/i),
]);findBy times out, the element never appeared or your mock never resolved — check network mocks before increasing timeout.findBy.18waitFor, waitForElementToBeRemoved, and act warnings
waitFor retries a callback until it passes or times out — use for complex multi-assertion async conditions. waitForElementToBeRemoved waits for spinners and toasts to leave. Fix act warnings by awaiting RTL async APIs instead of raw state updates.import { render, screen, waitFor, waitForElementToBeRemoved } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import SaveButton from "./SaveButton";
test("shows saving state then success toast", async () => {
const user = userEvent.setup();
render(<SaveButton />);
await user.click(screen.getByRole("button", { name: /save/i }));
expect(screen.getByRole("button", { name: /saving/i })).toBeDisabled();
await waitFor(() => {
expect(screen.getByRole("button", { name: /save/i })).toBeEnabled();
expect(screen.getByRole("status")).toHaveTextContent(/saved successfully/i);
});
});
test("spinner removed after load", async () => {
render(<SlowChart />);
const spinner = screen.getByRole("progressbar");
await waitForElementToBeRemoved(spinner);
expect(screen.getByRole("img", { name: /chart/i })).toBeVisible();
});Custom waitFor options:
await waitFor(
() => expect(mockFn).toHaveBeenCalledWith({ id: 1 }),
{ timeout: 2000, interval: 50 }
);act warning usually means:
// ❌ state update outside RTL await
setTimeout(() => setOpen(true), 0);
expect(screen.getByRole("dialog")).toBeInTheDocument(); // act warning
// ✅ await findBy or waitFor
expect(await screen.findByRole("dialog")).toBeInTheDocument();waitFor should assert one logical outcome. Multiple unrelated waits in one test often indicate the test is doing too much — split it.waitFor and waitForElementToBeRemoved.MSW integration
2 items19MSW setup: handlers, server, and test lifecycle
mocks/handlers.ts, start setupServer in Node tests, and reset handlers between tests.npm install -D msw
npx msw init public/ --save// mocks/handlers.ts
import { http, HttpResponse } from "msw";
export const handlers = [
http.get("/api/users/:id", ({ params }) => {
return HttpResponse.json({
id: params.id,
name: "Grace Hopper",
});
}),
http.post("/api/users", async ({ request }) => {
const body = await request.json();
return HttpResponse.json({ id: "99", ...body }, { status: 201 });
}),
];// mocks/server.ts
import { setupServer } from "msw/node";
import { handlers } from "./handlers";
export const server = setupServer(...handlers);// jest.setup.ts
import { server } from "./mocks/server";
beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());Test usage — no fetch mock needed:
import { render, screen } from "@testing-library/react";
import UserCard from "./UserCard";
test("displays user from API", async () => {
render(<UserCard userId="7" />);
expect(await screen.findByText("Grace Hopper")).toBeInTheDocument();
});onUnhandledRequest: "error" during development to catch missing handlers. Use "warn" temporarily when migrating a large suite./api/todos, and render a list component that consumes it without mocking fetch directly.20MSW overrides: per-test handlers, errors, and delays
server.use() inside a test to simulate errors, empty lists, or slow responses. Compose realistic edge cases without duplicating fetch mocks.import { http, HttpResponse, delay } from "msw";
import { server } from "@/mocks/server";
test("shows empty state when API returns no todos", async () => {
server.use(
http.get("/api/todos", () => HttpResponse.json([]))
);
render(<TodoPage />);
expect(await screen.findByText(/no todos yet/i)).toBeInTheDocument();
});
test("shows error banner on 500", async () => {
server.use(
http.get("/api/todos", () =>
HttpResponse.json({ message: "Server error" }, { status: 500 })
)
);
render(<TodoPage />);
expect(await screen.findByRole("alert")).toHaveTextContent(/something went wrong/i);
});
test("shows loading skeleton until delayed response", async () => {
server.use(
http.get("/api/todos", async () => {
await delay(500);
return HttpResponse.json([{ id: "1", text: "Late todo" }]);
})
);
render(<TodoPage />);
expect(screen.getByTestId("skeleton")).toBeInTheDocument();
expect(await screen.findByText("Late todo")).toBeInTheDocument();
});GraphQL with MSW:
import { graphql, HttpResponse } from "msw";
server.use(
graphql.query("GetUser", () => {
return HttpResponse.json({
data: { user: { id: "1", name: "Test User" } },
});
})
);handlers.ts and override only the deviation in each test — readers see defaults vs scenario at a glance.server.use().Testing hooks & forms
2 items21Testing custom hooks with renderHook
@testing-library/react's renderHook runs hooks inside a test component. Use result.current for values and act() or await act() when triggering updates. Wrap with providers via wrapper option.import { renderHook, act, waitFor } from "@testing-library/react";
import { useCounter } from "./useCounter";
test("increments counter", () => {
const { result } = renderHook(() => useCounter(0));
expect(result.current.count).toBe(0);
act(() => {
result.current.increment();
});
expect(result.current.count).toBe(1);
});Hook with async side effect:
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useUser } from "./useUser";
function createWrapper() {
const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
return function Wrapper({ children }: { children: React.ReactNode }) {
return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
};
}
test("useUser returns data", async () => {
const { result } = renderHook(() => useUser("1"), { wrapper: createWrapper() });
await waitFor(() => expect(result.current.isSuccess).toBe(true));
expect(result.current.data?.name).toBe("Grace Hopper");
});Testing hook that depends on router:
import { MemoryRouter } from "react-router-dom";
import { useQueryParam } from "./useQueryParam";
test("reads tab query param", () => {
const { result } = renderHook(() => useQueryParam("tab"), {
wrapper: ({ children }) => (
<MemoryRouter initialEntries={["/?tab=settings"]}>{children}</MemoryRouter>
),
});
expect(result.current).toBe("settings");
});renderHook for wiring and effects.useDebouncedValue hook: update input value, advance fake timers, assert debounced output changes once.22Form testing: validation, submission, and error messages
role="alert" or live regions. Verify submit handlers receive correct payloads and buttons disable during pending state.import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import SignupForm from "./SignupForm";
test("client validation prevents submit with weak password", async () => {
const user = userEvent.setup();
const onSubmit = jest.fn();
render(<SignupForm onSubmit={onSubmit} />);
await user.type(screen.getByLabelText(/email/i), "dev@example.com");
await user.type(screen.getByLabelText(/^password$/i), "123");
await user.click(screen.getByRole("button", { name: /sign up/i }));
expect(await screen.findByRole("alert")).toHaveTextContent(
/password must be at least 8 characters/i
);
expect(onSubmit).not.toHaveBeenCalled();
});
test("successful submit sends normalized payload", async () => {
const user = userEvent.setup();
const onSubmit = jest.fn().mockResolvedValue(undefined);
render(<SignupForm onSubmit={onSubmit} />);
await user.type(screen.getByLabelText(/email/i), " Dev@Example.COM ");
await user.type(screen.getByLabelText(/^password$/i), "securepass1");
await user.click(screen.getByRole("checkbox", { name: /terms/i }));
await user.click(screen.getByRole("button", { name: /sign up/i }));
await waitFor(() =>
expect(onSubmit).toHaveBeenCalledWith({
email: "dev@example.com",
password: "securepass1",
acceptedTerms: true,
})
);
});
test("submit button disabled while request pending", async () => {
const user = userEvent.setup();
let resolveSubmit!: () => void;
const onSubmit = jest.fn(
() => new Promise<void>((r) => { resolveSubmit = r; })
);
render(<SignupForm onSubmit={onSubmit} />);
await user.type(screen.getByLabelText(/email/i), "a@b.com");
await user.type(screen.getByLabelText(/^password$/i), "longenough");
await user.click(screen.getByRole("button", { name: /sign up/i }));
expect(screen.getByRole("button", { name: /creating account/i })).toBeDisabled();
resolveSubmit();
await waitFor(() =>
expect(screen.getByRole("button", { name: /sign up/i })).toBeEnabled()
);
});Server-side field errors:
server.use(
http.post("/api/signup", () =>
HttpResponse.json({ fieldErrors: { email: "Already registered" } }, { status: 422 })
)
);
// assert inline error linked to input
expect(screen.getByLabelText(/email/i)).toHaveAccessibleDescription(/already registered/i);/^password$/i regex anchors when both "Password" and "Confirm password" labels exist — avoids ambiguous matches.Next.js component & route testing
2 items23Testing Next.js client components, Link, and useRouter
next/navigation (useRouter, usePathname, useSearchParams) and wrap with MemoryRouter only when not using App Router mocks. Test next/link behavior via accessible links, not implementation.// __mocks__/next/navigation.ts (manual mock)
export const useRouter = jest.fn(() => ({
push: jest.fn(),
replace: jest.fn(),
back: jest.fn(),
prefetch: jest.fn(),
}));
export const usePathname = jest.fn(() => "/");
export const useSearchParams = jest.fn(() => new URLSearchParams());import { useRouter } from "next/navigation";
import { render, screen } from "@/test-utils";
import userEvent from "@testing-library/user-event";
import ProductLink from "./ProductLink";
jest.mock("next/navigation");
test("navigates to product detail on click", async () => {
const push = jest.fn();
(useRouter as jest.Mock).mockReturnValue({ push });
const user = userEvent.setup();
render(<ProductLink slug="wireless-mouse" />);
const link = screen.getByRole("link", { name: /wireless mouse/i });
expect(link).toHaveAttribute("href", "/products/wireless-mouse");
await user.click(link);
expect(push).toHaveBeenCalledWith("/products/wireless-mouse");
});Components using next/image — mock in Jest:
// jest.setup.ts
jest.mock("next/image", () => ({
__esModule: true,
default: (props: React.ImgHTMLAttributes<HTMLImageElement>) => {
// eslint-disable-next-line @next/next/no-img-element, jsx-a11y/alt-text
return <img {...props} />;
},
}));Server Components that fetch data are often tested indirectly via integration/E2E; extract data logic into testable functions or test the client boundary component that receives props.
__mocks__/next/navigation.ts so jest.mock("next/navigation") picks it up automatically without a factory in every file.useSearchParams to return ?q=jest, render a search results header, and assert it displays the query term.24Testing Server Actions, route handlers, and async RSC boundaries
cookies, headers, and database layers. For UI that invokes Server Actions, assert pending UI and revalidation outcomes on the client wrapper.// app/actions/createTodo.test.ts
import { createTodo } from "./createTodo";
import { db } from "@/lib/db";
jest.mock("@/lib/db", () => ({
db: { todo: { create: jest.fn() } },
}));
jest.mock("next/cache", () => ({
revalidatePath: jest.fn(),
}));
import { revalidatePath } from "next/cache";
test("createTodo inserts and revalidates list path", async () => {
(db.todo.create as jest.Mock).mockResolvedValue({ id: "1", text: "Buy milk" });
const formData = new FormData();
formData.set("text", "Buy milk");
await createTodo(formData);
expect(db.todo.create).toHaveBeenCalledWith({ data: { text: "Buy milk" } });
expect(revalidatePath).toHaveBeenCalledWith("/todos");
});Route handler test:
// app/api/health/route.test.ts
import { GET } from "./route";
test("GET /api/health returns ok", async () => {
const response = await GET();
const body = await response.json();
expect(response.status).toBe(200);
expect(body).toEqual({ status: "ok" });
});Client form calling a Server Action:
"use client";
// TodoForm.test.tsx — mock the action module
jest.mock("@/app/actions/createTodo", () => ({
createTodo: jest.fn(),
}));
import { createTodo } from "@/app/actions/createTodo";
test("shows optimistic item then refreshes list", async () => {
const user = userEvent.setup();
(createTodo as jest.Mock).mockImplementation(
() => new Promise((r) => setTimeout(r, 100))
);
render(<TodoForm />);
await user.type(screen.getByRole("textbox"), "New task");
await user.click(screen.getByRole("button", { name: /add/i }));
expect(screen.getByText("New task")).toBeInTheDocument(); // optimistic UI
await waitFor(() => expect(createTodo).toHaveBeenCalled());
});CI habits
2 items25Coverage thresholds, test splitting, and flake prevention
// jest.config.ts excerpt
const config: Config = {
collectCoverageFrom: [
"src/**/*.{ts,tsx}",
"!src/**/*.stories.{ts,tsx}",
"!src/**/index.ts",
],
coverageThreshold: {
global: {
branches: 70,
functions: 75,
lines: 80,
statements: 80,
},
"./src/lib/": {
branches: 90,
functions: 90,
lines: 90,
statements: 90,
},
},
};CI sharding (GitHub Actions example):
strategy:
matrix:
shard: [1, 2, 3, 4]
steps:
- run: npm test -- --shard=${{ matrix.shard }}/4 --ci --coverageFlake prevention checklist:
// ✅ deterministic
beforeEach(() => {
jest.useRealTimers();
jest.clearAllMocks();
server.resetHandlers();
});
// ✅ await async UI
await screen.findByRole("button", { name: /done/i });
// ❌ arbitrary sleep
await new Promise((r) => setTimeout(r, 500));
// ❌ testing exact fetch call order across microtasks without waitFor
expect(mockA).toHaveBeenCalledBefore(mockB); // fragileQuarantine policy: mark flaky tests with issue link, fix within sprint, or delete if low value. --onlyFailures locally speeds up fix loops.
jest --verbose or CI reporters). Split files that exceed 30 seconds — often MSW setup or missing mock cleanup.coverageThreshold for one critical folder. Identify your slowest test file and reduce runtime by at least 50% using fake timers or slimmer MSW handlers.26Pre-commit hooks, watch mode workflow, and debugging CI failures
--ci --runInBand and frozen lockfile installs.# Run tests related to changed files
npm test -- --watch
# Filter by filename pattern
npm test -- TodoList
# Update snapshots intentionally
npm test -- -u FeatureCardlint-staged + husky:
{
"lint-staged": {
"*.{ts,tsx}": [
"eslint --fix",
"jest --bail --findRelatedTests --passWithNoTests"
]
}
}Reproduce CI locally:
# CI often sets CI=true (Jest: no watch, fail on deprecated APIs)
CI=true npm test -- --ci --runInBand --coverage
# Match Node version
nvm use 20
npm ciDebugging CI-only failures:
- Timezone/locale — set
TZ=UTCin CI and locally. - Parallel race — try
--runInBandto expose shared state bugs. - Unhandled MSW requests — CI stricter logging reveals missing handlers.
- Snapshot drift — OS-specific line endings; normalize with
.gitattributes.
// package.json scripts
{
"test:ci": "jest --ci --coverage --runInBand",
"test:changed": "jest --bail --findRelatedTests"
}Document team conventions in CONTRIBUTING.md: naming, where mocks live, MSW handler rules, minimum bar before merge.
test:ci script, run it locally, and write a three-item checklist your team would follow when a PR test job fails on GitHub Actions.