Registry /
testing / next-test-api-route-handler
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
test
✓ import { test } from 'next-test-api-route-handler';
✗ const { test } = require('next-test-api-route-handler');
Primary testing utility. Use named import. CommonJS `require` is not recommended for modern Next.js projects.
appHandler
✓ import { appHandler } from 'next-test-api-route-handler';
✗ import appHandler from 'next-test-api-route-handler/appHandler';
A helper for testing App Router handlers. It's a named export from the main package.
pagesHandler
✓ import { pagesHandler } from 'next-test-api-route-handler';
✗ import pagesHandler from 'next-test-api-route-handler/pagesHandler';
A helper for testing Pages Router API routes. It's a named export from the main package.
Demonstrates how to test an App Router GET handler using `next-test-api-route-handler`, including passing the handler and patching the request object.
import { test } from 'next-test-api-route-handler';
import { NextResponse } from 'next/server';
// Simulate your actual App Router API handler (e.g., in src/app/api/hello/route.ts)
export async function GET() {
return NextResponse.json({ message: 'Hello from API!' });
}
describe('App Router GET /api/hello', () => {
it('should return a 200 status and a JSON message', async () => {
await test({
url: '/api/hello',
appHandler: GET, // Pass the handler function directly
async test({ fetch }) {
const res = await fetch({ method: 'GET' });
expect(res.status).toBe(200);
const data = await res.json();
expect(data).toEqual({ message: 'Hello from API!' });
},
});
});
it('should allow modifying the request', async () => {
await test({
url: '/api/hello',
appHandler: GET,
requestPatcher: (request) => {
request.headers.set('X-Test-Header', 'Value');
return request;
},
async test({ fetch }) {
const res = await fetch({ method: 'GET' });
expect(res.status).toBe(200);
// In a real handler, you'd access this header via request.headers.get('X-Test-Header')
},
});
});
});
Debug
Known issues
breakingVersion 5.0.0 of `next-test-api-route-handler` introduced a breaking change by dropping support for Node.js 18.fixEnsure your Node.js environment is updated to version `^20.18.0 || >=22.12.0` or later before upgrading to `next-test-api-route-handler` v5+.
affects: >=5.0.0
gotchaFull App Router support in `next-test-api-route-handler` begins with Next.js version `14.0.4`. Using older Next.js versions might lead to unexpected behavior or limited functionality when testing App Router handlers.fixUpgrade your Next.js project to version `14.0.4` or newer for comprehensive App Router testing capabilities. For older Next.js versions, focus on Pages Router testing.
affects: <14.0.4 (Next.js)
gotchaIncompatibilities with specific Next.js releases (e.g., Next.js 15.2 or 15.5) have been observed and addressed in patch versions. Delaying updates can lead to unexpected test failures or runtime errors.fixKeep `next-test-api-route-handler` updated alongside your Next.js installation. Regularly check for new releases of `next-test-api-route-handler` when updating Next.js to ensure continued compatibility.
affects: All versions
gotchaReact Server Components (RSC) functionality, particularly `React.createContext`, may require polyfills in certain Next.js server conditions. Without proper polyfills, tests involving RSCs could fail.fixUpgrade to `next-test-api-route-handler` version `5.0.2` or higher, which includes necessary polyfills to support 'react-server' conditions and `react.createContext`.
affects: <5.0.2
Errors
Common errors & fixes
The `process.versions.node` property indicates an unsupported Node.js version.
Attempting to use `next-test-api-route-handler` v5+ with an unsupported Node.js version (e.g., Node.js 18 or older).
fixUpgrade your Node.js environment to `^20.18.0 || >=22.12.0` or a newer compatible version.
Error: `cookies` can only be used in a `pages/api` or `app` route.
Testing Next.js App Router handlers directly without the `next-test-api-route-handler`'s full emulation of the Next.js runtime context, or using an incompatible version.
fixEnsure your test setup correctly uses `next-test-api-route-handler`'s `test` function with the `appHandler` option, and that your `next-test-api-route-handler` and Next.js versions are compatible (Next.js >=14.0.4 recommended).
TypeError: createContext is not a function
This error can occur in tests involving React Server Components when the `React.createContext` function is not properly polyfilled in the test environment.
fixUpdate `next-test-api-route-handler` to version `5.0.2` or later, as this version includes a polyfill to address this specific issue for 'react-server' conditions.
Audit
Dependencies
nextrequiredRequired as a peer dependency for testing Next.js API routes and handlers.