Testing Tools: Jest, Vitest, Testing Library, Playwright

At 4+ years you are not asked "what is a unit test?" You are asked why a test is flaky, why vi.mock fails with "before initialization", how you test an async Server Component, and what you do about the test database. This lesson covers the tools and the traps that come with them.

Strategy is not repeated here. What to test and at which level is in Frontend Testing Strategy. Backend API tests, contract tests and what to mock on the server are in Testing an API. This lesson is the tool layer under both.

Versions used and run in October 2026: Vitest 5.0, Jest 30.5, Testing Library React 16, user-event 14, MSW 3.0, Playwright 1.64, Prisma 7.10 (with SQLite), Next.js 16.3. Every code sample below was run.

Words used in this lesson

• A test runner is a program that finds your test files, runs them and prints which passed. Vitest and Jest are test runners.
• A test double is a fake thing you use in a test instead of the real thing. It is like a crash-test dummy in a car test.
• A stub is a double that returns a fixed answer. A spy is a wrapper that records how a real function was called, and still runs it. A mock is a double that records calls so you can check them. A fake is a small, working copy of the real thing (an in-memory database).
• Fake timers are a replacement for setTimeout, setInterval and Date where you move the clock by hand.
• MSW (Mock Service Worker) is a library that catches network requests in tests and answers them with responses you wrote.
• jsdom is a library that gives Node.js a fake browser page (document, window) so components can render without a real browser.
• Hoisting means a tool moves a line of code to the top of the file before it runs.
• A flaky test is a test that sometimes passes and sometimes fails with the same code.
• A snapshot test saves the output of something and fails when the output changes later.
• Code coverage is a number that says how many lines or branches of your code ran during the tests.

Jest vs Vitest

Difference in one line: Jest brings its own pipeline and you bend it to your code; Vitest reuses the pipeline your app already has. The API is about 90% the same, so moving between them is mostly a rename.

Choose Vitest for new Vite or Next.js projects with TypeScript. Keep Jest for a large working suite or React Native. The Next.js docs support both, and they say the same thing about both: neither can render an async Server Component, so use end-to-end tests for those.

Test doubles: stub, spy, mock, fake

import { test, expect, vi } from 'vitest'import { welcome, type Mailer } from '../src/mail'test('mock: record calls and check them', async () => {  const send = vi.fn().mockResolvedValue(undefined)  await welcome({ email: 'a@x.com', name: 'Ann' }, { send })  expect(send).toHaveBeenCalledExactlyOnceWith('a@x.com', 'Hi Ann')})test('fake: a small working copy', async () => {  const outbox: string[] = []  const fake: Mailer = { send: async (to, body) => { outbox.push(`${to}:${body}`) } }  await welcome({ email: 'a@x.com', name: 'Ann' }, fake)  expect(outbox).toEqual(['a@x.com:Hi Ann'])})test('spy: wrap a real method, keep its behaviour', () => {  const obj = { double: (n: number) => n * 2 }  const spy = vi.spyOn(obj, 'double')  expect(obj.double(4)).toBe(8)  expect(spy).toHaveBeenCalledWith(4)})

Passing a double in as an argument (as above) is the easy case. It works because welcome takes mailer as a parameter. Code that takes its dependencies as arguments needs far less mocking.

Mocking a module

import { vi } from 'vitest'import { label } from '../src/report'      // report.ts imports { now } from './clock'const { fakeNow } = vi.hoisted(() => ({ fakeNow: vi.fn(() => 7) }))vi.mock('../src/clock', () => ({ now: fakeNow }))

vi.mock (and jest.mock) is hoisted: it is moved above your imports so the fake is in place before report.ts loads. The price is that the factory runs before your other top-level lines. If the factory uses a normal const from your file, you get Cannot access 'fakeNow' before initialization. I ran it. vi.hoisted is the fix: it runs a small function at the very top and gives you its result. In Jest the same fix is a variable whose name starts with mock.

A second trap: vi.spyOn(clock, 'now').mockReturnValue(1) changes what other files see. A function inside clock.ts that calls now() directly still got the real time in my run, because it never goes through the export.

Mock the edges of your system (network, clock, randomness, next/headers). Do not mock your own modules to make a test easy; that is what Frontend Testing Strategy warns about.

Fake timers

test('debounce runs once after the quiet time', () => {  vi.useFakeTimers()  const fn = vi.fn()  const d = debounce(fn, 300)  d('a'); d('b'); d('c')  vi.advanceTimersByTime(299)  expect(fn).not.toHaveBeenCalled()  vi.advanceTimersByTime(1)  expect(fn).toHaveBeenCalledExactlyOnceWith('c')  vi.useRealTimers()})

• Fake timers also fake Date. Use vi.setSystemTime(new Date('2026-01-01')) to test "is the coupon expired?" without waiting. (In Jest: jest.setSystemTime.)
• If a timer callback uses promises, use the async version: await vi.advanceTimersByTimeAsync(1000). The sync version does not let promise callbacks run in between.
• Always go back to real timers in afterEach, or the next test inherits the fake clock.

MSW: mock the network, not fetch

// test/server.tsimport { setupServer } from 'msw/node'import { http, HttpResponse } from 'msw'export const server = setupServer(  http.get('/api/users', () => HttpResponse.json([{ id: 1, name: 'Ann' }])),)// test/msw-setup.ts  (listed in vitest `setupFiles`)beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))afterEach(() => server.resetHandlers())afterAll(() => server.close())

test('shows an error when the API fails', async () => {  server.use(http.get('/api/users', () => new HttpResponse(null, { status: 500 })))  render(<Users />)  expect(await screen.findByRole('alert')).toHaveTextContent('HTTP 500')})

Why this beats vi.mock('fetch'): your real fetch call, your data library, retries and error code all run. Only the server is fake. A mock of fetch hides bugs in how you build the URL and read the response.

• onUnhandledRequest: 'error' makes a request with no handler fail the test. Without it, MSW lets the request go to the real network. I ran it and saw [MSW] Error: intercepted a request without a matching request handler.
• server.use(...) adds a handler for one test. resetHandlers() in afterEach removes it, so tests do not leak into each other.
• Gotcha: Node's fetch cannot resolve a relative URL like /api/users in jsdom. I had to give fetch a base address. In your app, use an absolute URL from an environment variable.
• MSW 3 is new (released late September 2026). The http, HttpResponse and setupServer code above ran on 3.0.2. Check the changelog before you upgrade a large suite.

The backend side of this (a fake server for third-party APIs) is in Testing an API.

React Testing Library: queries and user-event

React Testing Library (RTL) is a library that renders a React component and lets you find and use elements the way a user does. user-event is a companion library that simulates real user actions (type, click, tab) with all the events a browser would send.

Which query? There are three families, and the name tells you what happens when nothing is found:

Add All (getAllBy…) when many matches are fine.

Order of preference: getByRole (with name), then getByLabelText, then getByText, and getByTestId last. Roles match what a screen reader sees, so a good role query also proves your page is accessible.

test('user-event: click and see the result', async () => {  const user = userEvent.setup()  const onSave = vi.fn()  render(<Counter onSave={onSave} />)  const save = screen.getByRole('button', { name: 'Save' })  expect(save).toBeDisabled()  await user.click(screen.getByRole('button', { name: 'Add one' }))  expect(screen.getByText('Count: 1')).toBeInTheDocument()  await user.click(save)  expect(onSave).toHaveBeenCalledWith(1)})

Difference in one line: fireEvent sends one raw event; userEvent plays the whole story of a click (hover, mouse down, focus, mouse up, click) or of typing (key down, input, key up). userEvent finds bugs that fireEvent hides, such as a disabled button that still got a click. Always call userEvent.setup() first and await every action.

Hooks and async UI

• A custom hook is a function that uses React hooks. You cannot call it outside a component, so use renderHook, which runs it inside a tiny test component. Wrap changes in act(() => ...).

const { result } = renderHook(() => useToggle())act(() => result.current.toggle())expect(result.current.on).toBe(true)

• act tells React "finish all updates from this change before I look". RTL and user-event already wrap their actions in it. A warning "not wrapped in act(...)" usually means an update happened after your test ended its check. The fix is to wait for the end state (await screen.findBy…), not to sprinkle act.
• Prefer findBy… over waitFor(() => expect(...)). If you use waitFor, put one assertion inside it and no side effects such as clicks.

Testing Next.js: Server Components and route handlers

Rule from the Next.js docs: async Server Components are not supported by Jest or Vitest renderers, so use E2E tests for them. Two honest options exist.

Option 1: a unit-style trick. An async component is only an async function. Call it, await the result, and render the JSX it returns:

test('async Server Component: await the function, then render the result', async () => {  const ui = await OrderPage({ params: Promise.resolve({ id: '7' }) })  render(ui)  expect(screen.getByRole('heading')).toHaveTextContent('Order 7: book')})

This worked in my run, including params as a Promise (Next.js 16 passes params as a Promise). Rendering it directly with render(<OrderPage … />) failed: React logged "is an async Client Component. Only Server Components can be async" and the page stayed empty.

The limit is real. This tests your branches and markup, not caching, streaming, Suspense or layouts. Anything from next/headers must be mocked: vi.mock('next/headers', () => ({ cookies: async () => ({ get: … }) })) worked for me.

Option 2: Playwright against next build and next start. This is the real thing. The Next.js docs recommend testing production code. Use it for pages that depend on caching or streaming.

Route handlers are the easy case. A handler is a function that takes a Request and returns a Response. Call it with a real NextRequest in the Node environment:

const res = await GET(new NextRequest('http://localhost/api/orders?id=7'))expect(res.status).toBe(200)expect(await res.json()).toEqual({ id: 7, item: 'book', total: 12 })

I ran the 200, 400 (bad id) and 404 (missing order) cases this way. No server is started. For middleware-level behaviour (redirects, auth cookies) use Playwright. See Next.js, Lesson 5 for the rendering model behind this.

Playwright

Playwright is a tool that drives a real browser from code. A locator is an object that describes how to find an element; it looks again each time you use it. Auto-waiting means Playwright waits before each action until the element is visible, stable, enabled and able to receive the click.

test('add a todo (auto-wait: no sleeps)', async ({ page }) => {  await page.goto('/')  await page.getByLabel('New todo').fill('buy milk')  await page.getByRole('button', { name: 'Add' }).click()  await expect(page.getByRole('status')).toHaveText('Saved')      // retries until true  await expect(page.getByRole('listitem')).toHaveText(['buy milk'])})

• Locators: prefer getByRole, getByLabel, getByText, then getByTestId. Avoid CSS paths like div > div:nth-child(3).
• Strict mode: if a locator matches more than one element, an action fails. I ran it: strict mode violation: getByRole('listitem') resolved to 2 elements. That is a feature. Narrow the locator instead of adding .first().
• Web-first assertions (await expect(locator).toHaveText(...)) retry for 5 seconds by default. The whole test has 30 seconds by default (both can be changed). Actions have no timeout of their own, so they live inside the test timeout.
• Fixtures: a fixture is setup that a test asks for by name and Playwright builds fresh for each test, then cleans up. Use test.extend to make your own (logged-in page, seeded data).

const test = base.extend<{ app: Page }>({  app: async ({ page }, use) => { await page.goto('/'); await use(page) },})

• Network inside the browser: page.route('**/api/todos', r => r.fulfill({ json: … })) fakes one call. I used it to test the UI against a made-up response. Inside a Playwright test, route is the simple built-in way.
• Config: webServer starts your app and waits for it. Use retries in CI only, set trace: 'on-first-retry', and use fullyParallel: true once tests are independent.

Flaky tests and the trace viewer

The classic cause of flakiness is reading state once instead of waiting for it:

const text = await page.getByRole('status').textContent()   // reads once, no retryexpect(text).toBe('Saved')                                  // got "Saving..."

My slow demo server took 400 ms, so this failed every time. On a fast machine it would pass sometimes. That is how a flaky test is born. The fix is one line: await expect(page.getByRole('status')).toHaveText('Saved').

Trace viewer: a trace is a recording of the whole test: each step, a DOM snapshot before and after, the network calls, the console and the source line. With trace: 'on-first-retry' and retries: 1, the first retry saved trace.zip. Open it with npx playwright show-trace trace.zip and you see the page as it was when the step failed. Retries hide flakiness, so track tests that needed a retry ("flaky" in the report) and fix them; do not just raise the retry count.

Test databases with Prisma

Backend rules (real database, isolation, speed) are in Testing an API. Here are the Prisma-specific choices. I ran all three with Prisma 7.10 and SQLite.

// global setup: build ONE template database from the schema, onceconst sql = execSync('npx prisma migrate diff --from-empty --to-schema prisma/schema.prisma --script').toString()new Database('.testdb/template.db').exec(sql.slice(sql.indexOf('-- CreateTable')))// per test file: its own copy, keyed by the worker numberexport function workerDb() {  const file = `.testdb/worker-${process.env.VITEST_POOL_ID ?? '0'}.db`  copyFileSync('.testdb/template.db', file)  return makeClient('file:./' + file)}// rollback strategyclass Rollback extends Error {}await db.$transaction(async (tx) => { await run(tx); throw new Rollback() }).catch(e => { if (!(e instanceof Rollback)) throw e })

What passed: a duplicate email failed with Prisma error code P2002; deleting a user cascaded to its orders; the rollback test left zero rows. These are the checks a mock could never give you.

• Use the same database engine as production. SQLite is fine for a demo, but it differs from PostgreSQL in types, JSON, case-sensitivity and locking. If production is Postgres, test on Postgres (a container, or one local server with one schema per worker).
• Build the template from your real migrations (prisma migrate deploy in CI). I generated SQL from the schema with migrate diff and did not run migrate deploy itself.
• Never point tests at a shared or production DATABASE_URL. Read the URL from a test-only variable and refuse to start if it does not contain "test".

Coverage and snapshots: two common myths

Coverage measures what ran, not what was checked. I wrote this test:

test('runs the code, checks nothing', () => {  price(3, true)  price(3, false)})

The Vitest report (v8 provider) showed 100% branch coverage for price.ts, and the only uncovered line was another function I never called. The test can never fail. Coverage is useful in one direction: a low or red number shows code that no test touched. A high number proves nothing. Chasing 100% leads to tests that call code and assert nothing. Better: look at the uncovered lines in a pull request, and use mutation testing (a tool such as Stryker changes your code on purpose and checks that a test fails) on the important modules.

Snapshots. toMatchInlineSnapshot() writes the expected value into the test file. toMatchSnapshot() writes it to a .snap file. My snapshot of a tiny counter's DOM was 18 lines for a component with two buttons. Nobody reads that diff. Rules: small values only, prefer inline, review every change, and never run -u (update all) to make red go green. Details and the visual-test option are in Frontend Testing Strategy.

Interview questions

Key takeaways

• Vitest and Jest are about 90% the same API. Vitest reuses your Vite pipeline; neither renders async Server Components.
• vi.mock is hoisted: use vi.hoisted for shared variables. A spy does not change calls inside the same file.
• Fake timers fake Date too. With Testing Library under Vitest, use shouldAdvanceTime: true.
• MSW fakes the server, with onUnhandledRequest: 'error' and resetHandlers after each test.
• getBy throws, queryBy returns null, findBy waits. Use getByRole first and userEvent with await.
• Call an async Server Component as a function, then render the result; use Playwright for the real behaviour. Call route handlers directly with NextRequest.
• In Playwright, never read once: use retrying expect. Strict locators, fixtures and trace: 'on-first-retry' find flakiness.
• Test the database with the real engine and real migrations; isolate by cleaning, rolling back, or one database per worker.
• Coverage shows untested code, not tested behaviour. Keep snapshots small.

What's next

Lesson 22: OAuth 2.0 and OpenID Connect. How users sign in to a Next.js app, and how to protect every route and Server Action on the server.