Testing

app/
  [locale]/store/[slug]/page.tsx     (1)
  api/books/[id]/rating/route.ts     (2)
components/
  book-card.tsx                      (3)
  counter.tsx
  search-box.tsx
lib/
  format.ts
  ratings.ts
__tests__/
  vitest/                            (4)
  jest/                              (5)
e2e/
  bookshelf.spec.ts                  (6)
  instant.spec.ts
  fake-ratings.mjs
cypress/
  e2e/app.cy.ts                      (7)
  component/book-card.cy.tsx
  support/component.ts
  tsconfig.json
vitest.config.mts
vitest.setup.ts
jest.config.ts
jest.setup.ts
playwright.config.ts
cypress.config.ts

// lib/format.ts
export function formatPrice(cents: number, locale = "en-US", currency = "EUR"): string {
  if (!Number.isInteger(cents) || cents < 0) throw new RangeError("cents must be a non-negative integer");
  return new Intl.NumberFormat(locale, { style: "currency", currency }).format(cents / 100);
}

// components/book-card.tsx -- no hooks, no async: usable as a Server Component and inside a Client tree
import Link from "next/link";
import { formatPrice } from "@/lib/format";

export type BookCardProps = { id: string; title: string; author: string; priceCents: number };

export function BookCard({ id, title, author, priceCents }: BookCardProps) {
  return (
    <article>
      <h2>
        <Link href={`/en/books/${id}`}>{title}</Link>
      </h2>
      <p>{author}</p>
      <p>{formatPrice(priceCents)}</p>
    </article>
  );
}

npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom \
  @testing-library/user-event @testing-library/jest-dom

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

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

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

// "server-only" throws when imported outside a React Server environment; neutralise it in unit tests.
vi.mock("server-only", () => ({}));

afterEach(() => cleanup());

{
  "scripts": {
    "test": "vitest run",
    "test:jest": "jest",
    "test:e2e": "playwright test"
  }
}

import { describe, expect, test } from "vitest";
import { formatPrice } from "@/lib/format";

describe("formatPrice", () => {
  test("formats cents as a currency string", () => {
    expect(formatPrice(999)).toBe("€9.99");
    expect(formatPrice(799, "es-ES")).toContain("7,99");
  });

  test("rejects negative or fractional cents", () => {
    expect(() => formatPrice(-1)).toThrow(RangeError);
    expect(() => formatPrice(1.5)).toThrow(RangeError);
  });
});

// components/counter.tsx
"use client";

import { useState } from "react";

export function Counter({ label = "Copies" }: { label?: string }) {
  const [count, setCount] = useState(1);
  return (
    <div>
      <span>
        {label}: {count}
      </span>
      <button onClick={() => setCount((c) => c + 1)}>Add copy</button>
    </div>
  );
}

// __tests__/vitest/components.test.tsx
import { expect, test } from "vitest";
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { BookCard } from "@/components/book-card";
import { Counter } from "@/components/counter";

test("BookCard renders title, author, price and a link", () => {
  render(<BookCard id="1" title="Dune" author="Frank Herbert" priceCents={999} />);
  expect(screen.getByRole("heading", { level: 2, name: "Dune" })).toBeInTheDocument();
  expect(screen.getByRole("link", { name: "Dune" })).toHaveAttribute("href", "/en/books/1");
  expect(screen.getByText("€9.99")).toBeInTheDocument();
});

test("Counter increments on click", async () => {
  const user = userEvent.setup();
  render(<Counter />);
  expect(screen.getByText("Copies: 1")).toBeInTheDocument();
  await user.click(screen.getByRole("button", { name: "Add copy" }));
  expect(screen.getByText("Copies: 2")).toBeInTheDocument();
});

$ npm test

 RUN  v5.0.3 /path/to/bookshelf

 Test Files  11 passed (11)
      Tests  23 passed (23)
   Duration  1.09s

npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom \
  @testing-library/jest-dom @testing-library/user-event ts-node @types/jest

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

const createJestConfig = nextJest({
  // Path to the Next.js app: loads next.config.ts and .env files into the test environment
  dir: "./",
});

const config: Config = {
  coverageProvider: "v8",
  testEnvironment: "jsdom",
  testMatch: ["<rootDir>/__tests__/jest/**/*.test.{ts,tsx}"],
  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],
};

// ESM-only packages (msw 3 and its dependencies) must be transformed by the Next.js compiler too.
// next/jest returns an async config function, so wrap it and adjust transformIgnorePatterns.
const esmOnly = ["msw", "@msw", "@mswjs", "rettime", "cookie", "until-async", "headers-polyfill", "@open-draft"];

export default async function jestConfig() {
  const resolved = await createJestConfig(config)();
  return {
    ...resolved,
    transformIgnorePatterns: [
      `/node_modules/(?!(${esmOnly.join("|")})/)`,
      "^.+\\.module\\.(css|sass|scss)$",
    ],
  };
}

import "@testing-library/jest-dom";

// "server-only" throws outside a React Server environment.
jest.mock("server-only", () => ({}));

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { BookCard } from "@/components/book-card";
import { Counter } from "@/components/counter";

describe("BookCard", () => {
  it("renders a heading, a link and the formatted price", () => {
    render(<BookCard id="2" title="Neuromancer" author="William Gibson" priceCents={899} />);
    expect(screen.getByRole("heading", { level: 2, name: "Neuromancer" })).toBeInTheDocument();
    expect(screen.getByRole("link", { name: "Neuromancer" })).toHaveAttribute("href", "/en/books/2");
    expect(screen.getByText("€8.99")).toBeInTheDocument();
  });

  it("matches its snapshot", () => {
    const { container } = render(<BookCard id="3" title="Solaris" author="Stanislaw Lem" priceCents={799} />);
    expect(container).toMatchSnapshot();
  });
});

describe("Counter", () => {
  it("increments", async () => {
    const user = userEvent.setup();
    render(<Counter />);
    await user.click(screen.getByRole("button", { name: "Add copy" }));
    expect(screen.getByText("Copies: 2")).toBeInTheDocument();
  });
});

exports[`BookCard matches its snapshot 1`] = `
<div>
  <article>
    <h2>
      <a
        href="/en/books/3"
      >
        Solaris
      </a>
    </h2>
    <p>
      Stanislaw Lem
    </p>
    <p>
      €7.99
    </p>
  </article>
</div>
`;

$ npm run test:jest

Test Suites: 4 passed, 4 total
Tests:       6 passed, 6 total
Snapshots:   1 passed, 1 total

// components/search-box.tsx
"use client";

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

export function SearchBox() {
  const router = useRouter();
  const params = useSearchParams();
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        const q = new FormData(e.currentTarget).get("q");
        router.push(`/en?q=${encodeURIComponent(String(q))}`);
      }}
    >
      <input name="q" aria-label="Search" defaultValue={params?.get("q") ?? ""} />
      <button>Go</button>
    </form>
  );
}

// __tests__/vitest/search-box.test.tsx
import { expect, test, vi } from "vitest";
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { SearchBox } from "@/components/search-box";

const push = vi.fn();
vi.mock("next/navigation", () => ({
  useRouter: () => ({ push }),
  useSearchParams: () => new URLSearchParams("q=dune"),
}));

test("SearchBox pushes the encoded query to the router", async () => {
  const user = userEvent.setup();
  render(<SearchBox />);
  const input = screen.getByRole("textbox", { name: "Search" });
  expect(input).toHaveValue("dune");
  await user.clear(input);
  await user.type(input, "war & peace");
  await user.click(screen.getByRole("button", { name: "Go" }));
  expect(push).toHaveBeenCalledWith("/en?q=war%20%26%20peace");
});

import { beforeEach, describe, expect, test, vi } from "vitest";

const auth = vi.fn();
vi.mock("@/auth", () => ({ auth: () => auth() }));
vi.mock("next/cache", () => ({ revalidatePath: vi.fn() }));

import { revalidatePath } from "next/cache";
import { submitReview } from "@/app/[locale]/actions";
import { listReviews } from "@/lib/books";

function form(fields: Record<string, string>) {
  const fd = new FormData();
  for (const [k, v] of Object.entries(fields)) fd.set(k, v);
  return fd;
}

describe("submitReview", () => {
  beforeEach(() => vi.clearAllMocks());

  test("rejects anonymous callers", async () => {
    auth.mockResolvedValue(null);
    const res = await submitReview({ ok: false }, form({ bookId: "1", rating: "5", text: "Great" }));
    expect(res).toEqual({ ok: false, error: "Sign in required" });
    expect(revalidatePath).not.toHaveBeenCalled();
  });

  test("validates input on the server", async () => {
    auth.mockResolvedValue({ user: { name: "Test User" } });
    const res = await submitReview({ ok: false }, form({ bookId: "1", rating: "9", text: "Too high" }));
    expect(res).toEqual({ ok: false, error: "Invalid input" });
  });

  test("stores the review and revalidates the page", async () => {
    auth.mockResolvedValue({ user: { name: "Test User" } });
    const res = await submitReview({ ok: false }, form({ bookId: "2", rating: "4", text: "Cyberpunk classic" }));
    expect(res).toEqual({ ok: true });
    expect(revalidatePath).toHaveBeenCalledWith("/[locale]/books/[id]", "page");
    expect((await listReviews("2")).map((r) => r.text)).toEqual(["Cyberpunk classic"]);
  });
});

import { expect, test } from "vitest";
import { GET } from "@/app/api/books/route";

test("GET /api/books filters by the q search parameter", async () => {
  const res = await GET(new Request("http://localhost/api/books?q=dune"));
  expect(res.status).toBe(200);
  expect(res.headers.get("content-type")).toContain("application/json");
  const body = (await res.json()) as { id: string; title: string }[];
  expect(body.map((b) => b.title)).toEqual(["Dune"]);
});

/**
 * @jest-environment node
 */
import { GET } from "@/app/api/books/route";

describe("GET /api/books", () => {
  it("returns JSON filtered by q", async () => {
    const res = await GET(new Request("http://localhost/api/books?q=gibson"));
    expect(res.status).toBe(200);
    expect(await res.json()).toEqual([
      { id: "2", title: "Neuromancer", author: "William Gibson", priceCents: 899 },
    ]);
  });
});

import { getRating } from "@/lib/ratings";

export async function GET(_request: Request, ctx: RouteContext<"/api/books/[id]/rating">) {
  const { id } = await ctx.params;
  try {
    const rating = await getRating(id);
    if (!rating) return Response.json({ error: "No rating" }, { status: 404 });
    return Response.json(rating);
  } catch {
    return Response.json({ error: "Ratings service unavailable" }, { status: 502 });
  }
}

import { expect, test } from "vitest";
import { NextRequest } from "next/server";
import * as testing from "next/experimental/testing/server";
import { config, proxy } from "@/proxy";

test("the matcher skips API routes and files", () => {
  const match = (url: string) => testing.unstable_doesMiddlewareMatch({ config, url });
  expect(match("/books")).toBe(true);
  expect(match("/api/books")).toBe(false);
  expect(match("/favicon.ico")).toBe(false);
});

test("proxy redirects to the preferred locale", async () => {
  const req = new NextRequest("http://localhost:3000/books", { headers: { "accept-language": "es-ES,es;q=0.9" } });
  const res = proxy(req);
  expect(testing.getRedirectUrl(res)).toBe("http://localhost:3000/es/books");
});

test("proxy lets localized paths through", () => {
  const res = proxy(new NextRequest("http://localhost:3000/en/books"));
  expect(res.headers.get("x-middleware-next")).toBe("1");
});

export type Rating = { bookId: string; average: number; count: number };

// Calls a third-party service; the base URL comes from configuration, not from user input.
const BASE_URL = process.env.RATINGS_API_URL ?? "https://ratings.example.test";

export async function getRating(bookId: string): Promise<Rating | null> {
  const res = await fetch(`${BASE_URL}/api/ratings/${encodeURIComponent(bookId)}`);
  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`ratings service failed: ${res.status}`);
  return (await res.json()) as Rating;
}

import { afterAll, afterEach, beforeAll, expect, test } from "vitest";
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { getRating } from "@/lib/ratings";

const server = setupServer(
  http.get("https://ratings.example.test/api/ratings/:id", ({ params }) =>
    params.id === "1"
      ? HttpResponse.json({ bookId: "1", average: 4.5, count: 12 })
      : new HttpResponse(null, { status: 404 }),
  ),
);

beforeAll(() => server.listen({ onUnhandledFrame: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test("returns the rating from the third-party service", async () => {
  expect(await getRating("1")).toEqual({ bookId: "1", average: 4.5, count: 12 });
});

test("returns null on 404", async () => {
  expect(await getRating("99")).toBeNull();
});

test("throws on a server error (per-test override)", async () => {
  server.use(http.get("https://ratings.example.test/api/ratings/:id", () => new HttpResponse(null, { status: 500 })));
  await expect(getRating("1")).rejects.toThrow("ratings service failed: 500");
});

test("a request without a handler fails the test instead of reaching the network", async () => {
  await expect(fetch("https://unmocked.example.test/ping")).rejects.toThrow();
});

import { afterAll, afterEach, beforeAll, expect, test } from "vitest";
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { GET } from "@/app/api/books/[id]/rating/route";

const server = setupServer();
beforeAll(() => server.listen({ onUnhandledFrame: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

// In a dynamic Route Handler the second argument carries the params as a Promise.
const ctx = (id: string) => ({ params: Promise.resolve({ id }) }) as RouteContext<"/api/books/[id]/rating">;

test("proxies the rating of the third-party service", async () => {
  server.use(
    http.get("https://ratings.example.test/api/ratings/:id", () =>
      HttpResponse.json({ bookId: "1", average: 4.5, count: 12 }),
    ),
  );
  const res = await GET(new Request("http://localhost/api/books/1/rating"), ctx("1"));
  expect(res.status).toBe(200);
  expect(await res.json()).toEqual({ bookId: "1", average: 4.5, count: 12 });
});

test("maps a failing service to 502", async () => {
  server.use(http.get("https://ratings.example.test/api/ratings/:id", () => new HttpResponse(null, { status: 500 })));
  const res = await GET(new Request("http://localhost/api/books/1/rating"), ctx("1"));
  expect(res.status).toBe(502);
});

import { expect, test } from "vitest";
import { loadEnvConfig } from "@next/env";

test("loadEnvConfig reads .env.test and ignores .env.local", () => {
  loadEnvConfig(process.cwd());
  expect(process.env.RATINGS_API_URL).toBe("https://ratings.example.test");
});

import { defineConfig, devices } from "@playwright/test";

const port = Number(process.env.PORT ?? 3000);
const fakePort = Number(process.env.FAKE_RATINGS_PORT ?? 3904);

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  reporter: "list",
  use: { baseURL: `http://localhost:${port}`, trace: "on-first-retry" },
  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
  webServer: [
    {
      // the third-party service, replaced by a fake: MSW cannot intercept calls made by the Next.js server process
      command: "node e2e/fake-ratings.mjs",
      url: `http://localhost:${fakePort}/api/ratings/1`,
    },
    {
      // test the production build, as the Next.js guide recommends
      command: `npm run build && npm run start -- --port ${port}`,
      url: `http://localhost:${port}`,
      env: { RATINGS_API_URL: `http://localhost:${fakePort}` },
      reuseExistingServer: !process.env.CI,
      timeout: 180_000,
    },
  ],
});

// A tiny stand-in for the third-party ratings service, started by Playwright next to the app.
import { createServer } from "node:http";

const port = Number(process.env.FAKE_RATINGS_PORT ?? 3904);

createServer((req, res) => {
  const match = /^\/api\/ratings\/(\w+)$/.exec(req.url ?? "");
  if (match && match[1] === "1") {
    res.setHeader("content-type", "application/json");
    res.end(JSON.stringify({ bookId: "1", average: 4.5, count: 12 }));
  } else {
    res.statusCode = 404;
    res.end();
  }
}).listen(port, () => console.log(`fake ratings service on ${port}`));

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

test("redirects to the preferred locale and shows the catalogue", async ({ browser }) => {
  const context = await browser.newContext({ locale: "es-ES", extraHTTPHeaders: { "accept-language": "es" } });
  const page = await context.newPage();
  await page.goto("/");
  await expect(page).toHaveURL(/\/es$/);
  await expect(page.getByRole("heading", { level: 1 })).toHaveText("Estantería");
  await context.close();
});

test("searches the catalogue and opens a book", async ({ page }) => {
  await page.goto("/en");
  await page.getByRole("textbox", { name: "Search" }).fill("sol");
  await page.getByRole("button", { name: "Search" }).click();
  await expect(page).toHaveURL(/q=sol/);
  await page.getByRole("link", { name: "Solaris" }).click();
  await expect(page).toHaveURL(/\/en\/books\/3$/);
  await expect(page.getByRole("heading", { name: "Solaris" })).toBeVisible();
});

test("an anonymous visitor cannot post a review (Server Action)", async ({ page }) => {
  await page.goto("/en/books/1");
  await page.getByRole("textbox").fill("Great book");
  await page.getByRole("button", { name: "Send review" }).click();
  await expect(page.getByText("Sign in required")).toBeVisible();
});

test("the Route Handler answers with JSON", async ({ request }) => {
  const res = await request.get("/api/books?q=dune");
  expect(res.ok()).toBe(true);
  expect(await res.json()).toEqual([{ id: "1", title: "Dune", author: "Frank Herbert", priceCents: 999 }]);
});

test("the rating comes from the (fake) third-party service", async ({ request }) => {
  const ok = await request.get("/api/books/1/rating");
  expect(await ok.json()).toEqual({ bookId: "1", average: 4.5, count: 12 });
  const missing = await request.get("/api/books/2/rating");
  expect(missing.status()).toBe(404);
});

$ CACHE_COMPONENTS=1 PORT=3804 npx playwright test

Running 7 tests using 5 workers
  ✓  [chrome] › e2e/bookshelf.spec.ts:29:5 › the Route Handler answers with JSON (21ms)
  ✓  [chrome] › e2e/bookshelf.spec.ts:35:5 › the rating comes from the (fake) third-party service (36ms)
  ✓  [chrome] › e2e/bookshelf.spec.ts:22:5 › an anonymous visitor cannot post a review (Server Action) (792ms)
  ✓  [chrome] › e2e/bookshelf.spec.ts:3:5 › redirects to the preferred locale and shows the catalogue (827ms)
  ✓  [chrome] › e2e/instant.spec.ts:5:7 › Product page (/en/store/[slug]) › is instant on an initial page load (916ms)
  ✓  [chrome] › e2e/bookshelf.spec.ts:12:5 › searches the catalogue and opens a book (1.2s)
  ✓  [chrome] › e2e/instant.spec.ts:20:7 › Product page (/en/store/[slug]) › is instant on a client navigation (1.3s)
  7 passed (6.2s)

import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    baseUrl: "http://localhost:3804",
    supportFile: false,
  },
  component: {
    devServer: {
      framework: "next",
      bundler: "webpack",
    },
    supportFile: "cypress/support/component.ts",
  },
});

describe("Navigation", () => {
  it("opens a book from the catalogue", () => {
    cy.visit("/en");
    cy.get('a[href="/en/books/1"]').click();
    cy.url().should("include", "/en/books/1");
    cy.contains("h1", "Dune");
  });

  it("answers the Route Handler with JSON", () => {
    cy.request("/api/books?q=gibson").its("body").should("have.length", 1);
  });
});

$ npm run build && npm run start -- --port 3804
$ npx cypress run --e2e

  Navigation
    ✓ opens a book from the catalogue (478ms)
    ✓ answers the Route Handler with JSON (13ms)

  2 passing (522ms)

// cypress/support/component.ts
import { mount } from "cypress/react";

declare global {
  // eslint-disable-next-line @typescript-eslint/no-namespace
  namespace Cypress {
    interface Chainable {
      mount: typeof mount;
    }
  }
}

Cypress.Commands.add("mount", mount);

// cypress/component/book-card.cy.tsx
import { BookCard } from "../../components/book-card";

describe("<BookCard />", () => {
  it("renders the title, author and price", () => {
    cy.mount(<BookCard id="1" title="Dune" author="Frank Herbert" priceCents={999} />);
    cy.get("h2").contains("Dune");
    cy.contains("€9.99");
    cy.get('a[href="/en/books/1"]').should("be.visible");
  });
});

{
  "compilerOptions": {
    "target": "es2017",
    "lib": ["es2017", "dom"],
    "jsx": "react-jsx",
    "moduleResolution": "bundler",
    "module": "esnext",
    "types": ["cypress", "node"],
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true,
    "paths": { "@/*": ["../*"] },
    "noEmit": true
  },
  "include": ["**/*.ts", "**/*.tsx", "../cypress.config.ts"]
}

{
  "exclude": ["node_modules", "cypress", "cypress.config.ts"]
}

// pages/legacy.tsx
import type { GetServerSideProps } from "next";

type Props = { greeting: string };

export const getServerSideProps: GetServerSideProps<Props> = async ({ query }) => ({
  props: { greeting: `Hello ${String(query.name ?? "reader")}` },
});

export default function Legacy({ greeting }: Props) {
  return <h1>{greeting}</h1>;
}

// pages/api/ping.ts
import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== "GET") {
    res.setHeader("Allow", "GET");
    return res.status(405).json({ error: "Method Not Allowed" });
  }
  return res.status(200).json({ pong: String(req.query.name ?? "world") });
}

// __tests__/vitest/pages-router.test.tsx
import { expect, test, vi } from "vitest";
import { render, screen } from "@testing-library/react";
import type { GetServerSidePropsContext, NextApiRequest, NextApiResponse } from "next";
import Legacy, { getServerSideProps } from "@/pages/legacy";
import handler from "@/pages/api/ping";

test("getServerSideProps is a plain async function", async () => {
  const result = await getServerSideProps({ query: { name: "Ada" } } as unknown as GetServerSidePropsContext);
  expect(result).toEqual({ props: { greeting: "Hello Ada" } });
  render(<Legacy greeting="Hello Ada" />);
  expect(screen.getByRole("heading", { name: "Hello Ada" })).toBeInTheDocument();
});

test("a Pages Router API route takes req and res objects", () => {
  const res = { status: vi.fn().mockReturnThis(), json: vi.fn(), setHeader: vi.fn() };
  handler({ method: "GET", query: { name: "Ada" } } as unknown as NextApiRequest, res as unknown as NextApiResponse);
  expect(res.status).toHaveBeenCalledWith(200);
  expect(res.json).toHaveBeenCalledWith({ pong: "Ada" });

  handler({ method: "POST", query: {} } as unknown as NextApiRequest, res as unknown as NextApiResponse);
  expect(res.setHeader).toHaveBeenCalledWith("Allow", "GET");
  expect(res.status).toHaveBeenLastCalledWith(405);
});