How do I test Next.js App Router API routes?

In short: Use next-test-api-route-handler as the first import, run Vitest in the node environment, and mock auth() from Auth.js v5. Mock aj.protect() to assert 403 versus 200. Live bot and rate-limit traffic belongs in the functional suite.

How do I test Next.js App Router API routes?

Use next-test-api-route-handler (NTARH). It runs your route.ts exports through Next.js's own resolver so you get real Request / Response objects, cookies(), headers(), and App Router segment config without starting next start.

Next.js does not document a first-party way to unit-test Route Handlers. Official testing guides cover components. Route Handlers depend on patched fetch, NextRequest, optional segment config (runtime, dynamic, preferredRegion), and sometimes the Edge runtime. Calling GET(new Request(...)) yourself skips those internals. node-mocks-http targets the Pages Router req/res pair and does not construct a Web Request.

NTARH is test-framework agnostic. Vitest is the default in new Next.js apps and is what this page uses. Jest still works if the repo already has next/jest. Import NTARH first in the file. That requirement is current: the package patches Next internals at load time, and a later import will resolve the unpatched module.

Write one test per status you care about: unauthenticated 401, authenticated 200, authenticated-but-forbidden 403, and the verb you forgot (POST or DELETE on a GET-only check). Broken access control is still the failure these tests catch. A handler that checks auth() on GET and not on DELETE is the usual miss.

How do I set up next-test-api-route-handler with Vitest?

1
npm i -D vitest next-test-api-route-handler

1
import { defineConfig } from "vitest/config";
2
import path from "node:path";
3

4
export default defineConfig({
5
  test: {
6
    environment: "node",
7
    setupFiles: ["./vitest.setup.ts"],
8
  },
9
  resolve: {
10
    alias: { "@": path.resolve(__dirname, ".") },
11
  },
12
});

1
export async function GET() {
2
  return Response.json({ hello: true }, { status: 200 });
3
}

1
import { testApiHandler } from "next-test-api-route-handler"; // must be first
2
import { describe, it, expect } from "vitest";
3
import * as appHandler from "./route";
4

5
describe("GET /api/hello", () => {
6
  it("returns 200", async () => {
7
    await testApiHandler({
8
      appHandler,
9
      test: async ({ fetch }) => {
10
        const response = await fetch({ method: "GET" });
11
        expect(response.status).toBe(200);
12
        await expect(response.json()).resolves.toStrictEqual({ hello: true });
13
      },
14
    });
15
  });
16
});

Run with npx vitest run. The Jest equivalent is the same testApiHandler call inside it(), with testEnvironment: "node" in jest.config.ts via next/jest. Prefer Vitest unless the repo already has a Jest harness.

NTARH also emulates the Pages Router and the Edge runtime. Pass params for dynamic segments. Use requestPatcher when you need a header or cookie that fetch() will not let you set cleanly.

1
import { testApiHandler } from "next-test-api-route-handler"; // must be first
2
import { expect, it } from "vitest";
3
import * as appHandler from "./route";
4

5
it("reads the dynamic id", async () => {
6
  await testApiHandler({
7
    appHandler,
8
    params: { id: "item_123" },
9
    requestPatcher(request) {
10
      request.headers.set("x-request-id", "test");
11
    },
12
    test: async ({ fetch }) => {
13
      const response = await fetch({ method: "GET" });
14
      expect(response.status).toBe(200);
15
      await expect(response.json()).resolves.toMatchObject({ id: "item_123" });
16
    },
17
  });
18
});

Keep Route Handler tests in the node environment. jsdom is for components. A file that imports both a handler and a client component should be split so the handler file never loads a DOM.

How do I mock Auth.js v5 sessions?

Auth.js v5 (the next-auth package, formerly NextAuth) replaced getServerSession with a single auth() helper exported from your root auth.ts. Mock that module, not next-auth/next.

1
import { auth } from "@/auth";
2

3
export async function GET() {
4
  const session = await auth();
5
  if (!session?.user) {
6
    return Response.json({ error: "Unauthorized" }, { status: 401 });
7
  }
8
  return Response.json({ hello: true }, { status: 200 });
9
}

1
import { testApiHandler } from "next-test-api-route-handler"; // must be first
2
import { afterEach, describe, expect, it, vi } from "vitest";
3
import type { Session } from "next-auth";
4
import * as appHandler from "./route";
5
import { auth } from "@/auth";
6

7
vi.mock("@/auth", () => ({
8
  auth: vi.fn(),
9
}));
10

11
let mockedSession: Session | null = null;
12

13
afterEach(() => {
14
  mockedSession = null;
15
  vi.mocked(auth).mockReset();
16
});
17

18
describe("GET /api/hello", () => {
19
  it("returns 401 when signed out", async () => {
20
    vi.mocked(auth).mockResolvedValue(null);
21

22
    await testApiHandler({
23
      appHandler,
24
      test: async ({ fetch }) => {
25
        const response = await fetch({ method: "GET" });
26
        expect(response.status).toBe(401);
27
        await expect(response.json()).resolves.toStrictEqual({
28
          error: "Unauthorized",
29
        });
30
      },
31
    });
32
  });
33

34
  it("returns 200 when signed in", async () => {
35
    mockedSession = {
36
      expires: "2099-01-01T00:00:00.000Z",
37
      user: { id: "user_1", email: "dev@example.com" },
38
    };
39
    vi.mocked(auth).mockResolvedValue(mockedSession);
40

41
    await testApiHandler({
42
      appHandler,
43
      test: async ({ fetch }) => {
44
        const response = await fetch({ method: "GET" });
45
        expect(response.status).toBe(200);
46
        await expect(response.json()).resolves.toStrictEqual({ hello: true });
47
      },
48
    });
49
  });
50
});

Add a third test that is signed in as user A and requests user B's resource. That is the broken-access-control case these route tests exist to catch.

1
it("returns 403 when the session cannot access the object", async () => {
2
  vi.mocked(auth).mockResolvedValue({
3
    expires: "2099-01-01T00:00:00.000Z",
4
    user: { id: "user_a", email: "a@example.com" },
5
  });
6

7
  await testApiHandler({
8
    appHandler,
9
    params: { userId: "user_b" },
10
    test: async ({ fetch }) => {
11
      const response = await fetch({ method: "DELETE" });
12
      expect(response.status).toBe(403);
13
    },
14
  });
15
});

Clerk and other providers follow the same shape: mock the helper your handler actually calls (currentUser(), auth() from @clerk/nextjs/server, and so on). Do not mock next/headers unless the handler reads cookies itself. If it only calls auth(), that one mock is enough.

v4 code that imported getServerSession from next-auth/next and passed authOptions around should move the config to auth.ts and switch the mock target. Leaving a jest.mock("next-auth/next") in a Vitest file after the migration is a silent pass: the handler no longer calls that module.

How do I test an Arcjet-protected route?

Branch on decision.isDenied() in the handler, then cover both sides in NTARH. For unit tests, mock protect(). For a live rule (bot UA, rate-limit burst), use the functional testing suite against a running server.

1
import arcjet, { detectBot, shield, slidingWindow } from "@arcjet/next";
2

3
export const aj = arcjet({
4
  key: process.env.ARCJET_KEY!,
5
  rules: [
6
    shield({ mode: "LIVE" }),
7
    detectBot({ mode: "LIVE", allow: [] }),
8
    slidingWindow({ mode: "LIVE", interval: 60, max: 100 }),
9
  ],
10
});

1
import { aj } from "@/lib/arcjet";
2

3
export async function GET(req: Request) {
4
  const decision = await aj.protect(req);
5
  if (decision.isDenied()) {
6
    const status = decision.reason.isRateLimit() ? 429 : 403;
7
    return Response.json({ error: "Denied" }, { status });
8
  }
9
  return Response.json({ ok: true });
10
}

1
import { testApiHandler } from "next-test-api-route-handler"; // must be first
2
import { describe, expect, it, vi } from "vitest";
3
import * as appHandler from "./route";
4
import { aj } from "@/lib/arcjet";
5

6
vi.mock("@/lib/arcjet", () => ({
7
  aj: { protect: vi.fn() },
8
}));
9

10
describe("GET /api/secure", () => {
11
  it("returns 403 when Arcjet denies a bot", async () => {
12
    vi.mocked(aj.protect).mockResolvedValue({
13
      isDenied: () => true,
14
      reason: { isRateLimit: () => false },
15
    } as Awaited<ReturnType<typeof aj.protect>>);
16

17
    await testApiHandler({
18
      appHandler,
19
      test: async ({ fetch }) => {
20
        const response = await fetch({ method: "GET" });
21
        expect(response.status).toBe(403);
22
        await expect(response.json()).resolves.toStrictEqual({
23
          error: "Denied",
24
        });
25
      },
26
    });
27
  });
28

29
  it("returns 200 when Arcjet allows", async () => {
30
    vi.mocked(aj.protect).mockResolvedValue({
31
      isDenied: () => false,
32
      reason: { isRateLimit: () => false },
33
    } as Awaited<ReturnType<typeof aj.protect>>);
34

35
    await testApiHandler({
36
      appHandler,
37
      test: async ({ fetch }) => {
38
        const response = await fetch({ method: "GET" });
39
        expect(response.status).toBe(200);
40
        await expect(response.json()).resolves.toStrictEqual({ ok: true });
41
      },
42
    });
43
  });
44
});

The mock proves your handler maps deny to the right status. It does not prove the rule configuration. A User-Agent: curl request against a live detectBot({ allow: [] }) rule is the complementary test. Put that in Newman, k6, or a second Vitest file that starts the app. If you mock protect() and never run a live request, a typo in allow: [] will ship.

Also test POST and DELETE on the same path. NTARH will call whichever export you fetch. A GET that checks auth() and a POST that does not is a common access-control miss.

When protect() needs a real request shape (IP, user agent, body), prefer requestPatcher plus a live Arcjet client in DRY_RUN only for logging. Assertions on deny require LIVE and a running decide path, which is slower and needs ARCJET_KEY. Keep those tests in the functional suite so unit tests stay offline.

How do I test the Edge runtime?

If the route exports export const runtime = "edge", tell NTARH so it uses the Edge resolver. A Node-environment test that passes against an Edge handler can hide node:crypto or fs imports that will fail in production.

1
await testApiHandler({
2
  appHandler,
3
  // NTARH reads runtime from the module export when present.
4
  test: async ({ fetch }) => {
5
    const response = await fetch({ method: "GET" });
6
    expect(response.status).toBe(200);
7
  },
8
});

Do not test Server Components or Server Actions with NTARH. It is a Route Handler tool. Components belong in a component runner or Playwright. Actions that call auth() and aj.protect() can use the same mocks in a direct function call, but they will not exercise cookies the way a handler does.

Assert the contract the client depends on: status, JSON shape, and Retry-After or your deny body. Do not assert the full Arcjet decision object in a unit test. That object changes with SDK versions and is not part of your HTTP API.

Frequently asked questions

How do I test Next.js App Router API routes?

Use next-test-api-route-handler. Import it first, pass the route module as appHandler, and call fetch() inside test(). Prefer Vitest with environment node.

What replaced getServerSession?

Auth.js v5 exports auth() from your root auth.ts. Mock @/auth, not next-auth/next. A leftover getServerSession mock after the migration is a silent pass.

Should I use Jest or Vitest?

Vitest is the usual default in new Next.js apps. Jest plus next/jest still works. NTARH is framework-agnostic.

How do I test an Arcjet-protected route?

Mock aj.protect() to return isDenied() true or false and assert 403/429 versus 200. Prove the live rule with Newman or k6 against a running server.

Does NTARH test Server Components?

No. It is a Route Handler tool. Components belong in a component runner or Playwright.

Application security in your code

Protect your application with Arcjet

Get rate limits, bot detection, and attack blocking in your request handlers.

Get an Arcjet account Read the docs

How do I test Next.js App Router API routes?

How do I set up next-test-api-route-handler with Vitest?

How do I mock Auth.js v5 sessions?

How do I test an Arcjet-protected route?

How do I test the Edge runtime?

Frequently asked questions

Protect your application with Arcjet

Related guides

How do I functionally test security rules?