Testing Route Handlers

An App Router route handler is not a framework abstraction you need a server to reach. It is a plain function that takes a Web Request and returns a Response:

// app/api/orders/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> },
) {
  const { id } = await params
  const order = await findOrder(id)
  if (!order) return Response.json({ error: 'not_found' }, { status: 404 })
  return Response.json(order)
}

Because the signature uses web standards, a test can import the export and call it directly — no next start, no port, no HTTP client:

import { describe, it, expect } from 'vitest'
import { GET, PATCH } from '@/app/api/orders/[id]/route'

it('returns the order as JSON', async () => {
  const res = await GET(new Request('http://localhost/api/orders/42'), {
    params: Promise.resolve({ id: '42' }),
  })

  expect(res.status).toBe(200)
  expect(res.headers.get('content-type')).toContain('application/json')
  await expect(res.json()).resolves.toMatchObject({ id: '42' })
})

it('returns 404 for an unknown order', async () => {
  const res = await GET(new Request('http://localhost/api/orders/404'), {
    params: Promise.resolve({ id: '404' }),
  })
  expect(res.status).toBe(404)
})

The params argument is where most first attempts fail. Since Next 15, segment data arrives as a Promise, so the test passes Promise.resolve({ id: '42' }); destructure only inside the handler. Passing the raw object makes await params yield an object shape your handler never sees in production, and the test passes for the wrong reasons.

Constructing the request exercises every branch the same way the wire would:

const post = new Request('http://localhost/api/orders', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ sku: 'SLATE-1', qty: 2 }),
})

const bad = new Request('http://localhost/api/orders', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: '{ not json',
})

await request.json() inside your handler parses that body exactly as it would in production — a malformed-body test costs nothing. Query strings work too: new URL(request.url).searchParams.get('cursor'), which is how you cover pagination without a URL builder.

Also worth pinning: how the handler exits. Response.json() and NextResponse.json() are interchangeable in tests — both give you a plain Response with the same assertion surface. redirect('/login') behaves differently: it works by throwing, so the thrown error carries a digest like NEXT_REDIRECT;replace;/login;307; and a direct test asserts it as a rejection:

it('sends anonymous visitors to login', async () => {
  await expect(GET(new Request('http://localhost/api/orders')))
    .rejects.toMatchObject({ digest: expect.stringContaining('NEXT_REDIRECT') })
})

Wrap the call in expect(...).rejects rather than letting the throw surface as an unhandled test failure — the error is the contract here, and next-test-api-route-handler resolves it into a real 307 when you need the status instead of the digest.

What you are not covering yet matters more than what you are. A bare new Request has no cookies(), no headers() from next/headers, no request.nextUrl, and no access to revalidatePath — those are injected by Next's request pipeline, and a handler that reads them will throw outside it. The rule of thumb:

That boundary is the whole design of this layer: start with the direct call because it is fast and hermetic, and reach for the pipeline wrapper only when the handler genuinely depends on Next's runtime — which the next chapter sets up alongside the network mocks. Contrast this with Component Tests with Testing Library: there the DOM was the subject; here there is no DOM at all, and the contract is status code plus body.

Your handler probably does not only read its own arguments — it calls a payment API, a database client, or an internal service. In a test those calls are liabilities: they make CI depend on someone else's uptime, rate limits, and latency. Two tools solve this, and picking between them is a scope decision.

Stub fetch when one call decides the assertion. If the handler makes a single outbound request and you care about the exact URL and payload:

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

afterEach(() => vi.unstubAllGlobals())

it('maps a delivered shipment to status "shipped"', async () => {
  fetchMock.mockResolvedValue(Response.json({ status: 'delivered' }))

  const res = await GET(new Request('http://localhost/api/orders/42/track'), {
    params: Promise.resolve({ id: '42' }),
  })

  expect(await res.json()).toEqual({ status: 'shipped' })
  expect(fetchMock).toHaveBeenCalledWith(
    'https://api.shippo.com/tracking/42',
    expect.objectContaining({ headers: expect.objectContaining({ Authorization: expect.any(String) }) }),
  )
})

The second assertion is the valuable one: it pins the contract with the external service — the endpoint and the auth header — so a refactor that drops the bearer token fails here instead of in production.

Use MSW when several endpoints or realistic parsing are involved. msw intercepts at the network layer, so every fetch in the code under test behaves like the real thing:

import { setupServer } from 'msw/node'
import { http, HttpResponse } from 'msw'

const server = setupServer(
  http.get('https://api.shippo.com/tracking/:id', ({ params }) =>
    HttpResponse.json({ status: 'delivered', id: params.id })),
  http.post('https://billing.internal/charges', () =>
    HttpResponse.json({ ok: true }, { status: 201 })),
)

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

onUnhandledRequest: 'error' is the setting that pays for itself: any URL you forgot to mock fails the test immediately instead of quietly reaching the real network from CI. Handlers can be overridden per test with server.use(...) to force an error branch — a 502 from the payment provider — without touching the shared defaults.

MSW also lets you capture the outgoing request, which turns the external call into a contract assertion instead of a side effect:

let captured: Request | undefined
server.use(http.post('https://billing.internal/charges', async ({ request }) => {
  captured = request
  return HttpResponse.json({ ok: true }, { status: 201 })
}))

// ... invoke the handler, then pin what it sent:
expect(await captured!.json()).toEqual({ amount: 1699, currency: 'EUR' })

If the handler starts sending the amount in cents instead of euros, the test names the field — the same guarantee you get from a fetch stub, without owning the URL list yourself.

Reach for next-test-api-route-handler when the handler needs Next's runtime. Cookies read through next/headers, request.nextUrl, segment config, or a revalidatePath call all require the pipeline that a bare new Request skips:

import { testApiHandler } from 'next-test-api-route-handler'  // must be the first import
import * as handler from '@/app/api/me/route'
import { describe, it, expect } from 'vitest'

describe('GET /api/me', () => {
  it('returns 401 without a session cookie', async () => {
    await testApiHandler({
      appHandler: handler,
      url: '/api/me',
      test: async ({ fetch }) => {
        const res = await fetch()
        expect(res.status).toBe(401)
        await expect(res.json()).resolves.toStrictEqual({ error: 'unauthorized' })
      },
    })
  })
})

It runs your route through Next's own resolver, supplies a fetch bound to the handler, and — important — must be imported before anything else, because it patches Next's internals at load time.

Mocking the outside world is what keeps this layer deterministic — and determinism is exactly what lets you assert the failure branches as confidently as the happy path, which is the next chapter's job.

A handler with one passing test is a handler with one exposed flank. The value of this layer is that every branch of the HTTP contract becomes a cheap, explicit test — the kind that catches an access-control mistake before it ships.

Write the table first, then the tests:

Then express it once and run it across the rows:

const cases: [string, Request, number, unknown][] = [
  ['valid body', orderRequest({ sku: 'SLATE-1', qty: 2 }), 201, { id: expect.any(String) }],
  ['qty of zero', orderRequest({ sku: 'SLATE-1', qty: 0 }), 400, { error: { code: 'invalid_body' } }],
  ['qty as text', orderRequest({ sku: 'SLATE-1', qty: 'two' }), 400, { error: { code: 'invalid_body' } }],
]

it.each(cases)('POST /api/orders with %s', async (_name, req, status, body) => {
  const res = await POST(req)
  expect(res.status).toBe(status)
  await expect(res.json()).resolves.toEqual(body)
})

it.each keeps the assertion identical across branches, so a divergence — say, 400 becoming 422 — shows up as a diff on one row rather than as an argument someone has to re-litigate.

Three contract details interviewers probe:

• Error envelopes must be uniform. { error: { code, message } } on every failure means your client has one parser. A handler that returns { message: 'oops' } on one path and { error: '...' } on another forces typeof checks in consuming code — name that trade-off when asked how you design error responses.
• Never leak internals. A 500 in production should be { error: { code: 'internal' } } with the stack in logs, not in the body. Test it: throw deliberately (mock the database to reject with a raw error) and assert the response carries no stack trace, no SQL, no file paths.
• The auth check belongs on every method. The classic miss is a GET guarded by auth() and a sibling DELETE on the same path that forgot it. Import the handler module once and fetch each export — GET, PATCH, DELETE — asserting 401/403 before 200. Method coverage is a one-line loop, and it is where broken access control hides.

for (const method of ['GET', 'PATCH', 'DELETE'] as const) {
  it(`${method} rejects anonymous callers`, async () => {
    const res = await handlers[method](new Request('http://localhost/api/orders/42', {
      method,
    }), { params: Promise.resolve({ id: '42' }) })
    expect([401, 403]).toContain(res.status)
  })
}

Also pin the success headers that consumers quietly depend on: content-type: application/json, cache-control: no-store on personalized responses, and Location on a 201. Someone — often a CDN or a mobile client you will never meet — reads them.

Success paths deserve the same rigor as failures: mock the data layer and assert the row the handler asked to insert, not just the response it returned. A POST that returns { id } while writing the wrong currency is a bug the response alone will never show, and opening a real database to check would trade this layer's determinism for nothing.

With request/response logic under regression protection, the same directness applies to the other server-side primitive in Next.js. Testing Server Actions in Isolation drops even the Request object: an action is just an async function waiting for a FormData.