Testing

Next.js applications are usually tested on two levels. Unit tests check individual components and functions quickly, typically with Vitest or Jest plus React Testing Library. End-to-end (E2E) tests open pages in a real browser and walk through user flows, typically with Playwright or Cypress. This chapter focuses on setting up and writing tests with Vitest and Playwright.

What to test with which tool

async Server Components are relatively new to the React ecosystem, and unit test runners such as Vitest and Jest cannot fully render them yet. The official docs therefore recommend covering them with E2E tests. If you extract the data-processing logic from such a component into plain functions, you can still unit test that part thoroughly.

Setting up Vitest

Install the packages as dev dependencies. vite-tsconfig-paths lets your tests resolve aliases such as @/.

npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths

Create a config file at the project root and add a "test": "vitest" script to package.json.

// vitest.config.mts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  plugins: [tsconfigPaths(), react()],
  test: {
    environment: "jsdom",
  },
});

You can also start from an official example such as create-next-app --example with-vitest, which comes with this setup in place. If you prefer Jest, the next/jest helper configures SWC transforms, CSS and image imports, and environment variable loading for you.

Testing components

Render a Client Component such as the LikeButton from the previous chapter, click it like a user would, and assert on the result. React Testing Library encourages you to query by role and visible text rather than implementation details.

// app/ui/like-button.test.tsx
import { describe, expect, it } from "vitest";
import { fireEvent, render, screen } from "@testing-library/react";
import { LikeButton } from "./like-button";

describe("LikeButton", () => {
  it("increments the count on each click", () => {
    render(<LikeButton initial={3} />);
    const button = screen.getByRole("button");
    fireEvent.click(button);
    expect(button.textContent).toContain("4");
  });
});