Next.js

🧪 Testing in Next.js: The Complete Guide

A well-tested Next.js application catches regressions early, gives teams confidence to refactor, and documents expected behavior far better than comments ever could. This tutorial covers the full testing pyramid — from fast unit tests to full-browser end-to-endflows — using the tools most common in the Next.js ecosystem.

Information

Examples use both Jest and Vitest alongside React Testing Library, Playwright, and Cypress. Pick the combination that fits your project.

📖 1. Introduction

Testing a Next.js app isn't a single activity — it spans components, Server Actions, Route Handlers, middleware, and full user journeys across the browser. Because Next.js mixes server and client rendering, tests need to account for where code actually runs.

Testing Layers

Unit Tests (functions, hooks, utilities)

Integration Tests (components, API routes)

End-to-End Tests (full user flows in a browser)

🎯 2. Why Test Next.js Applications?

Catch regressions early— before they reach production or a user's browser.
Enable confident refactoring— a passing suite proves behavior hasn't changed.
Document expected behavior— tests describe what the system is supposed to do.
Reduce manual QA time— automated checks run in seconds, not hours.

Tip

Tests are most valuable around business logic and critical user flows— checkout, authentication, form submission — not necessarily every visual detail.

🏗️ 3. Types of Testing

Type	Scope	Speed	Tooling
Unit	Single function or component in isolation	Very fast	Jest, Vitest
Integration	Multiple units working together	Fast	Jest/Vitest + React Testing Library
End-to-End	Full app in a real browser	Slower	Playwright, Cypress

Best Practice

Follow the testing pyramid: write many fast unit tests, fewer integration tests, and a small set of high-value end-to-end tests covering critical paths.

🔬 4. Unit Testing

Unit tests verify a single piece of logicin isolation — a utility function, a custom hook, or a pure calculation — with no rendering or network calls involved.

lib/formatPrice.test.ts

import { formatPrice } from "./formatPrice";

describe("formatPrice", () => {
  it("formats whole numbers as currency", () => {
    expect(formatPrice(1000)).toBe("$1,000.00");
  });

  it("handles zero correctly", () => {
    expect(formatPrice(0)).toBe("$0.00");
  });
});

🔗 5. Integration Testing

Integration tests check how multiple pieceswork together — a form component that calls a hook, or a page that fetches and renders data.

components/SearchBar.test.tsx

import { render, screen, fireEvent } from "@testing-library/react";
import { SearchBar } from "./SearchBar";

it("calls onSearch with the entered query", () => {
  const onSearch = jest.fn();
  render(<SearchBar onSearch={onSearch} />);

  fireEvent.change(screen.getByRole("textbox"), { target: { value: "sneakers" } });
  fireEvent.click(screen.getByRole("button", { name: /search/i }));

  expect(onSearch).toHaveBeenCalledWith("sneakers");
});

🌐 6. End-to-End Testing

End-to-end (E2E) tests simulate a real user clicking through your actual application in a browser, verifying entire flows like signup, checkout, or search.

e2e/checkout.spec.ts

import { test, expect } from "@playwright/test";

test("user can complete checkout", async ({ page }) => {
  await page.goto("/cart");
  await page.click("text=Checkout");
  await page.fill("#email", "user@example.com");
  await page.click("text=Place Order");

  await expect(page.locator("h1")).toHaveText("Order Confirmed");
});

Warning

E2E tests are the slowest and most brittle layer — reserve them for critical paths, not every possible interaction.

🧰 7. Test Environment Setup

Before writing tests, decide on a runner and configure it to understand Next.js's module resolution, path aliases, and JSX transform.

📦

Install the test runner and its Next.js-specific config helper.

⚙️

Configure the test environment (jsdom for component tests).

🔗

Set up path alias resolution to match tsconfig.json.

✅

Add a test script to package.json and run it in CI.

🃏 8. Jest

Jest is a mature, batteries-included test runner with built-in mocking, assertions, and coverage reporting. Next.js provides a first-party config helper.

Installing Jest for Next.js

npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom

jest.config.js

const nextJest = require("next/jest");

const createJestConfig = nextJest({ dir: "./" });

const customJestConfig = {
  setupFilesAfterEach: ["<rootDir>/jest.setup.js"],
  testEnvironment: "jest-environment-jsdom",
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/$1",
  },
};

module.exports = createJestConfig(customJestConfig);

Tip

next/jestautomatically handles SWC compilation, CSS module mocking, and environment variable loading — matching your app's actual build behavior.

⚡ 9. Vitest

Vitest is a fast, modern alternative to Jest, built on top of Vite, with a largely compatible API and significantly quicker test runs.

Installing Vitest

npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react

vitest.config.ts

import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
import path from "path";

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    setupFiles: ["./vitest.setup.ts"],
  },
  resolve: {
    alias: { "@": path.resolve(__dirname, "./") },
  },
});

Information

Vitest's API (describe, it, expect) closely mirrors Jest's, making migration between the two straightforward in most projects.

🧪 10. React Testing Library

React Testing Library (RTL) encourages testing components the way users actually interactwith them — by querying rendered text and roles, not internal implementation details.

components/LoginForm.test.tsx

import { render, screen, fireEvent, waitFor } from "@testing-library/react";
import "@testing-library/jest-dom";
import { LoginForm } from "./LoginForm";

it("shows an error when submitting an empty form", async () => {
  render(<LoginForm />);

  fireEvent.click(screen.getByRole("button", { name: /log in/i }));

  await waitFor(() => {
    expect(screen.getByText(/email is required/i)).toBeInTheDocument();
  });
});

Best Practice

Query elements by role, label, or visible text rather than className or data-testidwhenever possible — it keeps tests aligned with actual accessibility.

🎭 11. Playwright

Playwright automates real browsers (Chromium, Firefox, WebKit) and is well-suited for comprehensive E2E coverage with strong parallelization support.

Installing Playwright

npm init playwright@latest

e2e/homepage.spec.ts

import { test, expect } from "@playwright/test";

test("homepage displays the hero heading", async ({ page }) => {
  await page.goto("http://localhost:3000");
  await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
});

Tip

Use Playwright's webServer config option to automatically start your Next.js dev server before running tests in CI.

🌲 12. Cypress

Cypress offers an interactive test runner with time-travel debugging, making it popular for teams that want a visual, developer-friendly E2E experience.

cypress/e2e/login.cy.js

describe("Login flow", () => {
  it("logs in with valid credentials", () => {
    cy.visit("/login");
    cy.get("#email").type("user@example.com");
    cy.get("#password").type("password123");
    cy.get("button[type=submit]").click();
    cy.url().should("include", "/dashboard");
  });
});

Note

Cypress runs entirely inside the browser, which makes debugging intuitive but limits testing to a single tab or origin at a time, unlike Playwright's multi-context support.

🧩 13. Testing Components

Render components with realistic props and assert on what a user would actually see, not internal state.

components/Badge.test.tsx

import { render, screen } from "@testing-library/react";
import { Badge } from "./Badge";

it("renders the provided label", () => {
  render(<Badge label="New" />);
  expect(screen.getByText("New")).toBeInTheDocument();
});

🖥️ 14. Testing Server Components

Server Components are async functions that render to a string on the server, so they're typically tested by awaiting the component and checking the resulting output, rather than using standard RTL render calls.

app/products/page.test.tsx

import { render, screen } from "@testing-library/react";
import ProductsPage from "./page";

jest.mock("@/lib/api", () => ({
  getProducts: jest.fn().mockResolvedValue([{ id: "1", name: "Mug" }]),
}));

it("renders fetched products", async () => {
  const ui = await ProductsPage();
  render(ui);

  expect(screen.getByText("Mug")).toBeInTheDocument();
});

Caution

Direct unit testing of async Server Components is still an evolving area — many teams cover this logic instead through integration or E2E tests against a running app.

💻 15. Testing Client Components

Client Components behave like standard React components and can be tested normally with React Testing Library, including interactions and state changes.

components/Counter.test.tsx

"use client";

import { render, screen, fireEvent } from "@testing-library/react";
import { Counter } from "./Counter";

it("increments the count on click", () => {
  render(<Counter />);
  fireEvent.click(screen.getByRole("button"));
  expect(screen.getByText("Count: 1")).toBeInTheDocument();
});

🔌 16. Testing Route Handlers

Route Handlers can be tested by importing the exported HTTP method functions directly and invoking them with a mock Request.

app/api/users/route.test.ts

import { GET } from "./route";

it("returns a list of users", async () => {
  const response = await GET(new Request("http://localhost/api/users"));
  const data = await response.json();

  expect(response.status).toBe(200);
  expect(Array.isArray(data)).toBe(true);
});

⚡ 17. Testing Server Actions

Server Actions are plain async functions once you strip away the "use server" directive, so they can be imported and called directly in tests, typically with a mocked FormData.

app/actions.test.ts

import { createPost } from "./actions";

it("rejects an empty title", async () => {
  const formData = new FormData();
  formData.set("title", "");

  const result = await createPost(formData);

  expect(result.success).toBe(false);
  expect(result.error).toBe("Title is required");
});

🛡️ 18. Testing Middleware

Middleware functions can be tested by invoking them with a mock NextRequest and asserting on the returned NextResponse.

middleware.test.ts

import { NextRequest } from "next/server";
import { middleware } from "./middleware";

it("redirects unauthenticated users to login", () => {
  const request = new NextRequest("http://localhost/dashboard");
  const response = middleware(request);

  expect(response.status).toBe(307);
  expect(response.headers.get("location")).toContain("/login");
});

📡 19. Testing API Requests

Mock outgoing fetch calls so tests remain fast and don't depend on real network availability.

lib/api.test.ts

import { getPost } from "./api";

beforeEach(() => {
  global.fetch = jest.fn().mockResolvedValue({
    ok: true,
    json: async () => ({ id: 1, title: "Hello" }),
  }) as jest.Mock;
});

it("fetches and returns a post", async () => {
  const post = await getPost(1);
  expect(post.title).toBe("Hello");
});

🎭 20. Mocking

Mocking replaces real dependencies — databases, APIs, timers — with controlled stand-ins, keeping tests fast, deterministic, and isolated.

jest.mock() replaces entire modules with mock implementations.
jest.fn() creates a trackable mock function for asserting calls and arguments.
jest.spyOn() wraps an existing method while preserving the ability to restore it later.

Mocking a module

jest.mock("@/lib/db", () => ({
  getUser: jest.fn().mockResolvedValue({ id: "1", name: "Ada" }),
}));

Warning

Over-mocking can make tests pass while the real integration is broken. Balance mocked unit tests with a smaller number of integration or E2E tests that exercise real code paths.

📸 21. Snapshot Testing

Snapshot tests capture a component's rendered output and flag future changes for review, useful for catching unintentional UI regressions.

components/Badge.snapshot.test.tsx

import { render } from "@testing-library/react";
import { Badge } from "./Badge";

it("matches the snapshot", () => {
  const { container } = render(<Badge label="New" />);
  expect(container).toMatchSnapshot();
});

Caution

Snapshot tests can become noiseif overused — a broad snapshot of a large tree often just gets blindly updated rather than genuinely reviewed. Prefer targeted assertions where possible.

♿ 22. Accessibility Testing

Automated accessibility (a11y) checks catch common issues like missing labels, poor color contrast, and invalid ARIA attributes.

components/LoginForm.a11y.test.tsx

import { render } from "@testing-library/react";
import { axe, toHaveNoViolations } from "jest-axe";
import { LoginForm } from "./LoginForm";

expect.extend(toHaveNoViolations);

it("has no accessibility violations", async () => {
  const { container } = render(<LoginForm />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Tip

Automated tools like jest-axecatch roughly a third of accessibility issues — pair them with manual keyboard navigation and screen reader testing for full coverage.

🏎️ 23. Performance Testing

Performance testing verifies your app meets latency and rendering targets under realistic conditions, using tools like Lighthouse or Playwright's tracing features.

e2e/performance.spec.ts

import { test, expect } from "@playwright/test";

test("homepage loads within budget", async ({ page }) => {
  const start = Date.now();
  await page.goto("/");
  await page.waitForLoadState("networkidle");

  expect(Date.now() - start).toBeLessThan(3000);
});

📊 24. Code Coverage

Coverage reports show which lines, branches, and functions your test suite actually exercises, helping identify untested code paths.

Running tests with coverage

npx jest --coverage
# or
npx vitest run --coverage

Best Practice

Treat coverage percentage as a signal, not a target — 100% coverage doesn't guarantee correctness, and chasing it can encourage low-value tests.

🔄 25. Continuous Integration

Run your full test suite automatically on every push and pull request to catch regressions before they merge.

.github/workflows/test.yml

name: Run Tests

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm ci

      - name: Run unit and integration tests
        run: npm test -- --coverage

      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Run E2E tests
        run: npx playwright test

🐞 26. Debugging Tests

Use screen.debug() in React Testing Library to print the current rendered DOM.
Run Playwright in headed mode with --headed to visually watch a test execute.
Use test.only or it.only to isolate a single failing test during debugging.
Enable Playwright's trace viewer with --trace on to inspect a full failure timeline.

Tip

Playwright's npx playwright test --debugopens an interactive inspector that steps through each action — invaluable for diagnosing flaky tests.

✅ 27. Best Practices

Test behavior, not implementation details — avoid asserting on internal state or class names.
Keep unit tests fast and isolated; push slower checks to integration or E2E layers.
Use realistic, minimal mocks — don't mock more than necessary.
Name tests descriptively so failures immediately communicate what broke.
Run the full suite in CI before every merge to main.

⚠️ 28. Common Mistakes

Mistake	Consequence	Fix
Testing implementation details	Tests break on harmless refactors	Query by role/text, assert on visible behavior
Overusing snapshots	Failures get blindly approved without review	Prefer targeted, explicit assertions
No CI enforcement	Broken tests merge unnoticed	Require passing tests before merge
Flaky E2E tests	Team starts ignoring failures	Use proper waits instead of fixed timeouts

Danger

Never use hardcoded sleep()or fixed timeouts to "fix" flaky tests — they mask race conditions rather than resolving them, and slow the whole suite down.

❓ 29. Frequently Asked Questions

Question

Should I use Jest or Vitest for a new Next.js project?

Answer

Both work well. Vitest tends to run faster and integrates naturally with Vite-based tooling, while Jest has broader ecosystem maturity and is what next/jest is specifically built for.

Question

Do I need both Playwright and Cypress?

Answer

No, they serve the same purpose. Choose one based on team preference — Playwright offers stronger multi-browser and multi-tab support, while Cypress offers a more visual, beginner-friendly debugging experience.

Question

How do I test a page that requires authentication?

Answer

In E2E tests, use Playwright's or Cypress's stored authentication state feature to log in once and reuse the session across tests, avoiding repeated slow login flows.

📌 30. Summary

Effective testing in Next.js combines fast unit tests for logic, integration tests for components and API boundaries, and a focused set of E2E tests for critical user journeys — all enforced automatically through CI.

Summary

Follow the testing pyramid: many unit tests, fewer integration tests, a lean E2E suite.
Test Server Components, Route Handlers, and Server Actions as plain async functions.
Mock external dependencies, but don't over-mock to the point of testing nothing real.
Include accessibility and performance checks alongside functional tests.
Run the full suite in CI on every pull request before merging.

>>"A test suite is a safety net — the tighter the weave, the more confidently your team can move fast."

ℹ️Information

📖 1. Introduction

🎯 2. Why Test Next.js Applications?

💡Tip

🏗️ 3. Types of Testing

⭐Best Practice

🔬 4. Unit Testing

lib/formatPrice.test.ts

🔗 5. Integration Testing

components/SearchBar.test.tsx

🌐 6. End-to-End Testing

e2e/checkout.spec.ts

⚠️Warning

🧰 7. Test Environment Setup

🃏 8. Jest

Installing Jest for Next.js

jest.config.js

💡Tip

⚡ 9. Vitest

Installing Vitest

vitest.config.ts

ℹ️Information

🧪 10. React Testing Library

components/LoginForm.test.tsx

⭐Best Practice

🎭 11. Playwright

Installing Playwright

e2e/homepage.spec.ts

💡Tip

🌲 12. Cypress

cypress/e2e/login.cy.js

📝Note

🧩 13. Testing Components

components/Badge.test.tsx

🖥️ 14. Testing Server Components

app/products/page.test.tsx

🟡Caution

💻 15. Testing Client Components

components/Counter.test.tsx

🔌 16. Testing Route Handlers

app/api/users/route.test.ts

⚡ 17. Testing Server Actions

app/actions.test.ts

🛡️ 18. Testing Middleware

middleware.test.ts

📡 19. Testing API Requests

lib/api.test.ts

🎭 20. Mocking

Mocking a module

⚠️Warning

📸 21. Snapshot Testing

components/Badge.snapshot.test.tsx

🟡Caution

♿ 22. Accessibility Testing

components/LoginForm.a11y.test.tsx

💡Tip

🏎️ 23. Performance Testing

e2e/performance.spec.ts

📊 24. Code Coverage

Running tests with coverage

⭐Best Practice

🔄 25. Continuous Integration

.github/workflows/test.yml

🐞 26. Debugging Tests

💡Tip

✅ 27. Best Practices

⚠️ 28. Common Mistakes

🚫Danger

❓ 29. Frequently Asked Questions

❓Question

💬Answer

❓Question

💬Answer

❓Question

💬Answer

📌 30. Summary

📋Summary

Information

Tip

Best Practice

Warning

Tip

Information

Best Practice

Tip

Note

Caution

Warning

Caution

Tip

Best Practice

Tip

Danger

Question

Answer

Question

Answer

Question

Answer

Summary