Component Tests with Testing Library

Your unit suite covers the helpers; now a <NewsletterForm> component needs proof that a person can actually subscribe. Component tests render real React into a DOM, fire real events, and assert on what the user sees — without a browser. The setup has four pieces:

npm install -D @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom

// vitest.config.ts — for this layer only
test: { environment: 'jsdom' }

// vitest.setup.ts
import '@testing-library/jest-dom/vitest'

With globals: true, React Testing Library registers its own afterEach cleanup; without it you call cleanup() yourself, and a skipped cleanup leaves one test's DOM mounted inside the next.

Then the first rule of the library: query by what the user perceives — role, label, or visible text — never by implementation detail. A test that reaches for document.querySelector('.btn-primary') breaks the day your CSS module renames the class, and it told you nothing about whether a screen-reader user can find that button at all.

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import NewsletterForm from './newsletter-form'

it('confirms subscription after a valid email is submitted', async () => {
  const user = userEvent.setup()
  render(<NewsletterForm />)

  await user.type(screen.getByLabelText('Email address'), 'dev@example.com')
  await user.click(screen.getByRole('button', { name: 'Subscribe' }))

  expect(await screen.findByRole('status')).toHaveTextContent(/check your inbox/i)
})

The query priority Testing Library enforces, and why it maps onto resilience:

The accessible name is the matching target: getByRole('button', { name: /subscribe/i }) compares against what assistive technology announces, so renaming the button from "Subscribe" to "Join the list" updates the intent, and only a genuinely removed button fails. Headings take a level filter — getByRole('heading', { level: 1 }) asserts there is exactly one <h1>, a check your users' screen readers actually depend on.

When a query finds two matches it throws Found multiple elements with the role "button" rather than silently picking the first. That error is a feature: your markup now exposes two equally named buttons, and the fix is to narrow with { name } or give them distinct labels — not to fall back to a positional selector that reorders the moment the layout changes.

What to assert once you have the elements: what the user observes, plus the side effect you own.

it('announces the error and never submits when the email is invalid', async () => {
  const user = userEvent.setup()
  render(<NewsletterForm subscribe={subscribe} />)

  await user.type(screen.getByLabelText('Email address'), 'not-an-email')
  await user.click(screen.getByRole('button', { name: 'Subscribe' }))

  expect(await screen.findByRole('alert')).toHaveTextContent(/enter a valid email/i)
  expect(subscribe).not.toHaveBeenCalled()
})

The alert text is the user-visible contract; the uncalled handler is the behavior you own. Internal state like setErrors([...]) is not asserted at all — it is an implementation detail you should remain free to rename.

When an assertion fails, screen.debug() prints the rendered DOM tree; screen.logTestingPlaygroundURL() (from @testing-library/user-event) gives you a link where you can practice the query against the live markup. Both exist because the library wants you debugging the accessibility tree, not the JSX.

One boundary to be clear about: this works for components that can render without Next's server — client components, and server components whose imports stay free of server-only and data fetching. Async server components that stream awaited data belong to the end-to-end layer. You now have DOM rendering covered on top of the pure-logic layer from Unit Testing Utilities; the next problem is that a click is not really a click yet — fireEvent.click(el) dispatches one event, while React and the browser care about the whole sequence, which is where userEvent comes in.

A teammate's test does this and it passes:

fireEvent.click(button)
expect(onAdd).toHaveBeenCalledTimes(1)

Then the real app breaks: clicking with a trackpad does nothing, because the handler listens for pointerdown, or a <label> click never focuses its input, and the raw-dispatch test never noticed. The difference is that fireEvent.click(el) synthesizes exactly one DOM event — click — while a user generates a chain: pointerdown → mousedown → focus → mouseup → click, with browser-default behavior (focus moves, labels activate, drag starts) computed along the way.

userEvent reproduces that chain:

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import ProductSearch from './product-search'

it('filters the list as you type and submits on Enter', async () => {
  const user = userEvent.setup()
  render(<ProductSearch items={seedItems} />)

  const input = screen.getByRole('searchbox', { name: /search products/i })
  await user.type(input, 'mug{Enter}')

  expect(screen.getByRole('listitem', { name: /slate mug/i })).toBeInTheDocument()
  expect(screen.queryAllByRole('listitem')).toHaveLength(1)
})

Three details in that snippet carry the weight. userEvent.setup() runs before render so the instance is bound to the document the component mounts into. Every call returns a promise — await it, and React state updates settle without act() warnings. And {Enter} is user-event's keyboard syntax: user.keyboard('{Escape}'), {ArrowDown}, Control+a all work, which is how you test autocomplete menus and dialog dismissal.

Where fireEvent still earns a place: asserting pure rendering props with no interaction (a counter renders 0 initially), or high-volume loops where per-event overhead matters. For anything a person touches, prefer userEvent — and remember fireEvent.change(input, { target: { value } }) does work for controlled inputs, which is why the raw approach looks fine until pointer or keyboard behavior enters the picture.

Asynchronous UI needs waiting, but wait with the library's tools, never with sleeps:

// good: polls the DOM until true or the timeout expires
expect(await screen.findByText(/added to cart/i)).toBeInTheDocument()
await waitFor(() => expect(cartCount).toHaveTextContent('2'))

// bad: asserts on wall-clock time, flaky on slow CI machines
await new Promise((r) => setTimeout(r, 300))

Paste-heavy flows get their own primitive: await user.paste('pasted text') fires the paste event with a real DataTransfer, which fireEvent would make you fake by hand. Replacing existing text follows the same realistic sequence — await user.clear(input) selects and deletes before you type again, so a component that reacts to selection changes behaves the way it will for a real user.

Controlled inputs also deserve an assertion on the value the component actually stores, not just what was typed:

await user.clear(input)
await user.type(input, 'slate mug')
expect(input).toHaveValue('slate mug')

When the component debounces its work, fake timers and userEvent must cooperate. userEvent schedules its own inter-key delays through timers, so under vi.useFakeTimers() those delays never elapse unless you hand it the advancer:

vi.useFakeTimers()
const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime.bind(vi) })

await user.type(input, 'mug')
await vi.advanceTimersByTimeAsync(300)   // the debounce window

expect(fetchMock).toHaveBeenCalledWith('/api/search?q=mug')
vi.useRealTimers()

Without the advanceTimers option the type() call stalls until the suite times out — a failure that reads like a broken component but is really a clock mismatch.

This same discipline carries forward: Testing Route Handlers drops the DOM entirely and constructs a Request directly, but the underlying stance — simulate what the caller really does, assert what the caller really observes — stays identical.

A component under test imports three things jsdom knows nothing about: next/image expects an optimizer config and viewport observers, next/link needs the router context, and useRouter does not exist outside a Next request. Mocking them is normal — as long as you can say why each fake is safe.

Routing out of the component. When the test's subject is not navigation, flatten the Next wrappers:

vi.mock('next/link', () => ({
  default: ({ href, children, ...rest }: any) => (
    <a href={href} {...rest}>{children}</a>
  ),
}))

vi.mock('next/image', () => ({
  default: ({ src, alt, fill, priority, loader, ...rest }: any) => (
    // eslint-disable-next-line @next/next/no-img-element
    <img src={typeof src === 'string' ? src : src.src} alt={alt} {...rest} />
  ),
}))

next/link becomes an anchor you can assert on (getByRole('link', { name: 'Home' }) checks the text and the href), and next/image stops depending on the optimizer pipeline or an IntersectionObserver that jsdom does not implement. The component's own behavior — what it renders, what it does on click — is still fully real.

Navigation you need to observe. When the component calls the router, mock next/navigation and assert the call:

const { push } = vi.hoisted(() => ({ push: vi.fn() }))

vi.mock('next/navigation', () => ({
  useRouter: () => ({ push, back: vi.fn(), prefetch: vi.fn() }),
  usePathname: () => '/checkout',
  useSearchParams: () => new URLSearchParams('step=2'),
}))

it('sends the user to the receipt page after payment succeeds', async () => {
  const user = userEvent.setup()
  render(<CheckoutButton pay={paySucceeds} />)
  await user.click(screen.getByRole('button', { name: /pay now/i }))
  expect(push).toHaveBeenCalledWith('/receipt')
})

The vi.hoisted line is not decoration: vi.mock factories are hoisted above your imports, so a bare top-level const push = vi.fn() would still be uninitialized when the factory runs and throw Cannot access 'push' before initialization — the same trap covered in Unit Testing Utilities.

Network. For a client component that fetches, stub the global and drive both states:

const fetchMock = vi.fn()
vi.stubGlobal('fetch', fetchMock)

it('shows the loaded rows', async () => {
  fetchMock.mockResolvedValue(Response.json({ rows: [{ id: 1 }] }))
  render(<OrdersTable />)
  expect(await screen.findByRole('row', { name: /order 1/i })).toBeInTheDocument()
})

it('shows a skeleton while the request is in flight', () => {
  fetchMock.mockReturnValue(new Promise(() => {}))  // never resolves
  render(<OrdersTable />)
  expect(screen.getByRole('status', { name: /loading/i })).toBeInTheDocument()
})

The never-resolving promise is deliberate: it pins the pending branch, which the happy path alone never exercises.

Choosing between the two network doubles is a scope question. vi.stubGlobal('fetch', ...) wins when one or two calls decide the assertion and you want to inspect the exact URL and headers. MSW's setupServer earns its setup when the component fans out to several endpoints or you want real Request/Response parsing — it intercepts at the network layer, so code you did not explicitly stub still sees plausible responses. And if the mock takes longer to write than the component does, you have picked the wrong layer: push the interaction down into a route-handler test where the fetch belongs to someone else.

What remains for the layer above: server components that stream data cannot execute in jsdom at all. Extract their pure logic and unit-test it, then let Testing Route Handlers — and eventually Playwright — prove the server-rendered output end to end.