Why can Route Handlers in App Router be tested without starting an HTTP server, unlike Pages Router?

Pages Router handlers depended on Node.js http.IncomingMessage and http.ServerResponse instances, requiring mocked wrappers or supertest server listeners. App Router handlers operate on standard Web API Request and Response primitives, which execute natively within modern Node.js and can be directly instantiated in tests without a network stack.

What is the difference between standard Request and NextRequest from 'next/server' during testing?

NextRequest extends the standard Web Request class by adding conveniences: a pre-parsed nextUrl (NextURL instance with built-in searchParams parsing), a cookies helper (ReadonlyRequestCookies API), and server metadata. When testing handlers expecting NextRequest, instantiate new NextRequest(...) to satisfy method signatures.

How do you test cookie assignment and expiration via NextResponse?

When calling response.cookies.set() or response.cookies.delete(), Next.js sets a standard 'Set-Cookie' header. In tests, inspect response.headers.get('set-cookie') and verify that the expected token, along with HttpOnly, Secure, and SameSite flags, are present.

How did the second argument signature for Route Handlers change in Next.js 15, and how does this affect tests?

In Next.js 15, context.params became asynchronous: Promise . In unit and integration tests, route parameters passed in the context argument must be wrapped in a Promise: { params: Promise.resolve({ id: '123' }) }, and handlers must resolve it with await context.params.

What happens when request.json() is called twice, and how can this be addressed in tests or middlewares?

The request body is a single-consumption ReadableStream. Once read, it becomes 'disturbed' and locked. Attempting a second read throws a TypeError. To consume the body multiple times, call request.clone() before the initial read pass.

How do you verify the output of a Server-Sent Events (SSE) stream in an integration test?

Verify the presence of 'Content-Type: text/event-stream' and HTTP status 200. Acquire response.body.getReader() and iteratively consume chunks, decoding them via new TextDecoder().decode(chunk). Assert that the accumulated payload conforms to the SSE protocol format (prefixing lines with 'data: ' and terminating messages with '\n\n').

How do you simulate client request cancellation (AbortSignal) when testing streaming endpoints?

Instantiate new AbortController() and pass its signal into the request constructor: new NextRequest(url, { signal: controller.signal }). During chunk consumption, trigger controller.abort(). Assert that the stream handler terminates cleanly, closes database connections, and releases resources within its finally block.

Integration Testing of Route Handlers (API) — Testing & QA Automation

Architectural Foundation#

In the Next.js 15 App Router architecture, API endpoints are implemented as Route Handlers. Unlike legacy Pages Router API Routes (req: NextApiRequest, res: NextApiResponse), modern handlers fully adhere to the WHATWG Fetch Standard.

This transition to standardized Web APIs brings significant architectural advantages to testing:

Serverless In-Memory Execution: A Route Handler is a standard exported asynchronous function with the signature export async function GET(request: NextRequest, context: RouteContext): Promise<Response>. It can be directly executed inside Vitest tests in a Node.js runtime by supplying synthetic Request or NextRequest instances without spinning up a physical HTTP listener.
Native Web Streams API Support: Streaming AI outputs, Server-Sent Events (SSE), and large file transfers operate natively on ReadableStream.
Unified Asynchronous Context in Next.js 15: In Next.js 15, dynamic route segment parameters context.params are asynchronous (Promise<{ [key: string]: string | string[] }>), unifying async I/O handling across the framework.

Integration testing Route Handlers enables microsecond-level verification of OpenAPI contracts, HTTP response codes, CORS policies, session cookie management, and streaming pipeline integrity.

Mental Model#

In the testing mental model, a Route Handler is viewed as a pure functional transformer converting a standard Web Request into a Web Response:

text

+-------------------------------------------------------------------------------+
|                    Vitest Test Runner (Node.js Environment)                   |
+-------------------------------------------------------------------------------+
       │
       ├─► 1. Construct new NextRequest('https://api.domain/endpoint?filter=active')
       ├─► 2. Append Headers: new Headers({ 'Content-Type': 'application/json' })
       ├─► 3. Supply dynamic params context: { params: Promise.resolve(...) }
       │
       ▼
+-------------------------------------------------------------------------------+
|                      Route Handler (app/api/.../route.ts)                     |
+-------------------------------------------------------------------------------+
       │
       ├─► Bearer Token / Session Authentication
       ├─► Validate Request Body: await req.json() (Zod Schema)
       ├─► Delegate to Data Access Layer (DAL / Drizzle)
       │
       ▼
+-------------------------------------------------------------------------------+
|                    Result: Response / NextResponse                            |
+-------------------------------------------------------------------------------+
       │
       ├─► expect(res.status).toBe(200 | 201 | 400 | 401 | 500)
       ├─► const body = await res.json()
       ├─► expect(res.headers.get('set-cookie')).toBeDefined()
       └─► const reader = res.body.getReader() (for ReadableStream / SSE)

Applied in Production#

REST API Contract Verification: Asserting HTTP status codes (200 OK, 201 Created, 400 Bad Request on invalid payloads, 401 on missing auth tokens, 403 on insufficient permissions, 404 when resources do not exist).
Security Headers and CORS Preflight Validation: Verifying that OPTIONS preflight requests correctly set Access-Control-Allow-Origin and Access-Control-Allow-Headers for public or partner APIs.
Session Cookie Lifecycle Management: Testing issuance, rotation, and revocation of HTTP-only cookies equipped with Secure, SameSite=Strict, and Path=/ flags.
Validating Data Streaming Pipelines (AI Streaming / SSE): Confirming continuous chunk emission without buffering the entire payload using ReadableStream.

How It Works#

1. Testing GET Endpoints with Query Parameters and Async Params#

Here is a Route Handler delivering project analytics for dynamic routes app/api/projects/[id]/analytics/route.ts. In Next.js 15, context.params returns a Promise.

typescriptsrc/app/api/projects/[id]/analytics/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { getProjectAnalytics } from '@/dal/analytics';

interface RouteContext {
  params: Promise<{ id: string }>;
}

export async function GET(request: NextRequest, context: RouteContext): Promise<Response> {
  // In Next.js 15, params is asynchronous
  const { id } = await context.params;

  if (!id || id === 'invalid') {
    return NextResponse.json({ error: 'Invalid project identifier' }, { status: 400 });
  }

  const { searchParams } = request.nextUrl;
  const period = searchParams.get('period') || '30d';

  const analytics = await getProjectAnalytics(id, period);

  if (!analytics) {
    return NextResponse.json({ error: 'Project not found' }, { status: 404 });
  }

  return NextResponse.json(
    { data: analytics, meta: { period, generatedAt: new Date().toISOString() } },
    {
      status: 200,
      headers: {
        'Cache-Control': 'private, no-cache, no-store',
      },
    }
  );
}

typescriptsrc/app/api/projects/[id]/analytics/route.test.ts

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { NextRequest } from 'next/server';
import { GET } from './route';
import * as dal from '@/dal/analytics';

vi.mock('@/dal/analytics', () => ({
  getProjectAnalytics: vi.fn(),
}));

describe('GET /api/projects/[id]/analytics', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('returns 200 OK and analytics data for valid parameters', async () => {
    vi.mocked(dal.getProjectAnalytics).mockResolvedValue({
      views: 12500,
      conversions: 450,
    });

    // Construct NextRequest with query parameters
    const request = new NextRequest('https://agenticlab.dev/api/projects/proj-101/analytics?period=7d');

    // Construct asynchronous context for Next.js 15
    const context = {
      params: Promise.resolve({ id: 'proj-101' }),
    };

    const response = await GET(request, context);

    expect(response.status).toBe(200);
    expect(response.headers.get('Cache-Control')).toBe('private, no-cache, no-store');

    const json = await response.json();
    expect(json.data).toEqual({ views: 12500, conversions: 450 });
    expect(json.meta.period).toBe('7d');
    expect(dal.getProjectAnalytics).toHaveBeenCalledWith('proj-101', '7d');
  });

  it('returns 404 Not Found when project does not exist', async () => {
    vi.mocked(dal.getProjectAnalytics).mockResolvedValue(null);

    const request = new NextRequest('https://agenticlab.dev/api/projects/not-found/analytics');
    const context = {
      params: Promise.resolve({ id: 'not-found' }),
    };

    const response = await GET(request, context);

    expect(response.status).toBe(404);
    const json = await response.json();
    expect(json.error).toBe('Project not found');
  });

  it('returns 400 Bad Request on invalid identifier', async () => {
    const request = new NextRequest('https://agenticlab.dev/api/projects/invalid/analytics');
    const context = {
      params: Promise.resolve({ id: 'invalid' }),
    };

    const response = await GET(request, context);

    expect(response.status).toBe(400);
    expect(dal.getProjectAnalytics).not.toHaveBeenCalled();
  });
});

This authentication endpoint accepts user credentials, verifies the password, and returns a response setting a secure session cookie.

typescriptsrc/app/api/auth/login/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { verifyCredentials } from '@/dal/auth';

const LoginSchema = z.object({
  email: z.string().email('Invalid email format'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});

export async function POST(request: NextRequest): Promise<Response> {
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return NextResponse.json({ error: 'Malformed JSON payload' }, { status: 400 });
  }

  const parsed = LoginSchema.safeParse(body);
  if (!parsed.success) {
    return NextResponse.json(
      { error: 'Validation error', details: parsed.error.flatten().fieldErrors },
      { status: 422 }
    );
  }

  const session = await verifyCredentials(parsed.data.email, parsed.data.password);
  if (!session) {
    return NextResponse.json({ error: 'Invalid email or password' }, { status: 401 });
  }

  const response = NextResponse.json(
    { user: { id: session.userId, email: parsed.data.email } },
    { status: 200 }
  );

  // Set secure HttpOnly cookie
  response.cookies.set({
    name: 'auth_session',
    value: session.token,
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
    path: '/',
    maxAge: 60 * 60 * 24 * 7, // 7 days
  });

  return response;
}

typescriptsrc/app/api/auth/login/route.test.ts

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { NextRequest } from 'next/server';
import { POST } from './route';
import * as authDal from '@/dal/auth';

vi.mock('@/dal/auth');

describe('POST /api/auth/login', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('returns 200 OK and sets secure session cookie on valid credentials', async () => {
    vi.mocked(authDal.verifyCredentials).mockResolvedValue({
      userId: 'usr-900',
      token: 'jwt.enterprise.token',
    });

    const payload = {
      email: '[email protected]',
      password: 'StrongSecretPassword123!',
    };

    const request = new NextRequest('https://agenticlab.dev/api/auth/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    });

    const response = await POST(request);

    expect(response.status).toBe(200);

    const json = await response.json();
    expect(json.user.id).toBe('usr-900');

    // Assert Set-Cookie header attributes
    const setCookie = response.headers.get('set-cookie');
    expect(setCookie).toBeDefined();
    expect(setCookie).toContain('auth_session=jwt.enterprise.token');
    expect(setCookie).toContain('HttpOnly');
    expect(setCookie).toContain('SameSite=Strict');
  });

  it('returns 422 Unprocessable Entity on invalid email', async () => {
    const request = new NextRequest('https://agenticlab.dev/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'not-an-email', password: '123' }),
    });

    const response = await POST(request);

    expect(response.status).toBe(422);
    const json = await response.json();
    expect(json.error).toBe('Validation error');
    expect(json.details.email).toBeDefined();
    expect(authDal.verifyCredentials).not.toHaveBeenCalled();
  });

  it('returns 401 Unauthorized on invalid credentials', async () => {
    vi.mocked(authDal.verifyCredentials).mockResolvedValue(null);

    const request = new NextRequest('https://agenticlab.dev/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: '[email protected]', password: 'WrongPassword123' }),
    });

    const response = await POST(request);

    expect(response.status).toBe(401);
    const json = await response.json();
    expect(json.error).toBe('Invalid email or password');
  });
});

3. Testing ReadableStream / SSE Streaming Responses#

In modern architectures, Route Handlers frequently emit real-time stream data (LLM token generation or Server-Sent Events). To test streams, read chunks through a native ReadableStreamDefaultReader and decode bytes via TextDecoder.

typescriptsrc/app/api/stream/events/route.test.ts

import { describe, it, expect } from 'vitest';
import { NextRequest } from 'next/server';
import { GET } from './route';

describe('GET /api/stream/events (ReadableStream SSE)', () => {
  it('delivers streaming response with 200 status and SSE chunks', async () => {
    const request = new NextRequest('https://agenticlab.dev/api/stream/events');
    const response = await GET(request);

    expect(response.status).toBe(200);
    expect(response.headers.get('Content-Type')).toContain('text/event-stream');
    expect(response.headers.get('Cache-Control')).toBe('no-cache');
    expect(response.body).toBeDefined();

    // Read chunks from ReadableStream
    const reader = response.body!.getReader();
    const decoder = new TextDecoder();
    const chunks: string[] = [];

    let isDone = false;
    while (!isDone) {
      const { value, done } = await reader.read();
      if (done) {
        isDone = true;
      } else if (value) {
        chunks.push(decoder.decode(value, { stream: true }));
      }
    }

    const fullContent = chunks.join('');
    expect(fullContent).toContain('data: {"event":"connected"}');
    expect(fullContent).toContain('data: {"event":"ready"}');
  });
});

Common Pitfalls#

Ошибка: Re-reading request.json() Triggers Disturbed Stream Exception

Unlike legacy req.body, the body of a native Request is a one-time ReadableStream. Attempting to consume it multiple times (e.g., inside a logging utility and subsequently within the route handler) throws TypeError: Body has already been consumed or is disturbed.

typescript

// ❌ FAILS: Multiple body consumption attempts
const clone = request; // Does not clone the underlying byte stream!
await request.json();
await clone.json(); // Throws: body already disturbed

// ✅ SECURE: Call request.clone() BEFORE the first consumption pass
const requestClone = request.clone();
const data1 = await request.json();
const data2 = await requestClone.json();

Ошибка: Synchronous Access to context.params in Next.js 15

In Next.js 15, the params property on the second handler argument (context) is a Promise<{ ... }>. Accessing context.params.id directly resolves to undefined because properties cannot be read synchronously off an unresolved Promise.

typescript

// ❌ WRONG: params is a Promise in Next.js 15
export async function GET(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
  const id = (params as unknown as Record<string, string>).id; // undefined!
}

// ✅ CORRECT: Await context.params
export async function GET(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
}

Ошибка: Omitting OPTIONS Handler When Implementing Custom CORS Headers

If you append CORS response headers manually without exporting a dedicated export async function OPTIONS() preflight handler, browser preflight requests will receive 405 Method Not Allowed, blocking client cross-origin traffic. Always test preflight behavior.

Ошибка: Hanging ReadableStream Tests Due to Unclosed Stream Controllers

If a server stream implementation fails to call controller.close(), a reader loop while (!done) { await reader.read() } will block indefinitely and trigger a Vitest test timeout. Always ensure mock streams terminate reliably or simulate cancellation via reader.cancel().

Step-by-Step Route Handler Testing Workflow#

API endpoint integration testing procedure

Synthesize NextRequestRequest Factory

Instantiate synthetic request with full URL, HTTP method, headers, and body payload.

Prepare Async ContextContext

Wrap dynamic segment parameters into Promise.resolve(params) for Next.js 15 compatibility.

Mock Data LayerMocks

Isolate database calls and external downstream services using vi.mock().

Invoke Route HandlerDispatch

Call the exported GET/POST/DELETE function directly as an asynchronous function.

Assert Status and HeadersHTTP Assert

Verify res.status, Content-Type headers, CORS directives, and caching attributes.

Parse and Assert BodyPayload

Parse payload via await res.json() or stream chunks via reader.read().

Interview Questions#

Interview Questions7 questions

Integration Testing of Route Handlers (API)

Architectural Foundation#

Mental Model#

Applied in Production#

How It Works#

1. Testing GET Endpoints with Query Parameters and Async Params#

2. Testing POST Endpoints: Zod Validation and Set-Cookie Headers#

3. Testing ReadableStream / SSE Streaming Responses#

Common Pitfalls#

Ошибка: Re-reading request.json() Triggers Disturbed Stream Exception

Ошибка: Synchronous Access to context.params in Next.js 15

Ошибка: Omitting OPTIONS Handler When Implementing Custom CORS Headers

Ошибка: Hanging ReadableStream Tests Due to Unclosed Stream Controllers

Step-by-Step Route Handler Testing Workflow#

Interview Questions#

Related Topics#

Architectural Foundation#

Mental Model#

Applied in Production#

How It Works#

1. Testing GET Endpoints with Query Parameters and Async Params#

2. Testing POST Endpoints: Zod Validation and Set-Cookie Headers#

3. Testing ReadableStream / SSE Streaming Responses#

Common Pitfalls#

Ошибка: Re-reading request.json() Triggers Disturbed Stream Exception

Ошибка: Synchronous Access to context.params in Next.js 15

Ошибка: Omitting OPTIONS Handler When Implementing Custom CORS Headers

Ошибка: Hanging ReadableStream Tests Due to Unclosed Stream Controllers

Step-by-Step Route Handler Testing Workflow#

Interview Questions#

Related Topics#