Testing Next.js Components

A test that renders the tea shop's home page

In the React course, Testing React components tested components with Vitest and React Testing Library: render a component, find what it shows by role, click with user-event, and check the screen. A Next.js app's pages and components are React components, so the same tools test them. What changes is what's around them. In the app, Next.js gives each component a router, a request and a server that renders it. In a test, Next.js isn't running at all, so whatever the code asks Next.js for has to be a mock: a replacement module or function that the test controls (Mocks, spies & fakes builds them in plain JavaScript).

Here is the tea shop's home page and its test, in a real Next.js 16.4.3 project. The recorder ran npx vitest run --reporter=verbose in it, the way continuous integration (CI) does: a server that runs the tests on every change, then built it with next build and asked next start for /. Click a file in the tree to read it.

1import { expect, test } from "vitest";2import { render, screen } from "@testing-library/react";3import userEvent from "@testing-library/user-event";4import Home from "./page";5 6test("shows today's tea and a link to every tea", () => {7  render(<Home />);8  expect(screen.getByRole("heading", { level: 1, name: "Tea shop" })).toBeInTheDocument();9  expect(screen.getByText("Tea of the day: Mint tea, $3")).toBeInTheDocument();10  expect(screen.getByRole("link", { name: "See every tea" })).toHaveAttribute("href", "/teas");11});12 13test("adds Mint tea to the cart", async () => {14  const user = userEvent.setup();15  render(<Home />);16  await user.click(screen.getByRole("button", { name: "Add Mint tea" }));17  await user.click(screen.getByRole("button", { name: "Add Mint tea" }));18  expect(screen.getByText("In your cart: 2")).toBeInTheDocument();19});

$ npx vitest run --reporter=verbose RUN  v5.0.5 /my-app  ✓ app/page.test.tsx > shows today's tea and a link to every tea ✓ app/page.test.tsx > adds Mint tea to the cart  Test Files  1 passed (1)      Tests  2 passed (2) $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /└ ○ /_not-found ○  (Static)  prerendered as static content

app/page.test.tsx sits next to the page. It doesn't become a route: only files named page or route do. Line 4 imports Home from ./page, the same component Next.js shows at /. Home is a Server Component that isn't async: a function that returns JSX. So line 7 renders it like any component, and lines 8 to 10 find its heading, its text, and its link to /teas.

The second test clicks Add Mint tea twice (lines 16 and 17), and line 18 finds In your cart: 2. That button is AddToCart, a Client Component: app/add-to-cart.tsx starts with "use client", keeps the count in state, and Home renders it on line 10 of app/page.tsx.

The Terminal tab shows both runs. First Vitest's report: a ✓ for each test, then Tests 2 passed (2). Then $ next build, which printed ○ /. Open the Browser tab: next start sent the same heading, text and link that the test found.

Setting up Vitest in a Next.js app

A test of a React component uses several tools, each with one job. Each row is one package, what it does, and where it runs:

Next.js's Vitest guide installs vitest, @vitejs/plugin-react, jsdom, @testing-library/react and @testing-library/dom. user-event and jest-dom are the two the React course's tests also use. On October 30, 2026, npm's latest Vitest is 5.0.5, which runs on Vite 8.3.5. One command installs them as development tools:

npm install --save-dev vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom @testing-library/user-event @testing-library/jest-dom @types/node@22

The last package, @types/node@22, is there for a reason. In a project create-next-app 16.4.3 just made, npm refuses to install Vitest 5.0.5 on its own, with an ERESOLVE error: Vitest asks for @types/node ^22.0.0 || >=24.0.0 as a peer dependency, and create-next-app writes "@types/node": "^20". Asking for version 22 in the same command fixes it. (The recorded projects keep create-next-app's @types/node, because the recorder links its pinned packages in itself.)

Then a config file tells Vitest how to read your files. This is the one Next.js's guide writes for TypeScript, with a setup file added, in a recorded project:

1import { defineConfig } from "vitest/config";2import react from "@vitejs/plugin-react";3import tsconfigPaths from "vite-tsconfig-paths";4 5export default defineConfig({6  plugins: [tsconfigPaths(), react()],7  test: {8    environment: "jsdom",9    setupFiles: ["./vitest.setup.ts"],10  },11});

$ npx vitest run --reporter=verboseThe plugin "vite-tsconfig-paths" is detected. Vite now supports tsconfig paths resolution natively via the resolve.tsconfigPaths option. You can remove the plugin and set resolve.tsconfigPaths: true in your Vite config instead.  RUN  v5.0.5 /my-app  ✓ app/page.test.tsx > shows today's tea and a link to every tea ✓ app/page.test.tsx > adds Mint tea to the cart  Test Files  1 passed (1)      Tests  2 passed (2) $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /└ ○ /_not-found ○  (Static)  prerendered as static content

In vitest.config.mts, line 6 adds two Vite plugins. Vite itself strips the TypeScript types; react(), from @vitejs/plugin-react, applies React's JSX transform (and Fast Refresh, which only matters in a dev server). tsconfigPaths(), from line 3, reads the @/* path in tsconfig.json, so an import like @/lib/teas on line 2 of app/page.tsx works in a test as it does in Next.js. Line 8 gives every test file a jsdom page, and line 9 runs a setup file before each test file.

Open the Terminal tab. Before RUN, Vite printed: The plugin "vite-tsconfig-paths" is detected. Vite now supports tsconfig paths resolution natively via the resolve.tsconfigPaths option. The tests still passed. Vite 8.3.5 reads the paths itself, so the shop's config does without the plugin:

1import { defineConfig } from "vitest/config";2import react from "@vitejs/plugin-react";3 4export default defineConfig({5  plugins: [react()],6  resolve: { tsconfigPaths: true },7  test: {8    environment: "jsdom",9    setupFiles: ["./vitest.setup.ts"],10  },11});12 

Line 6, resolve: { tsconfigPaths: true }, takes the plugin's place. The shop's other projects use this file, and none of their reports has the message. The setup file is the same as the React course's:

import "@testing-library/jest-dom/vitest";
import { cleanup } from "@testing-library/react";
import { afterEach } from "vitest";

afterEach(() => {
  cleanup();
});

Line 1 adds jest-dom's matchers, like toBeInTheDocument and toHaveValue, to Vitest's expect. Lines 5 to 7 call cleanup after each test, which removes what the test rendered. Testing Library only does that by itself when it finds a global afterEach, and Vitest makes none unless you set globals: true.

To run the tests, add scripts to package.json. npx vitest in a terminal keeps watching your files and runs the tests again each time you save. npx vitest run runs them once and exits with code 0 when every test passed, or 1 when one failed, which is what a CI job needs. --reporter=verbose, which the recordings add, prints a line for each test.

{
  "scripts": {
    "test": "vitest",
    "test:ci": "vitest run"
  }
}

next build doesn't run tests. It does type-check every file that tsconfig.json includes, and create-next-app's include list takes every .ts, .tsx and .mts file: your tests and vitest.config.mts too. A type error in a test stops the build, as one in a page would.

Jest, with next/jest

Next.js also has a guide for Jest, the older test runner many projects use (version 30.5.2 on October 30, 2026). Its config goes through next/jest, a helper that ships with Next.js:

import type { Config } from "jest";
import nextJest from "next/jest.js";

const createJestConfig = nextJest({
  // Where the app is, so next/jest can read next.config.ts and .env files.
  dir: "./",
});

const config: Config = {
  testEnvironment: "jsdom",
  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],
};

export default createJestConfig(config);

Line 4 makes the helper, and line 6 tells it where the app is. Line 14 passes your own settings through it. Next.js's guide lists what next/jest sets up: it turns your files into JavaScript with Next.js's own compiler (SWC), replaces stylesheets, images and next/font with stand-ins, loads your .env files and next.config, and leaves node_modules and .next out. The tests themselves look the same as Vitest's, with Jest's jest.fn() and jest.mock() in place of vi.fn() and vi.mock(). The guide gives Jest the same limit as Vitest for async Server Components. This course records Vitest, so every report on this page is Vitest's.

Client Components: render, click, check

To Vitest, "use client" on line 1 of app/add-to-cart.tsx is a string that does nothing. In the app, it marks where the client part of the page starts. In a test, the component is a function like any other, and the overview's test clicked it and read its state on the screen. A Client Component that uses only React, like AddToCart, needs nothing more.

Many Client Components in a Next.js app call something that isn't React. This form calls a Server Action, addTea, through useActionState, as Forms in Next.js showed. In a test, the action is replaced, so the test checks the form alone: what it sends, and what it shows with the answer.

1import { expect, test, vi } from "vitest";2import { render, screen } from "@testing-library/react";3import userEvent from "@testing-library/user-event";4import { addTea } from "./actions";5import AddTeaForm from "./add-tea-form";6 7vi.mock("./actions", () => ({8  addTea: vi.fn(async () => ({ message: "Added Mint tea." })),9}));10 11test("sends the chosen tea and shows the answer", async () => {12  const user = userEvent.setup();13  render(<AddTeaForm />);14  await user.selectOptions(screen.getByLabelText("Tea"), "Mint tea");15  await user.click(screen.getByRole("button", { name: "Add to cart" }));16  expect(await screen.findByText("Added Mint tea.")).toBeInTheDocument();17  expect(addTea).toHaveBeenCalledTimes(1);18  const [previous, formData] = vi.mocked(addTea).mock.calls[0];19  expect(previous).toEqual({ message: "" });20  expect(formData.get("tea")).toBe("mint");21});

$ npx vitest run --reporter=verbose RUN  v5.0.5 /my-app  ✓ app/teas/add-tea-form.test.tsx > sends the chosen tea and shows the answer  Test Files  1 passed (1)      Tests  1 passed (1) $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /_not-found└ ○ /teas ○  (Static)  prerendered as static content

In app/teas/add-tea-form.test.tsx, lines 7 to 9 replace the module ./actions with one whose addTea is a mock function, made with vi.fn, that answers { message: "Added Mint tea." }. Line 4 imports that mock, not the real action. Line 14 picks Mint tea, line 15 clicks Add to cart, and line 16 waits until the answer shows. Then the test reads what the form sent: line 18 takes the first call's two arguments, the previous state and the form's FormData, line 19 checks the state, and line 20 checks the tea.

This works because React 19 runs a form's action in the browser too: useActionState calls whatever function it got. In the app, that function is Next.js's reference to the Server Action, which sends a request. In the test, it's the mock, and nothing leaves the test. The action's own code gets a test of its own, further down.

Server Components: plain ones render, async ones don't

Home rendered because it isn't async. The teas page is: it waits for getTeas(), a stand-in for a database query, before it returns.

1import { getTeas } from "@/lib/teas";2 3export default async function TeasPage() {4  const teas = await getTeas();5  return (6    <main>7      <h1>Our teas</h1>8      <ul>9        {teas.map((tea) => (10          <li key={tea.id}>11            {tea.name}: ${tea.price}12          </li>13        ))}14      </ul>15    </main>16  );17}18 

Line 3 makes TeasPage an async function, so line 4 can wait for the teas. In the app, Next.js renders it on the server, where React waits for it. Try both ways to test it:

1import { expect, test } from "vitest";2import { render, screen } from "@testing-library/react";3import TeasPage from "./page";4 5test("lists every tea", async () => {6  render(<TeasPage />);7  expect(await screen.findByRole("heading", { name: "Our teas" })).toBeInTheDocument();8  expect(screen.getAllByRole("listitem")).toHaveLength(3);9});

$ npx vitest run --reporter=verbose RUN  v5.0.5 /my-app stderr | app/teas/page.test.tsx > lists every tea<TeasPage> is an async Client Component. Only Server Components can be async at the moment. This error is often caused by accidentally adding `'use client'` to a module that was originally written for the server. stderr | app/teas/page.test.tsx > lists every teaA component suspended inside an `act` scope, but the `act` call was not awaited. When testing React components that depend on asynchronous data, you must await the result: await act(() => ...)  × app/teas/page.test.tsx > lists every tea   → Unable to find role="heading" and name "Our teas" Ignored nodes: comments, script, style<body>  <div /></body> Ignored nodes: comments, script, style<body>  <div /></body> ⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯  FAIL  app/teas/page.test.tsx > lists every teaTestingLibraryElementError: Unable to find role="heading" and name "Our teas" Ignored nodes: comments, script, style<body>  <div /></body> Ignored nodes: comments, script, style<body>  <div /></body> ❯ waitForWrapper node_modules/@testing-library/dom/dist/wait-for.js:163:27 ❯ node_modules/@testing-library/dom/dist/query-helpers.js:86:33 ❯ app/teas/page.test.tsx:7:23      5| test("lists every tea", async () => {      6|   render(<TeasPage />);      7|   expect(await screen.findByRole("heading", { name: "Our teas" })).toB…       |                       ^      8|   expect(screen.getAllByRole("listitem")).toHaveLength(3);      9| }); ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯   Test Files  1 failed (1)      Tests  1 failed (1) $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /_not-found└ ○ /teas ○  (Static)  prerendered as static content

The first version fails. Testing Library's render renders the page with React's client renderer, React DOM, on the jsdom page, not with the renderer Next.js uses for Server Components. So React treats the async function as an async component on the client, which it doesn't support yet, and printed: <TeasPage> is an async Client Component. Only Server Components can be async at the moment. The page stayed an empty <div />, and findByRole gave up after waiting. Next.js's Vitest and Jest guides say it plainly: Vitest doesn't support async Server Components yet, and they recommend end-to-end tests for them.

The second version calls TeasPage() itself, waits for the JSX it returns, and renders that. It passed, but only because nothing below the page is async, and the page reads nothing from the request. An async component inside it would fail the same way, and a page that calls cookies() would throw, as the data access layer shows below. It also skips everything Next.js does around a page: layouts, loading.tsx, Suspense and streaming. Use it for small pages, and test the real page from the outside, as End-to-end testing does.

Mocking next/navigation

The teas page has a sort menu. Choosing Price changes the address to /teas?sort=price, so the page can read the search params and sort the list.

1"use client";2 3import { usePathname, useRouter, useSearchParams } from "next/navigation";4 5export default function SortSelect() {6  const router = useRouter();7  const pathname = usePathname();8  const searchParams = useSearchParams();9  const sort = searchParams.get("sort") ?? "name";10 11  function choose(next: string) {12    const params = new URLSearchParams(searchParams);13    params.set("sort", next);14    router.push(`${pathname}?${params}`);15  }16 17  return (18    <label>19      Sort by{" "}20      <select value={sort} onChange={(event) => choose(event.target.value)}>21        <option value="name">Name</option>22        <option value="price">Price</option>23      </select>24    </label>25  );26}27 

Lines 6 to 8 call three hooks from next/navigation: useRouter for the router, usePathname for the path, /teas, and useSearchParams for the query. Line 9 reads the current sort. When the menu changes, line 12 copies the query, line 13 sets sort, and line 14 asks the router to go to the new address, as Linking and navigating showed with router.push.

1import { expect, test } from "vitest";2import { render, screen } from "@testing-library/react";3import SortSelect from "./sort-select";4 5test("starts sorted by name", () => {6  render(<SortSelect />);7  expect(screen.getByLabelText("Sort by")).toHaveValue("name");8});

$ npx vitest run --reporter=verbose RUN  v5.0.5 /my-app  × app/teas/sort-select.test.tsx > starts sorted by name   → invariant expected app router to be mounted ⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯  FAIL  app/teas/sort-select.test.tsx > starts sorted by nameError: invariant expected app router to be mounted ❯ useRouter node_modules/next/src/client/components/navigation.ts:169:11 ❯ SortSelect app/teas/sort-select.tsx:6:18      4|      5| export default function SortSelect() {      6|   const router = useRouter();       |                  ^      7|   const pathname = usePathname();      8|   const searchParams = useSearchParams(); ❯ Object.react_stack_bottom_frame node_modules/react-dom/cjs/react-dom-client.development.js:28571:20 ❯ renderWithHooks node_modules/react-dom/cjs/react-dom-client.development.js:8030:22 ❯ updateFunctionComponent node_modules/react-dom/cjs/react-dom-client.development.js:10569:19 ❯ beginWork node_modules/react-dom/cjs/react-dom-client.development.js:12205:18 ❯ runWithFiberInDEV node_modules/react-dom/cjs/react-dom-client.development.js:1048:13 ❯ performUnitOfWork node_modules/react-dom/cjs/react-dom-client.development.js:19176:22 ❯ workLoopSync node_modules/react-dom/cjs/react-dom-client.development.js:19004:41 ❯ renderRootSync node_modules/react-dom/cjs/react-dom-client.development.js:18985:11 ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯   Test Files  1 failed (1)      Tests  1 failed (1) $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /_not-found└ ○ /teas ○  (Static)  prerendered as static content

Without a mock, the first hook threw. useRouter reads the router from React context, where Next.js's App Router puts it for every page, and throws when it finds none (navigation.ts, lines 166 to 170). A test renders the component with no App Router around it.

In the mocked version, vi.mock on lines 8 to 12 answers import ... from "next/navigation" with an object of three functions, for every file in this test. Vitest moves each vi.mock call above the file's imports, so the mock is ready before ./sort-select loads. That's why push is made on line 6 with vi.hoisted, which moves up with it: a plain const push = vi.fn() wouldn't exist yet when the factory ran. beforeEach on lines 14 to 16 clears push's calls, so each test starts from zero. Line 26 chooses Price, and lines 27 and 28 check that push was called once, with /teas?sort=price.

A mock answers only for the names it returns. Leave one out, and Vitest stops at the first use of it, with an error that names it:

1import { expect, test, vi } from "vitest";2import { render, screen } from "@testing-library/react";3import SortSelect from "./sort-select";4 5vi.mock("next/navigation", () => ({6  useRouter: () => ({ push: vi.fn() }),7  usePathname: () => "/teas",8}));9 10test("starts sorted by name", () => {11  render(<SortSelect />);12  expect(screen.getByLabelText("Sort by")).toHaveValue("name");13});14 

The recorded run of this file failed on line 8 of sort-select.tsx: No "useSearchParams" export is defined on the "next/navigation" mock. Mock every function the component calls, including useParams, redirect or notFound when it uses them. A mock also checks only what your component asked for. Whether the page really changed, and what the router fetched, is a question for an end-to-end test.

server-only, cookies() and the data access layer

The shop keeps one way to know who is asking: getCurrentUser in lib/current-user.ts, its data access layer. Line 1 imports server-only, so a Client Component that imports it stops the build (Server-only code showed how). Line 6 reads the session cookie with cookies(), and line 8 looks the session up in a stand-in for the sessions table. Its test calls it like any async function.

First, the package. Next.js handles import "server-only" itself, so create-next-app doesn't install it, and a Next.js app works without it. Vitest isn't Next.js: it looks for the package like any import, so a test that loads this module needs npm install server-only. Each version below has it. Pick them in order: each one fixes the error the one before it hit.

1import "server-only";2import { cookies } from "next/headers";3import { findSession } from "./sessions";4 5export async function getCurrentUser() {6  const id = (await cookies()).get("session")?.value;7  if (!id) return null;8  return findSession(id);9}

$ npx vitest run --reporter=verbose RUN  v5.0.5 /my-app  ⎯⎯⎯⎯⎯⎯ Failed Suites 1 ⎯⎯⎯⎯⎯⎯⎯  FAIL  lib/current-user.test.ts [ lib/current-user.test.ts ]Error: This module cannot be imported from a Client Component module. It should only be used from a Server Component. ❯ Object.<anonymous> node_modules/server-only/index.js:1:7 ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯   Test Files  1 failed (1)      Tests  no tests $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /_not-found└ ◐ /account ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

Two things stood in the way, and each one is something only Next.js provides:

1. The package throws. Its package.json sends code built with the react-server condition, like Next.js's Server Components, to an empty file, and everything else to a file that throws. Vitest gets the throwing one, so line 6 of the setup file replaces it with an empty module, for every test. (The message names Client Components because, in a Next.js app, only their code reaches that file.)
2. cookies() needs a request. It reads the cookies of the request being answered, and throws outside one (cookies.ts, line 146). The last version replaces next/headers with a cookies() that reads a Map, which each test fills.

Pick the last version and open its Browser tab: the real /account, from next start, says You're not signed in. without a cookie, and Signed in as Asha with Asha's. The tests checked the same two answers through the mock. headers() works the same way: mock next/headers with each function your code calls.

A Server Action is an async function in a test

addTea, the action the tea form calls, checks who is asking, checks the tea, saves it to the cart, and updates the cart's cache. Every Server Action is a public endpoint, so the first two checks matter most (Securing Server Actions). In a test, "use server" on its line 1 is a plain string again, and addTea is an async function you can import and call with a FormData:

1import { beforeEach, expect, test, vi } from "vitest";2import { addToCart } from "@/lib/cart";3import { getCurrentUser } from "@/lib/current-user";4import { addTea } from "./actions";5 6vi.mock("@/lib/current-user", () => ({ getCurrentUser: vi.fn() }));7vi.mock("@/lib/cart", () => ({ addToCart: vi.fn() }));8 9function teaForm(tea: string) {10  const formData = new FormData();11  formData.set("tea", tea);12  return formData;13}14 15beforeEach(() => {16  vi.clearAllMocks();17});18 19test("asks a visitor to sign in first", async () => {20  vi.mocked(getCurrentUser).mockResolvedValue(null);21  expect(await addTea({ message: "" }, teaForm("mint"))).toEqual({ message: "Sign in to add teas." });22  expect(addToCart).not.toHaveBeenCalled();23});24 25test("adds the tea to the signed-in user's cart", async () => {26  vi.mocked(getCurrentUser).mockResolvedValue({ id: "u1", name: "Asha" });27  expect(await addTea({ message: "" }, teaForm("mint"))).toEqual({ message: "Added Mint tea." });28  expect(addToCart).toHaveBeenCalledWith("u1", "mint");29});

$ npx vitest run --reporter=verbose RUN  v5.0.5 /my-app  ✓ app/teas/actions.test.ts > asks a visitor to sign in first × app/teas/actions.test.ts > adds the tea to the signed-in user's cart   → updateTag can only be called from within a Server Action. To invalidate cache tags in Route Handlers or other contexts, use revalidateTag instead. See more info here: https://nextjs.org/docs/app/api-reference/functions/updateTag ⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯  FAIL  app/teas/actions.test.ts > adds the tea to the signed-in user's cartError: updateTag can only be called from within a Server Action. To invalidate cache tags in Route Handlers or other contexts, use revalidateTag instead. See more info here: https://nextjs.org/docs/app/api-reference/functions/updateTag ❯ updateTag node_modules/next/src/server/web/spec-extension/revalidate.ts:64:11 ❯ Module.addTea app/teas/actions.ts:16:3     14|   if (!tea) return { message: "Pick a tea from the list." };     15|   await addToCart(user.id, tea.id);     16|   updateTag(`cart-${user.id}`);       |   ^     17|   return { message: `Added ${tea.name}.` };     18| } ❯ app/teas/actions.test.ts:27:10 ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯   Test Files  1 failed (1)      Tests  1 failed | 1 passed (2) $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /_not-found└ ○ /teas ○  (Static)  prerendered as static content

Pick the second version. In its app/teas/actions.test.ts, lines 7 and 8 replace the data access layer and the cart with mock functions, so each test decides who is signed in: line 22 nobody, lines 28 and 35 Asha. teaForm, on lines 11 to 15, makes the FormData a form would send. Line 18 clears the mocks' calls before each test. Then each test checks what the action returned, and what it saved: nothing for a visitor who isn't signed in (line 24), Mint tea for Asha (line 30), and nothing for coffee, which isn't on the list (line 37).

Without line 9, the second test failed on updateTag: updateTag can only be called from within a Server Action. But addTea is a Server Action. The error says what calling it directly skips. When the browser posts the form, Next.js's action layer runs before your function:

• It finds the action by the id the form sent.
• It checks that the Origin header matches the host, and refuses a post from another site (action-handler.ts, lines 731 to 745).
• It decrypts the values a closure captured, if the action is defined inside a component.
• It runs your function inside the request, so cookies() and updateTag work (revalidate.ts, lines 58 to 68).

So a unit test of an action proves your own checks: who may call it, what it accepts, what it saves and what it returns. It can't prove that Next.js's layer works for your app: that the form posts, the origin check passes, and the page shows the answer. An end-to-end test that fills in the real form checks that.

A unit test or an end-to-end test?

Each mock stood in for something Next.js gives a component in the app. Each row is one of them: what the app gives, and what happens in a Vitest test, as the recordings showed.

A good split for the tea shop: Vitest tests for the logic in components, actions and the data access layer, which run in a second and point at the line that broke, and a few end-to-end tests for what needs Next.js running. Sort each check:

Common mix-ups

• "A Next.js app needs its own test runner." No. Vitest or Jest with Testing Library test its components, as they test any React app. Next.js only adds next/jest, a config helper for Jest.
• "next build runs my tests." No. It type-checks them with the rest of the project and never runs them. Run vitest run yourself, in CI too.
• "Server Components can't be unit-tested." Ones that aren't async can: Home rendered like any component. Async ones can't be rendered by Testing Library yet.
• "findBy will wait for an async Server Component." No. It waited, and the page stayed an empty <div />: React DOM never rendered it.
• "Mocking next/navigation tests the navigation." No. It checks what your component asked the router to do. Whether the page changed is for an end-to-end test.
• "A passing Server Action test means the action is safe." Only your own checks ran. The test called the function directly, so Next.js's action id lookup and origin check never did.

Practice exercises

These exercises are about Next.js projects and their tests, which can't run inside this page. Answer first, then use the hints.

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

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

import { getTeas } from "@/lib/teas";

export default async function TeasPage() {
  const teas = await getTeas();
  return (
    <main>
      <h1>Our teas</h1>
      <ul>
        {teas.map((tea) => (
          <li key={tea.id}>
            {tea.name}: ${tea.price}
          </li>
        ))}
      </ul>
    </main>
  );
}

"use client";

import { usePathname, useRouter, useSearchParams } from "next/navigation";

export default function SortSelect() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();
  const sort = searchParams.get("sort") ?? "name";

  function choose(next: string) {
    const params = new URLSearchParams(searchParams);
    params.set("sort", next);
    router.push(`${pathname}?${params}`);
  }

  return (
    <label>
      Sort by{" "}
      <select value={sort} onChange={(event) => choose(event.target.value)}>
        <option value="name">Name</option>
        <option value="price">Price</option>
      </select>
    </label>
  );
}

import { expect, test, vi } from "vitest";
import { render, screen } from "@testing-library/react";
import SortSelect from "./sort-select";

vi.mock("next/navigation", () => ({
  useRouter: () => ({ push: vi.fn() }),
  usePathname: () => "/teas",
}));

test("starts sorted by name", () => {
  render(<SortSelect />);
  expect(screen.getByLabelText("Sort by")).toHaveValue("name");
});

import "@testing-library/jest-dom/vitest";
import { cleanup } from "@testing-library/react";
import { afterEach, vi } from "vitest";

// server-only throws outside Next.js's server bundles, and tests run outside them.
vi.mock("server-only", () => ({}));

afterEach(() => {
  cleanup();
});

import { beforeEach, expect, test, vi } from "vitest";
import { addToCart } from "@/lib/cart";
import { getCurrentUser } from "@/lib/current-user";
import { addTea } from "./actions";

vi.mock("@/lib/current-user", () => ({ getCurrentUser: vi.fn() }));
vi.mock("@/lib/cart", () => ({ addToCart: vi.fn() }));

function teaForm(tea: string) {
  const formData = new FormData();
  formData.set("tea", tea);
  return formData;
}

beforeEach(() => {
  vi.clearAllMocks();
});

test("asks a visitor to sign in first", async () => {
  vi.mocked(getCurrentUser).mockResolvedValue(null);
  expect(await addTea({ message: "" }, teaForm("mint"))).toEqual({ message: "Sign in to add teas." });
  expect(addToCart).not.toHaveBeenCalled();
});

test("adds the tea to the signed-in user's cart", async () => {
  vi.mocked(getCurrentUser).mockResolvedValue({ id: "u1", name: "Asha" });
  expect(await addTea({ message: "" }, teaForm("mint"))).toEqual({ message: "Added Mint tea." });
  expect(addToCart).toHaveBeenCalledWith("u1", "mint");
});

import { beforeEach, expect, test, vi } from "vitest";
import { updateTag } from "next/cache";
import { addToCart } from "@/lib/cart";
import { getCurrentUser } from "@/lib/current-user";
import { addTea } from "./actions";

vi.mock("@/lib/current-user", () => ({ getCurrentUser: vi.fn() }));
vi.mock("@/lib/cart", () => ({ addToCart: vi.fn() }));
vi.mock("next/cache", () => ({ updateTag: vi.fn() }));

function teaForm(tea: string) {
  const formData = new FormData();
  formData.set("tea", tea);
  return formData;
}

beforeEach(() => {
  vi.clearAllMocks();
});

test("asks a visitor to sign in first", async () => {
  vi.mocked(getCurrentUser).mockResolvedValue(null);
  expect(await addTea({ message: "" }, teaForm("mint"))).toEqual({ message: "Sign in to add teas." });
  expect(addToCart).not.toHaveBeenCalled();
});

test("adds the tea to the signed-in user's cart", async () => {
  vi.mocked(getCurrentUser).mockResolvedValue({ id: "u1", name: "Asha" });
  expect(await addTea({ message: "" }, teaForm("mint"))).toEqual({ message: "Added Mint tea." });
  expect(addToCart).toHaveBeenCalledWith("u1", "mint");
  expect(updateTag).toHaveBeenCalledWith("cart-u1");
});

test("refuses a tea that isn't on the list", async () => {
  vi.mocked(getCurrentUser).mockResolvedValue({ id: "u1", name: "Asha" });
  expect(await addTea({ message: "" }, teaForm("coffee"))).toEqual({ message: "Pick a tea from the list." });
  expect(addToCart).not.toHaveBeenCalled();
});

Check your understanding

Key takeaways

• Vitest, jsdom and React Testing Library test a Next.js app's components as they test any React app. Install @types/node@22 with Vitest 5, and let Vite 8 read tsconfig.json's paths.
• Client Components and Server Components that aren't async render in a test. "use client" and "use server" do nothing there.
• Async Server Components don't render with Testing Library yet. Calling the page and rendering its JSX works only for simple pages; test them end to end.
• Mock what Next.js provides: next/navigation for the router, next/headers for the request, next/cache for updateTag, and server-only in the setup file.
• A Server Action is an async function in a test. Calling it checks your logic and skips Next.js's action layer, so an end-to-end test checks the real post.

Coming next: End-to-end testing. Playwright drives real Chrome against next build and next start, so the async teas page, streaming, navigations and forms get tested as visitors use them.