22 — Testing and the Custom Server Escape Hatch

Testing a Next.js app looked like one question until I noticed it was really two, split by scope. The model that clicked: testing splits by scope — Vitest or Jest for unit/integration tests at the base, Playwright or Cypress for end-to-end tests at the top — and the custom server is an escape hatch for programmatic server patterns, not the default [1][2][3][4][5][6]. The framework's own server (next start) handles the vast majority of cases.

The testing landscape

Next.js supports the major testing frameworks, and the choice is by scope:

• Vitest — a fast unit test framework powered by Vite, with HMR (hot module replacement — code updates without a full reload), TypeScript, and JSX support built in [1]. Good fit for projects already on Vite-style tooling.
• Jest — a complete JavaScript testing framework with a runner, assertions, mocking, and coverage, popular for React apps [2]. The long-standing default for unit and snapshot testing.
• Playwright — automates Chromium, Firefox, and WebKit with one API, used for end-to-end testing [3].
• Cypress — supports both end-to-end and component testing, with visual debugging [4].

Unit and integration testing

Vitest and Jest cover the base of the pyramid — testing individual functions, hooks, and components in isolation [1][2]. Both have first-class Next.js setup guides. The choice between them is largely taste and ecosystem: Vitest if the project values Vite-aligned speed and DX (developer experience), Jest if it wants the mature, everything-included default.

End-to-end testing

Playwright and Cypress drive a real browser against the running app [3][4]. They test the full stack — routing, data fetching, rendering, interaction — as a user experiences it. Playwright's strength is cross-browser coverage with one API; Cypress's is the visual debug loop and component testing support.

The discipline with E2E: keep the suite small. E2E tests are slow and flaky-prone compared to units. Reserve them for the critical user journeys (login, checkout, the main flow), and let unit tests cover the rest.

The custom server — escape hatch, not default

Next.js includes its own server via next start [5]. If there's an existing backend, I can still use it alongside Next.js without a custom server. A custom server lets me programmatically start a server for custom patterns — and the roadmap is explicit: the majority of the time, I will not need this approach [5]. It's available when I need to eject.

The reasons to reach for a custom server are narrow: integrating Next.js into a larger existing Node server with custom routing, running server-side logic that doesn't fit the route handler model, or specific hosting constraints. The cost is real — a custom server opts out of some of Next.js's automatic optimizations and complicates deployment. The default next start supports all Next.js features and is what production deployments use.

How I use this

For testing, I split by scope: Vitest (or Jest) for units and component tests, Playwright for a small set of E2E tests covering the critical flows. I resist the urge to E2E everything — slow, flaky suites are worse than no tests. For the server, I've never needed a custom server in practice; next start covers every deployment I've done, and route handlers cover any server-side logic. The custom server stays in the toolbox as a labeled escape hatch I expect to rarely open.

References

[1] Vercel, "How to set up Vitest with Next.js," Next.js Docs, 2024. [Online]. Available: https://nextjs.org/docs/app/guides/testing/vitest

[2] Vercel, "How to set up Jest with Next.js," Next.js Docs, 2024. [Online]. Available: https://nextjs.org/docs/app/guides/testing/jest

[3] Vercel, "How to set up Playwright with Next.js," Next.js Docs, 2024. [Online]. Available: https://nextjs.org/docs/app/guides/testing/playwright

[4] Vercel, "How to set up Cypress with Next.js," Next.js Docs, 2024. [Online]. Available: https://nextjs.org/docs/app/guides/testing/cypress

[5] Vercel, "How to set up a custom server in Next.js," Next.js Docs, 2024. [Online]. Available: https://nextjs.org/docs/app/guides/custom-server

[6] Vitest, "Vitest — A blazing-fast unit-test framework powered by Vite," vitest.dev, 2024. [Online]. Available: https://vitest.dev/

[7] Playwright, "Playwright — Fast and reliable end-to-end testing," playwright.dev, 2024. [Online]. Available: https://playwright.dev/