next-test-api-route-handler (NTARH)

NTARH is designed for unit testing API route handlers, not for recreating the full Next.js runtime. Because of this, several Next.js features are not available:

• Middleware and NextResponse.next()
• Metadata, Static Assets, and Styling
• OpenTelemetry, Instrumentation, and Caching
• Server Actions and Mutations
• React components
• Helper functions (except: cookies, fetch (global), headers, NextRequest, NextResponse, notFound, permanentRedirect, redirect, and userAgent)

Important Runtime Note: While NTARH provides support for the "edge runtime", your tests will always run in Node.js (or your chosen test runner). It does not run in a different runtime, realm, or VM. NTARH should be used for unit testing handlers in addition to, not instead of, end-to-end testing.

To ensure Next.js internal resolvers work correctly, next-test-api-route-handler must always be the first import in your test file.

ESM usage:

import { testApiHandler } from 'next-test-api-route-handler'; // ◄ Must be first
import * as myHandler from '../app/api/route';

CJS usage:

const { testApiHandler } = require('next-test-api-route-handler'); // ◄ Must be first
const myHandler = require('../app/api/route');

If you use automated import sorting (like eslint-plugin-import), you can import NTARH as a side-effect first to satisfy the requirement:

import 'next-test-api-route-handler';

// ... other imports ...
import { testApiHandler } from 'next-test-api-route-handler';

import { testApiHandler } from 'next-test-api-route-handler'; // ◄ Must be first

... all other imports ...

To simulate specific request or response states in a Pages Router test, use the requestPatcher and responsePatcher properties within the testApiHandler configuration.

Request Patching

Use requestPatcher to modify the IncomingMessage. This is useful for setting custom headers or properties. Important: When adding or replacing headers, all header names must be lowercase.

Response Patching

Use responsePatcher to modify the ServerResponse object before it is passed to your handler.

Shorthands

• To set the URL: Use the url property (e.g., url: '/api/path').
• To set params: Use the params property (e.g., params: { slug: 'my-post' }).

If your project uses jsdom by default, you may encounter errors (like TypeError: RequestInit: Expected signal...) because jsdom does not support global fetch natively and API routes do not require a DOM.

To fix this, use a Jest docblock annotation to switch the environment to node for your API test files.

/**
 * @jest-environment node
 */

import { testApiHandler } from 'next-test-api-route-handler';

test('use the node test environment for all tests in this file', () => {
  //...
});

Next.js's App Router implementation mutates the global fetch function. This can interfere with testing tools like Mock Service Worker (MSW) or Jest spies.

NTARH sidesteps this by caching the original globalThis.fetch upon import, but it does not restore it after the test returns. If you need to ensure a clean environment, you should manually capture the original fetch and restore it in an afterEach block.

const originalGlobalFetch = fetch;

afterEach(function () {
  // Undo what Next.js does to the global fetch function
  globalThis.fetch = originalGlobalFetch;
});

To test a Pages Router handler, import the handler and its configuration from your pages/api directory and pass it to testApiHandler using the pagesHandler property. You can use requestPatcher to modify the req object.

import { testApiHandler } from 'next-test-api-route-handler';
import * as pagesHandler from '../pages/api/your-endpoint';

it('does what I want', async () => {
  await testApiHandler<{ hello: string }>({
    pagesHandler,
    requestPatcher: (req) => {
      req.headers = { key: process.env.SPECIAL_TOKEN };
    },
    test: async ({ fetch }) => {
      const res = await fetch({ method: 'POST', body: 'data' });
      const { hello } = await res.json();
      expect(hello).toBe('world');
    }
  });
});

Install the package as a development dependency using npm:

npm install --save-dev next-test-api-route-handler

Note on environments: If you are using jest or vitest with a DOM-like environment (such as jest-environment-jsdom or jsdom), you should not use that environment to test your API handlers. Refer to the project appendix for details on JSDOM support.

The AppRouteRouteModule and its dependencies require AsyncLocalStorage to be available globally and immediately. Since Node.js does not place AsyncLocalStorage in globalThis natively, NTARH injects it.

To prevent errors, next-test-api-route-handler must be the very first import in your test file.

import { testApiHandler } from 'next-test-api-route-handler';
// This must be the first import in the file

The rejectOnHandlerError boolean controls how exceptions thrown inside your route handler are treated during tests.

• false (Default): Errors are passed to the Next.js resolver, mimicking production behavior. This may result in a 500 response being returned instead of a test failure.
• true: The testApiHandler function will reject immediately when an error is thrown in the handler.

When to use true:

• When you want to manually handle errors thrown from within the handler.
• If you are using expect() assertions inside your handler code.
• If you encounter false negatives where exceptions are thrown but the test does not fail as expected.

rejectOnHandlerError: true