Testing Next.js Apps

A Practical Testing Pyramid for Next.js

Fast unit tests cover helpers, validation, and data mappers. React Testing Library covers Client Components and interactive UI. End-to-end tools (Playwright or Cypress) verify routing, auth, and forms against a real running app. Server Components complicate classic enzyme-style rendering, so teams often test them via thin integration tests or by extracting pure logic that is easy to unit test.

Next.js documentation commonly recommends Jest (or Vitest) with React Testing Library for components, and Playwright for E2E. Match the tool to the risk: auth and checkout deserve E2E coverage; a pure formatDate helper only needs a unit test.

// Button.test.tsx (Client Component)
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import Button from "./Button";

test("calls onClick when pressed", async () => {
  const onClick = jest.fn();
  render(<Button onClick={onClick}>Save</Button>);
  await userEvent.click(screen.getByRole("button", { name: /save/i }));
  expect(onClick).toHaveBeenCalledTimes(1);
});

Client Components with handlers test cleanly with React Testing Library. Keep Server Component data logic in pure functions when you want the same style of unit tests.

What to Test Where

Unit tests          → pure functions, schemas, mappers
Component tests     → Client Components, forms, hooks
Route Handler tests → call handlers with Request objects
E2E (Playwright)    → login, checkout, critical navigations

• Prefer testing user-visible behavior over implementation details.
• Mock network/database at boundaries; avoid mocking the entire Next.js runtime unless necessary.
• Run E2E against next start (production build) for the highest confidence.
• Keep test IDs rare — prefer roles, labels, and text queries.

Next.js Testing Cheat Sheet

Tooling choices mapped to App Router features.

Testing Route Handlers

Because App Router handlers are plain exported functions, you can import GET/POST and call them with a constructed Request in a unit test — no HTTP server required for many cases.

import { GET } from "./route";

test("GET /api/health returns ok", async () => {
  const response = await GET(new Request("http://localhost/api/health"));
  expect(response.status).toBe(200);
  await expect(response.json()).resolves.toEqual({ ok: true });
});

Critical Paths with Playwright

Use E2E for flows that cross auth, cookies, and multiple routes. Keep the suite small and stable: login, one happy-path feature, and one sad-path validation are often enough early on.

• Run against production builds (next build && next start) in CI when possible.
• Seed deterministic test data so flaky external APIs do not break CI.
• Prefer role-based selectors over brittle CSS class names.

Common Mistakes

• Only writing E2E tests and ending up with a slow, brittle suite.
• Trying to render async Server Components with Testing Library the same way as Client Components without extraction or special setup.
• Mocking so much of Next.js that tests pass while production wiring is wrong.
• Skipping tests around auth redirects and protected mutations.

Key Takeaways

• Combine unit, component, and a small E2E suite for balanced coverage.
• Client Components fit React Testing Library well; Server Component logic benefits from extracted helpers.
• Route Handlers and Server Actions can often be tested by calling them directly.
• Playwright/Cypress cover authentic user journeys across routes and cookies.
• Prefer behavior-focused assertions over testing internals.