Confidently test your Next.js API routes in an isolated Next-like environment

---

next-test-api-route-handler

Trying to unit test your Next.js API routes? Tired of hacking something together with express or node-mocks-http or writing a bunch of boring dummy infra just to get some passing tests? And what does a "passing test" mean anyway when your handlers aren't receiving actual [NextRequest][1] objects and aren't being run by Next.js itself?

Next.js patches the global fetch function, for instance. If your tests aren't doing the same, you're making space for bugs!

Is it vexing that everything explodes when your [App Router][2] handlers call headers() or cookies() or any of the other route-specific [helper functions][3]? Or maybe you want your [Pages Router][4] handlers to receive actual [NextApiRequest][5] and [NextApiResponse][5] objects?

Sound interesting? Then want no longer! 🤩

[next-test-api-route-handler][x-badge-repo-link] (NTARH) uses Next.js's internal resolvers to precisely emulate route handling. To guarantee stability, this package is [automatically tested][6] against [each release of Next.js][7] and Node.js. Go forth and test confidently!

---

• Install
• Usage
  • Quick Start: App Router
  • Quick Start: Edge Runtime
  • Quick Start: Pages Router
• API
  • appHandler
  • pagesHandler
  • test
  • rejectOnHandlerError
  • requestPatcher (url)
  • responsePatcher
  • paramsPatcher (params)
• Examples
  • Using the App Router
  • Using the Pages Router
• Appendix
  • Limitations with App Router and Edge Runtime Emulation
  • Legacy Runtime Support
  • Jsdom Support
  • Inspiration
  • Published Package Details
  • License
• Contributing and Support
  • Contributors

Install

To install:

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

See [the appendix][9] for legacy Next.js support options.

Also see [the appendix][10] if you're using jest and jest-environment-jsdom.

Usage

[!IMPORTANT]

NTARH must always be the first import in your test file. This is due to the way Next.js is written and distributed. See [the appendix][11] for technical details.

1// ESM
2import { testApiHandler } from 'next-test-api-route-handler'; // ◄ Must be first
3
4... all other imports ...

1// CJS
2const { testApiHandler } = require('next-test-api-route-handler'); // ◄ Must be first
3
4... all other imports ...

If you're using fancy import sorting like [eslint-plugin-import's "order" rule][102], import NTARH as a [side-effect][x-pkg-side-effects-key] first, then perform the real import later:

1import 'next-test-api-route-handler';
2
3... all other imports ordered before NTARH ...
4import { testApiHandler } from 'next-test-api-route-handler';
5... all other imports ordered after NTARH ...

Quick Start: App Router

1/* File: test/unit.test.ts */
2
3import { testApiHandler } from 'next-test-api-route-handler'; // ◄ Must be first import
4// Import the handler under test from the app directory
5import * as appHandler from '../app/your-endpoint/route';
6
7it('does what I want', async () => {
8  await testApiHandler({
9    appHandler,
10    // requestPatcher is optional
11    requestPatcher(request) {
12      request.headers.set('key', process.env.SPECIAL_TOKEN);
13    },
14    // responsePatcher is optional
15    async responsePatcher(response) {
16      const json = await response.json();
17      return Response.json(
18        json.apiSuccess ? { hello: 'world!' } : { goodbye: 'cruel world' }
19      );
20    },
21    async test({ fetch }) {
22      const res = await fetch({ method: 'POST', body: 'dummy-data' });
23      await expect(res.json()).resolves.toStrictEqual({ hello: 'world!' }); // ◄ Passes!
24    }
25  });
26});

Quick Start: Edge Runtime

1/* File: test/unit.test.ts */
2
3import { testApiHandler } from 'next-test-api-route-handler'; // ◄ Must be first import
4// Import the handler under test from the app directory
5import * as edgeHandler from '../app/your-edge-endpoint/route';
6
7it('does what I want', async function () {
8  // NTARH supports optionally typed response data via TypeScript generics:
9  await testApiHandler<{ success: boolean }>({
10    // Only appHandler supports edge functions. The pagesHandler prop does not!
11    appHandler: edgeHandler,
12    // requestPatcher is optional
13    requestPatcher(request) {
14      return new Request(request, {
15        body: dummyReadableStream,
16        duplex: 'half'
17      });
18    },
19    async test({ fetch }) {
20      // The next line would cause TypeScript to complain:
21      // const { luck: success } = await (await fetch()).json();
22      await expect((await fetch()).json()).resolves.toStrictEqual({
23        success: true // ◄ Passes!
24      });
25    }
26  });
27});

Quick Start: Pages Router

1/* File: test/unit.test.ts */
2
3import { testApiHandler } from 'next-test-api-route-handler'; // ◄ Must be first import
4// Import the handler under test and its config from the pages/api directory
5import * as pagesHandler from '../pages/api/your-endpoint';
6
7it('does what I want', async () => {
8  // NTARH supports optionally typed response data via TypeScript generics:
9  await testApiHandler<{ hello: string }>({
10    pagesHandler,
11    requestPatcher: (req) => {
12      req.headers = { key: process.env.SPECIAL_TOKEN };
13    },
14    test: async ({ fetch }) => {
15      const res = await fetch({ method: 'POST', body: 'data' });
16      // The next line would cause TypeScript to complain:
17      // const { goodbye: hello } = await res.json();
18      const { hello } = await res.json();
19      expect(hello).toBe('world'); // ◄ Passes!
20    }
21  });
22});

API

NTARH exports a single function, testApiHandler(options), that accepts an options object as its only parameter.

At minimum, options must contain the following properties:

• At least one of the appHandler or pagesHandler options, but not both.
• The test option.

For example:

[!CAUTION]

Ensuring testApiHandler is imported [before][12] any Next.js package (like 'next/headers' below) is crucial to the proper function of NTARH. Doing otherwise will result in undefined behavior.

1import { testApiHandler } from 'next-test-api-route-handler';
2import { headers } from 'next/headers';
3
4await testApiHandler({
5  appHandler: {
6    dynamic: 'force-dynamic',
7    async GET(_request) {
8      return Response.json(
9        {
10          // Yep, those fancy helper functions work too!
11          hello: (await headers()).get('x-hello')
12        },
13        { status: 200 }
14      );
15    }
16  },
17  async test({ fetch }) {
18    await expect(
19      (await fetch({ headers: { 'x-hello': 'world' } })).json()
20    ).resolves.toStrictEqual({
21      hello: 'world'
22    });
23  }
24});

appHandler

⪢ API reference: [appHandler][13]

The actual route handler under test (usually imported from app/*). It should be an object and/or exported module containing one or more [valid uppercase HTTP method names][14] as keys, each with an [async handling function][15] that accepts a [NextRequest][1] and ["segment data"][16] (i.e. { params }) as its two parameters. The object or module can also export [other configuration settings recognized by Next.js][17].

1await testApiHandler({
2  params: { id: 5 },
3  appHandler: {
4    async POST(request, { params: { id } }) {
5      return Response.json(
6        { special: request.headers.get('x-special-header'), id },
7        { status: 200 }
8      );
9    }
10  },
11  async test({ fetch }) {
12    expect((await fetch({ method: 'POST' })).status).toBe(200);
13
14    const result2 = await fetch({
15      method: 'POST',
16      headers: { 'x-special-header': 'x' }
17    });
18
19    expect(result2.json()).toStrictEqual({ special: 'x', id: 5 });
20  }
21});

See also: [rejectOnHandlerError][18] and the section [Working Around Next.js fetch Patching][19].

pagesHandler

⪢ API reference: [pagesHandler][20]

The actual route handler under test (usually imported from pages/api/*). It should be an async function that accepts [NextApiRequest][5] and [NextApiResponse][5] objects as its two parameters.

1await testApiHandler({
2  params: { id: 5 },
3  pagesHandler: (req, res) => res.status(200).send({ id: req.query.id }),
4  test: async ({ fetch }) =>
5    expect((await fetch({ method: 'POST' })).json()).resolves.toStrictEqual({
6      id: 5
7    })
8});

See also: [rejectOnHandlerError][18].

test

⪢ API reference: [test][21]

An async or promise-returning function wherein test assertions can be run. This function receives one destructured parameter: fetch, which is a wrapper around Node's [global fetch][22] function. Use this to send HTTP requests to the handler under test.

[!CAUTION]

Note that fetch's resource parameter, i.e. [the first parameter in fetch(...)][23], is omitted.

⚙ Handling Redirections

Starting with version 4.0.4, NTARH sets the [fetch(...) options][24] parameter's [redirect property to 'manual'][25] by default. This prevents the WHATWG/undici fetch function from throwing a fetch failed/redirect count exceeded error.

If you want to change this value, call fetch with your own custom options parameter, e.g. fetch({ redirect: 'error' }).

⚙ Compatibility with Mock Service Worker

Starting with version 4.0.0, NTARH ships with [Mock Service Worker (msw)][26] support by adding the [x-msw-intention: "bypass"][27] and x-msw-bypass: "true" headers to all requests.

If necessary, you can override this behavior by setting the appropriate headers to some other value (e.g. "none") via fetch's customInit parameter (not requestPatcher). This comes in handy when testing functionality like [arbitrary response redirection][28] (or via the [Pages Router][29]).

For example:

1import { testApiHandler } from 'next-test-api-route-handler';
2import { http, passthrough, HttpResponse } from 'msw';
3import { setupServer } from 'msw/node';
4
5const server = setupServer(/* ... */);
6
7beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
8
9afterEach(() => {
10  server.resetHandlers();
11});
12
13afterAll(() => server.close());
14
15it('redirects a shortened URL to the real URL', async () => {
16  expect.hasAssertions();
17
18  // e.g. https://xunn.at/gg => https://www.google.com/search?q=next-test-api-route-handler
19  // shortId would be "gg"
20  // realLink would be https://www.google.com/search?q=next-test-api-route-handler
21
22  const { shortId, realLink } = getUriEntry();
23  const realUrl = new URL(realLink);
24
25  await testApiHandler({
26    appHandler,
27    params: { shortId },
28    test: async ({ fetch }) => {
29      server.use(
30        http.get('*', async ({ request }) => {
31          return request.url === realUrl.href
32            ? HttpResponse.json({ it: 'worked' }, { status: 200 })
33            : passthrough();
34        })
35      );
36
37      const res = await fetch({
38        headers: { 'x-msw-intention': 'none' } // <==
39      });
40
41      await expect(res.json()).resolves.toMatchObject({ it: 'worked' });
42      expect(res.status).toBe(200);
43    }
44  });
45});

⚙ response.cookies

As of version 2.3.0, the response object returned by fetch() includes a non-standard cookies field containing an array of objects representing [set-cookie response header(s)][30] parsed by [the cookie package][31]. Use the cookies field to easily access a response's cookie data in your tests.

Here's an example taken straight from the [unit tests][32]:

1import { testApiHandler } from 'next-test-api-route-handler';
2
3it('handles multiple set-cookie headers', async () => {
4  expect.hasAssertions();
5
6  await testApiHandler({
7    pagesHandler: (_, res) => {
8      // Multiple calls to setHeader('Set-Cookie', ...) overwrite previous, so
9      // we have to set the Set-Cookie header properly
10      res
11        .setHeader('Set-Cookie', [
12          serializeCookieHeader('access_token', '1234', {
13            expires: new Date()
14          }),
15          serializeCookieHeader('REFRESH_TOKEN', '5678')
16        ])
17        .status(200)
18        .send({});
19    },
20    test: async ({ fetch }) => {
21      expect((await fetch()).status).toBe(200);
22      await expect((await fetch()).json()).resolves.toStrictEqual({});
23      expect((await fetch()).cookies).toStrictEqual([
24        {
25          access_token: '1234',
26          // Lowercased cookie property keys are available
27          expires: expect.any(String),
28          // Raw cookie property keys are also available
29          Expires: expect.any(String)
30        },
31        { refresh_token: '5678', REFRESH_TOKEN: '5678' }
32      ]);
33    }
34  });
35});

rejectOnHandlerError

⪢ API reference: [rejectOnHandlerError][33]

As of version 2.3.0, unhandled errors in the pagesHandler/appHandler function are kicked up to Next.js to handle.

[!IMPORTANT]

This means testApiHandler will NOT reject or throw if an unhandled error occurs in pagesHandler/appHandler, which typically includes failing expect() assertions.

Instead, the response returned by fetch() in your test function will have a HTTP 500 status [thanks to how Next.js deals with unhandled errors in production][34]. Prior to 2.3.0, NTARH's behavior on unhandled errors and elsewhere was inconsistent. Version 3.0.0 further improved error handling, ensuring no errors slip by uncaught.

To guard against false negatives, you can do either of the following:

1. Make sure the status of the fetch() response is what you're expecting:

1const res = await fetch();
2...
3// For this test, a 403 status is what we wanted
4expect(res.status).toBe(403);
5...
6const res2 = await fetch();
7...
8// Later, we expect an "unhandled" error
9expect(res2.status).toBe(500);

2. If you're using version >=3.0.0, you can use rejectOnHandlerError to tell NTARH to intercept unhandled handler errors and reject the promise returned by testApiHandler instead of relying on Next.js to respond with HTTP 500. This is especially useful if you have expect() assertions inside your handler function:

1await expect(
2  testApiHandler({
3    rejectOnHandlerError: true, // <==
4    pagesHandler: (_req, res) => {
5      res.status(200);
6      throw new Error('bad bad not good');
7    },
8    test: async ({ fetch }) => {
9      const res = await fetch();
10      // By default, res.status would be 500...
11      //expect(res.status).toBe(500);
12    }
13  })
14  // ...but since we used rejectOnHandlerError, the whole promise rejects
15  // instead
16).rejects.toThrow('bad not good');
17
18await testApiHandler({
19  rejectOnHandlerError: true, // <==
20  appHandler: {
21    async GET(request) {
22      // Suppose this expectation fails
23      await expect(backend.getSomeStuff(request)).resolves.toStrictEqual(
24        someStuff
25      );
26
27      return new Response(null, { status: 200 });
28    }
29  },
30  test: async ({ fetch }) => {
31    await fetch();
32    // By default, res.status would be 500 due to the failing expect(). If we
33    // don't also expect() a non-500 response status here, the failing
34    // expectation in the handler will be swallowed and the test will pass
35    // (a false negative).
36  }
37});
38// ...but since we used rejectOnHandlerError, the whole promise rejects
39// and it is reported that the test failed, which is probably what you wanted.

requestPatcher (url)

[!TIP]

Manually setting the request url is usually unnecessary. Only set the url if [your handler expects it][35] or [you want to rely on query string parsing instead of params/paramsPatcher][36].

💎 Using appHandler

⪢ API reference: [requestPatcher][37], [url][38]

requestPatcher is a function that receives a [NextRequest][1] object and returns a [Request][39] instance. Use this function to edit the request before it's injected into the handler.

[!CAUTION]

Be wary returning a brand new request from requestPatcher (i.e. new NextRequest(newUrl) instead of new NextRequest(newUrl, oldRequest)), especially one that is missing standard headers added by fetch(...). If you're getting strange JSON-related errors or hanging tests, ensure this is not the cause.

The returned [Request][39] instance will be wrapped with [NextRequest][1] if it is not already an instance of [NextRequest][1], i.e.:

1const returnedRequest = (await requestPatcher?.(request)) || request;
2const nextRequest = new NextRequest(returnedRequest, { ... });

If you're only setting the request url, use the url shorthand instead:

1await testApiHandler({
2  // requestPatcher: (request) => new Request('ntarh:///my-url?some=query', request),
3  url: '/my-url?some=query'
4});

[!NOTE]

Unlike the Pages Router's NextApiRequest type, the App Router's NextRequest class [does not support relative URLs][40]. Therefore, whenever you pass a relative url string via the url shorthand (e.g. { url: '/my-url?some=query' }), NTARH will wrap that url like so: new URL(url, 'ntarh://'). In this case, your requests will have urls like ntarh:///my-url?some=query.

URL Normalization

By default, when initializing the NextRequest object passed to your handler, if a URL with an empty pathname is encountered, NTARH sets said URL's pathname to "/" on your behalf. Additionally, if said URL is missing host and/or protocol, NTARH sets host to "" and protocol to "ntarh:".

If you want your handler to receive the URL string and resulting NextRequest::nextUrl object exactly as you've typed it, use requestPatcher, which is executed after NTARH does URL normalization.

🔷 Using pagesHandler

⪢ API reference: [requestPatcher][41], [url][42]

requestPatcher is a function that receives an [IncomingMessage][43]. Use this function to modify the request before it's injected into Next.js's resolver.

If you're only setting the request url, use the url shorthand instead:

1await testApiHandler({
2  // requestPatcher: (req) => { req.url = '/my-url?some=query'; }
3  url: '/my-url?some=query'
4});

Note that, unlike with [the URL class][44], the url string can be relative.

responsePatcher

💎 Using appHandler

⪢ API reference: [responsePatcher][45]

responsePatcher is a function that receives the [Response][46] object returned from appHandler and returns a [Response][46] instance. Use this function to edit the response after your handler runs but before it's processed by the server.

🔷 Using pagesHandler

⪢ API reference: [responsePatcher][47]

responsePatcher is a function that receives a [ServerResponse][48] object. Use this function to edit the response before it's injected into the handler.

paramsPatcher (params)

paramsPatcher is a function that receives an object representing "processed" [dynamic segments][49] (aka: routes, slugs).

For example, to test a handler normally accessible from /api/user/:id requires passing that handler a value for the "id" dynamic segment:

1await testApiHandler({
2  paramsPatcher(params) {
3    params.id = 'test-id';
4  }
5});

Or:

1await testApiHandler({
2  paramsPatcher: (params) => ({ id: 'test-id' })
3});

Parameters can also be passed using the params shorthand:

1await testApiHandler({
2  params: {
3    id: 'test-id'
4  }
5});

[!TIP]

Due to its simplicity, favor the params shorthand over paramsPatcher.

💎 Using appHandler

⪢ API reference: [paramsPatcher][50], [params][51]

[!IMPORTANT]

Note that, starting with next@15, the params object passed to handlers via the context parameter [is now a (Frankensteinian) promise][52]. This means tests like expect(params).toStrictEqual(...) will no longer work unless params is first await-ed. More information [here][53].

If both paramsPatcher and the params shorthand are used, paramsPatcher will receive params as its first argument.

Route parameters should not be confused with [query string parameters][54], which are automatically parsed out from the url and made available via the [NextRequest][1] argument passed to your handler.

🔷 Using pagesHandler

⪢ API reference: [paramsPatcher][55], [params][56]

If both paramsPatcher and the params shorthand are used, paramsPatcher will receive an object like { ...queryStringURLParams, ...params } as its first argument.

Route parameters should not be confused with [query string parameters][54], which are automatically parsed out from the url and added to the params object before paramsPatcher is evaluated.

Examples

What follows are several examples that demonstrate using NTARH with the [App Router][57] and the [Pages Router][58].

Check out [the tests][59] for even more examples.

Using the App Router

These examples use Next.js's [App Router][60] API.

Testing Apollo's Official Next.js Integration @ app/api/graphql

This example is based on [the official Apollo Next.js App Router integration][61]. You can run it yourself by copying and pasting the following commands into your terminal.

The following should be run in a nix-like environment. On Windows, that's [WSL][62]. Requires curl, node, and git.

1mkdir -p /tmp/ntarh-test/test
2cd /tmp/ntarh-test
3npm install --force next @apollo/server @as-integrations/next graphql-tag next-test-api-route-handler jest babel-jest @babel/core @babel/preset-env
4echo 'module.exports={presets:["@babel/preset-env"]};' > babel.config.js
5mkdir -p app/api/graphql
6curl -o app/api/graphql/route.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw_app_route
7curl -o test/integration.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw_app_test
8npx jest

This script creates a new temporary directory, installs NTARH and configures dependencies, downloads the [app route][63] and [jest test][64] files shown below, and runs the test using [jest][65].

The following is our new app route:

1/* File: app/api/graphql/route.js */
2
3import { ApolloServer } from '@apollo/server';
4import { startServerAndCreateNextHandler } from '@as-integrations/next';
5import { gql } from 'graphql-tag';
6
7const resolvers = {
8  Query: {
9    hello: () => 'world'
10  }
11};
12
13const typeDefs = gql`
14  type Query {
15    hello: String
16  }
17`;
18
19const server = new ApolloServer({
20  resolvers,
21  typeDefs
22});
23
24const handler = startServerAndCreateNextHandler(server);
25
26export { handler as GET, handler as POST };

And with the following jest test, we ensure our route integrates with Apollo correctly:

1/* File: tests/integration.test.js */
2
3import { testApiHandler } from 'next-test-api-route-handler';
4// Import the handler under test from the app/api directory
5import * as appHandler from '../app/api/graphql/route';
6
7describe('my-test (app router)', () => {
8  it('does what I want 1', async () => {
9    expect.hasAssertions();
10
11    await testApiHandler({
12      appHandler,
13      test: async ({ fetch }) => {
14        const query = `query { hello }`;
15
16        const res = await fetch({
17          method: 'POST',
18          headers: {
19            'content-type': 'application/json' // Must use correct content type
20          },
21          body: JSON.stringify({ query })
22        });
23
24        await expect(res.json()).resolves.toStrictEqual({
25          data: { hello: 'world' }
26        });
27      }
28    });
29  });
30
31  it('does what I want 2', async () => {
32    // Exactly the same as the above...
33  });
34
35  it('does what I want 3', async () => {
36    // Exactly the same as the above...
37  });
38});

Testing Clerk's Official Next.js Integration @ app/api/authed

Suppose we created a new authenticated API endpoint at app/api/authed by [cloning the Clerk App Router demo repo][66] and following [Clerk's quick-start guide for Next.js][67]:

1/* File: app/api/authed/route.ts */
2
3import { auth } from '@clerk/nextjs';
4
5export async function GET() {
6  const { userId } = auth();
7  return Response.json({ isAuthed: !!userId, userId });
8}

How might we test that this endpoint functions as we expect?

1/* File: test/unit.test.ts */
2
3import { testApiHandler } from 'next-test-api-route-handler';
4import * as appHandler from '../app/api/authed/route';
5
6import type { auth } from '@clerk/nextjs';
7
8let mockedClerkAuthReturnValue: Partial<ReturnType<typeof auth>> | undefined =
9  undefined;
10
11jest.mock('@clerk/nextjs', () => {
12  return {
13    auth() {
14      return mockedClerkAuthReturnValue;
15    }
16  };
17});
18
19afterEach(() => {
20  mockedClerkAuthReturnValue = undefined;
21});
22
23it('returns isAuthed: true and a userId when authenticated', async () => {
24  expect.hasAssertions();
25
26  mockedClerkAuthReturnValue = { userId: 'winning' };
27
28  await testApiHandler({
29    appHandler,
30    test: async ({ fetch }) => {
31      await expect((await fetch()).json()).resolves.toStrictEqual({
32        isAuthed: true,
33        userId: 'winning'
34      });
35    }
36  });
37});
38
39it('returns isAuthed: false and nothing else when unauthenticated', async () => {
40  expect.hasAssertions();
41
42  mockedClerkAuthReturnValue = { userId: null };
43
44  await testApiHandler({
45    appHandler,
46    test: async ({ fetch }) => {
47      await expect((await fetch()).json()).resolves.toStrictEqual({
48        isAuthed: false,
49        userId: null
50      });
51    }
52  });
53});

If you're feeling more adventurous, you can transform this unit test into an integration test (like the Apollo example above) by calling Clerk's [authMiddleware][68] function in appHandler instead of mocking @clerk/nextjs:

1// This integration test also requires your Clerk dashboard is setup in test
2// mode and your Clerk secret key information is available in process.env. Said
3// information must be available BEFORE any Clerk packages are imported! You
4// will also have to setup authMiddleware properly in ../middleware.ts
5
6/* ... same imports as before ... */
7// Also import our Next.js middleware
8import { default as middleware } from '../middleware';
9// And we want to keep our types as tight as we can too
10import type { NextRequest } from 'next/server';
11
12const DUMMY_CLERK_USER_ID = 'user_2aqlGWnjdTRRbbBk9OdBHHbniyK';
13
14it('returns isAuthed: true and a userId when authenticated', async () => {
15  expect.hasAssertions();
16
17  await testApiHandler({
18    rejectOnHandlerError: true,
19    // You may want to alter the default URL pathname like below if your Clerk
20    // middleware is using path-based filtering. By default, the pathname
21    // will always be '/' because 'ntarh://testApiHandler/' is the default url
22    url: 'ntarh://app/api/authed',
23    appHandler: {
24      get GET() {
25        return async function (...args: Parameters<typeof appHandler.GET>) {
26          const request = args.at(0) as unknown as NextRequest;
27          const middlewareResponse = await middleware(request, {
28            /* ... */
29          });
30
31          // Make sure we're not being redirected to the sign in page since
32          // this is a publicly available endpoint
33          expect(middlewareResponse.headers.get('location')).toBeNull();
34          expect(middlewareResponse.ok).toBe(true);
35
36          const handlerResponse = await appHandler.GET(...args);
37
38          // You could run some expectations here (since rejectOnHandlerError is
39          // true), or you can run your remaining expectations in the test
40          // function below. Either way is fine.
41
42          return handlerResponse;
43        };
44      }
45    },
46    test: async ({ fetch }) => {
47      await expect((await fetch()).json()).resolves.toStrictEqual({
48        isAuthed: true,
49        userId: DUMMY_CLERK_USER_ID
50      });
51    }
52  });
53});
54
55/* ... */

You can also try calling [authMiddleware][68] in requestPatcher; however, Clerk's middleware does its magic by importing the headers helper function from 'next/headers', and only functions invoked within appHandler have access to the storage context that allows Next.js's helper functions to work. For insight into what you'd need to do to make [authMiddleware][68] callable in requestPatcher, check out [Clerk's own tests][69].

Testing an Unreliable Handler on the Edge @ app/api/unreliable

Suppose we have an API endpoint we use to test our application's error handling. The endpoint responds with status code HTTP 200 for every request except the 10th, where status code HTTP 555 is returned instead.

How might we test that this endpoint responds with HTTP 555 once for every nine HTTP 200 responses?

1/* File: test/unit.test.ts */
2
3import { testApiHandler } from 'next-test-api-route-handler';
4// Import the handler under test from the app/api directory
5import * as edgeHandler from '../app/api/unreliable';
6
7const expectedReqPerError = 10;
8
9it('injects contrived errors at the required rate', async () => {
10  expect.hasAssertions();
11
12  // Signal to the edge endpoint (which is configurable) that there should be 1
13  // error among every 10 requests
14  process.env.REQUESTS_PER_CONTRIVED_ERROR = expectedReqPerError.toString();
15
16  await testApiHandler({
17    appHandler: edgeHandler,
18    requestPatcher(request) {
19      // Our edge handler expects Next.js to provide geo and ip data with the
20      // request, so let's add some. This is also where you'd mock/emulate the
21      // effects of any Next.js middleware
22      //
23      // IMPORTANT: starting with next@15, geo/ip have been removed from
24      // NextRequest and were functionally replaced by @vercel/function
25      // https://github.com/vercel/next.js/pull/68379
26      // https://nextjs.org/docs/app/building-your-application/upgrading/version-15#nextrequest-geolocation
27      return new NextRequest(request, {
28        geo: { city: 'Chicago', country: 'United States' },
29        ip: '110.10.77.7'
30      });
31    },
32    test: async ({ fetch }) => {
33      // Run 20 requests with REQUESTS_PER_CONTRIVED_ERROR = '10' and
34      // record the results
35      const results1 = await Promise.all(
36        [
37          ...Array.from({ length: expectedReqPerError - 1 }).map(() =>
38            fetch({ method: 'GET' })
39          ),
40          fetch({ method: 'POST' }),
41          ...Array.from({ length: expectedReqPerError - 1 }).map(() =>
42            fetch({ method: 'PUT' })
43          ),
44          fetch({ method: 'DELETE' })
45        ].map((p) => p.then((r) => r.status))
46      );
47
48      process.env.REQUESTS_PER_CONTRIVED_ERROR = '0';
49
50      // Run 10 requests with REQUESTS_PER_CONTRIVED_ERROR = '0' and record the
51      // results
52      const results2 = await Promise.all(
53        Array.from({ length: expectedReqPerError }).map(() =>
54          fetch().then((r) => r.status)
55        )
56      );
57
58      // We expect results1 to be an array with eighteen `200`s and two
59      // `555`s in any order
60      //
61      // https://github.com/jest-community/jest-extended#toincludesamemembersmembers
62      // because responses could be received out of order
63      expect(results1).toIncludeSameMembers([
64        ...Array.from({ length: expectedReqPerError - 1 }).map(() => 200),
65        555,
66        ...Array.from({ length: expectedReqPerError - 1 }).map(() => 200),
67        555
68      ]);
69
70      // We expect results2 to be an array with ten `200`s
71      expect(results2).toStrictEqual([
72        ...Array.from({ length: expectedReqPerError }).map(() => 200)
73      ]);
74    }
75  });
76});

Using the Pages Router

These examples use Next.js's [Pages Router][70] API.

Testing Next.js's Official Apollo Example @ pages/api/graphql

This example uses the [official Next.js Apollo demo][71]. You can easily run it yourself by copying and pasting the following commands into your terminal.

The following should be run in a nix-like environment. On Windows, that's [WSL][62]. Requires curl, node, and git.

1git clone --depth=1 https://github.com/vercel/next.js /tmp/ntarh-test
2cd /tmp/ntarh-test/examples/api-routes-apollo-server-and-client
3npm install --force
4npm install --force next-test-api-route-handler jest babel-jest @babel/core @babel/preset-env
5# You could test with an older version of Next.js if you want, e.g.:
6# npm install --force next@9.0.6
7# Or even older:
8# npm install --force next@9.0.0 next-server
9echo 'module.exports={presets:["@babel/preset-env"]};' > babel.config.js
10mkdir test
11curl -o test/integration.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw
12npx jest

This script clones [the Next.js repository][72], installs NTARH and configures dependencies, downloads the [jest test][73] file shown below, and runs it using [jest][65] to ensure our route integrates with Apollo correctly.

[!IMPORTANT]

Note that passing the [route configuration object][74] (imported below as config) through to NTARH and setting request.url to the proper value [may be necessary][75] when testing Apollo endpoints using the Pages Router.

1/* File: examples/api-routes-apollo-server-and-client/tests/integration.test.js */
2
3import { testApiHandler } from 'next-test-api-route-handler';
4// Import the handler under test from the pages/api directory
5import * as pagesHandler from '../pages/api/graphql';
6
7describe('my-test (pages router)', () => {
8  it('does what I want 1', async () => {
9    expect.hasAssertions();
10
11    await testApiHandler({
12      pagesHandler,
13      url: '/api/graphql', // Set the request url to the path graphql expects
14      test: async ({ fetch }) => {
15        const query = `query ViewerQuery {
16          viewer {
17            id
18            name
19            status
20          }
21        }`;
22
23        const res = await fetch({
24          method: 'POST',
25          headers: {
26            'content-type': 'application/json' // Must use correct content type
27          },
28          body: JSON.stringify({ query })
29        });
30
31        await expect(res.json()).resolves.toStrictEqual({
32          data: { viewer: { id: '1', name: 'John Smith', status: 'cached' } }
33        });
34      }
35    });
36  });
37
38  it('does what I want 2', async () => {
39    // Exactly the same as the above...
40  });
41
42  it('does what I want 3', async () => {
43    // Exactly the same as the above...
44  });
45});

Testing an Authenticated Flight Search Handler @ pages/api/v3/flights/search

Suppose we have an authenticated API endpoint our application uses to search for flights. The endpoint responds with an array of flights satisfying the query.

How might we test that this endpoint returns flights in our database as expected?

1/* File: test/unit.test.ts */
2
3import { testApiHandler } from 'next-test-api-route-handler';
4import { DUMMY_API_KEY as KEY, getFlightData, RESULT_SIZE } from '../backend';
5import * as pagesHandler from '../pages/api/v3/flights/search';
6
7import type { PageConfig } from 'next';
8
9it('returns expected public flights with respect to match', async () => {
10  expect.hasAssertions();
11
12  // Get the flight data currently in the test database
13  const expectedFlights = getFlightData();
14
15  // Take any JSON object and stringify it into a URL-ready string
16  const encode = (o: Record<string, unknown>) =>
17    encodeURIComponent(JSON.stringify(o));
18
19  // This function will return in order the URIs we're interested in testing
20  // against our handler. Query strings are parsed by NTARH automatically.
21  //
22  // NOTE: setting the request url manually using encode(), while valid, is
23  // unnecessary here; we could have used `params` or `paramsPatcher` to do this
24  // more easily without explicitly setting a dummy request url.
25  //
26  // Example URI for `https://site.io/path?param=yes` would be `/path?param=yes`
27  const genUrl = (function* () {
28    // For example, the first should match all the flights from Spirit airlines!
29    yield `/?match=${encode({ airline: 'Spirit' })}`;
30    yield `/?match=${encode({ type: 'departure' })}`;
31    yield `/?match=${encode({ landingAt: 'F1A' })}`;
32    yield `/?match=${encode({ seatPrice: 500 })}`;
33    yield `/?match=${encode({ seatPrice: { $gt: 500 } })}`;
34    yield `/?match=${encode({ seatPrice: { $gte: 500 } })}`;
35    yield `/?match=${encode({ seatPrice: { $lt: 500 } })}`;
36    yield `/?match=${encode({ seatPrice: { $lte: 500 } })}`;
37  })();
38
39  await testApiHandler({
40    // Patch the request object to include our dummy URI
41    requestPatcher: (req) => {
42      req.url = genUrl.next().value || undefined;
43      // Could have done this instead of `fetch({ headers: { KEY }})` below:
44      // req.headers = { KEY };
45    },
46
47    pagesHandler,
48
49    test: async ({ fetch }) => {
50      // 8 URLs from genUrl means 8 calls to fetch:
51      const responses = await Promise.all(
52        Array.from({ length: 8 }).map(() =>
53          fetch({ headers: { KEY } }).then(async (r) => [
54            r.status,
55            await r.json()
56          ])
57        )
58      );
59
60      // We expect all of the responses to be 200
61      expect(responses.some(([status]) => status !== 200)).toBe(false);
62
63      // We expect the array of flights returned to match our
64      // expectations given we already know what dummy data will be
65      // returned:
66
67      // https://github.com/jest-community/jest-extended#toincludesamemembersmembers
68      // because responses could be received out of order
69      expect(responses.map(([, r]) => r.flights)).toIncludeSameMembers([
70        expectedFlights
71          .filter((f) => f.airline === 'Spirit')
72          .slice(0, RESULT_SIZE),
73        expectedFlights
74          .filter((f) => f.type === 'departure')
75          .slice(0, RESULT_SIZE),
76        expectedFlights
77          .filter((f) => f.landingAt === 'F1A')
78          .slice(0, RESULT_SIZE),
79        expectedFlights
80          .filter((f) => f.seatPrice === 500)
81          .slice(0, RESULT_SIZE),
82        expectedFlights.filter((f) => f.seatPrice > 500).slice(0, RESULT_SIZE),
83        expectedFlights.filter((f) => f.seatPrice >= 500).slice(0, RESULT_SIZE),
84        expectedFlights.filter((f) => f.seatPrice < 500).slice(0, RESULT_SIZE),
85        expectedFlights.filter((f) => f.seatPrice <= 500).slice(0, RESULT_SIZE)
86      ]);
87    }
88  });
89
90  // We expect these two to fail with 400 errors
91
92  await testApiHandler({
93    pagesHandler,
94    url: `/?match=${encode({ ffms: { $eq: 500 } })}`,
95    test: async ({ fetch }) =>
96      expect((await fetch({ headers: { KEY } })).status).toBe(400)
97  });
98
99  await testApiHandler({
100    pagesHandler,
101    url: `/?match=${encode({ bad: 500 })}`,
102    test: async ({ fetch }) =>
103      expect((await fetch({ headers: { KEY } })).status).toBe(400)
104  });
105});

Testing an Unreliable Handler @ pages/api/unreliable

Suppose we have an API endpoint we use to test our application's error handling. The endpoint responds with status code HTTP 200 for every request except the 10th, where status code HTTP 555 is returned instead.

How might we test that this endpoint responds with HTTP 555 once for every nine HTTP 200 responses?

1/* File: test/unit.test.ts */
2
3import { testApiHandler } from 'next-test-api-route-handler';
4// Import the handler under test from the pages/api directory
5import * as pagesHandler from '../pages/api/unreliable';
6
7const expectedReqPerError = 10;
8
9it('injects contrived errors at the required rate', async () => {
10  expect.hasAssertions();
11
12  // Signal to the endpoint (which is configurable) that there should be 1
13  // error among every 10 requests
14  process.env.REQUESTS_PER_CONTRIVED_ERROR = expectedReqPerError.toString();
15
16  await testApiHandler({
17    pagesHandler,
18    test: async ({ fetch }) => {
19      // Run 20 requests with REQUESTS_PER_CONTRIVED_ERROR = '10' and
20      // record the results
21      const results1 = await Promise.all(
22        [
23          ...Array.from({ length: expectedReqPerError - 1 }).map(() =>
24            fetch({ method: 'GET' })
25          ),
26          fetch({ method: 'POST' }),
27          ...Array.from({ length: expectedReqPerError - 1 }).map(() =>
28            fetch({ method: 'PUT' })
29          ),
30          fetch({ method: 'DELETE' })
31        ].map((p) => p.then((r) => r.status))
32      );
33
34      process.env.REQUESTS_PER_CONTRIVED_ERROR = '0';
35
36      // Run 10 requests with REQUESTS_PER_CONTRIVED_ERROR = '0' and record the
37      // results
38      const results2 = await Promise.all(
39        Array.from({ length: expectedReqPerError }).map(() =>
40          fetch().then((r) => r.status)
41        )
42      );
43
44      // We expect results1 to be an array with eighteen `200`s and two
45      // `555`s in any order
46      //
47      // https://github.com/jest-community/jest-extended#toincludesamemembersmembers
48      // because responses could be received out of order
49      expect(results1).toIncludeSameMembers([
50        ...Array.from({ length: expectedReqPerError - 1 }).map(() => 200),
51        555,
52        ...Array.from({ length: expectedReqPerError - 1 }).map(() => 200),
53        555
54      ]);
55
56      // We expect results2 to be an array with ten `200`s
57      expect(results2).toStrictEqual([
58        ...Array.from({ length: expectedReqPerError }).map(() => 200)
59      ]);
60    }
61  });
62});

Appendix

Further documentation can be found under [docs/][x-repo-docs].

Limitations with App Router and Edge Runtime Emulation

Since NTARH is meant for unit testing API routes rather than faithfully recreating Next.js functionality, NTARH's feature set comes with some caveats. Namely: no Next.js features will be available that are external to processing API routes and executing their handlers. This includes [middleware][76] and NextResponse.next (see [requestPatcher][77] if you need to mutate the Request before it gets to the handler under test), [metadata][78], [static assets][79], [OpenTelemetry][80] and [instrumentation][81], [caching][82], [styling][83], [server actions and mutations][84], [helper functions][3] (except: cookies, fetch (global), headers, NextRequest, NextResponse, notFound, permanentRedirect, redirect, and userAgent), and anything related to React or [components][85].

NTARH is for testing your API route handlers only.

Further, any support NTARH appears to have for any "[edge runtime][86]" (or any other runtime) beyond what is provided by [AppRouteRouteModule][87] is merely cosmetic. Your tests will always run in Node.js (or your runner of choice) and never in a different runtime, realm, or VM. This means unit testing like with NTARH must be done in addition to, and not in lieu of, more holistic testing practices (e.g. [end-to-end][88]).

If you're having trouble with your App Router and/or Edge Runtime routes, consider [opening a new issue][x-repo-choose-new-issue]!

Also note that Next.js's middleware only supports the Edge runtime, even if the Next.js application is being run entirely by Node.js. This is an artificial constraint imposed by Next.js; when running the middleware locally (via npm run dev or something similar), the middleware will still run on Node.js.

Next.js's middleware limitation is discussed at length [here][89].

Working around the App Router Patching the Global fetch Function

Next.js's current App Router implementation mutates the global fetch function, redefining it entirely. This can cause [problems][90] in testing environments where the global fetch is to be mocked by something else.

Internally, NTARH sidesteps this issue entirely by caching the value of globalThis.fetch upon import. This also means NTARH completely sidesteps other tools that rely on interception through rewriting the global fetch function, such as [Mock Service Worker (MSW)][91]. We still include the MSW bypass headers with NTARH requests since we cannot guarantee that NTARH will not be imported after MSW has finished patching global fetch.

Similarly, it is impossible for NTARH to meaningfully track mutations to the global fetch function; NTARH cannot tell the difference between Next.js overwriting fetch and, say, a Jest spy overwriting fetch. Therefore, NTARH does not restore the cached fetch after the function returns.

If Next.js's patching of fetch is causing trouble for you, you can do what NTARH does: capture the current global fetch (perhaps after setting up MSW) and then restore it after each test:

1const originalGlobalFetch = fetch;
2
3afterEach(function () {
4  // Undo what Next.js does to the global fetch function
5  globalThis.fetch = originalGlobalFetch;
6});

Working around Global AsyncLocalStorage Availability

AppRouteRouteModule and its dependents want AsyncLocalStorage to be available globally and immediately. Unfortunately, Node.js does not place AsyncLocalStorage in globalThis natively.

NTARH handles this by ensuring AsyncLocalStorage is added to globalThis before Next.js needs it. This is why [NTARH should always be the very first import in any test file][12].

Legacy Runtime Support

As of version 4.0.0, NTARH supports both the App Router (for next@>=14.0.4) and the "legacy" Pages Router Next.js APIs. However, due to the code churn with next@13, NTARH's support for the App Router begins at next@14.0.4. See [here][8] and [here][92] for more information.

Additionally, as of version 2.1.0, NTARH's Pages Router support is fully backwards compatible with Next.js going allll the way back to next@9.0.0 [when API routes were first introduced][93]!

If you're working with the Pages Router and next@<9.0.6 (so: [before next-server was merged into next][94]), you might need to install next-server manually:

1npm install --save-dev next-server

Similarly, if you are using npm@<7 or node@<15, you must install Next.js and its peer dependencies manually. This is because [npm@<7 does not install peer dependencies by default][95].

1npm install --save-dev next@latest react

If you're also using an older version of Next.js, ensure you install the [peer dependencies (like react) that your specific Next.js version requires][96]!

Jsdom Support

Note that [jsdom does not support global fetch natively][97]. This should not be an issue, however, since neither your API code nor your API test code should be executed in a browser-like environment.

For projects configured to use jsdom by default, you can use an annotation to switch environments only in the files housing your API tests:

1/**
2 * @jest-environment node
3 */
4// ⬆⬆⬆⬆⬆⬆⬆⬆⬆⬆⬆⬆⬆
5
6import { testApiHandler } from 'next-test-api-route-handler';
7
8test('use the node test environment for all tests in this file', () => {
9  //...
10});

If you're dead set on using jsdom over the node testing environment with NTARH, see [here][98] and [here][99] for workarounds.

Inspiration

I'm constantly creating things with Next.js. Most of these applications have a major API component. Unfortunately, Next.js doesn't make unit testing your APIs very easy. After a while, I noticed some conventions forming around how I liked to test my APIs and NTARH was born 🙂

Of course, this all was back before the app router or edge routes existed. NTARH got app router and edge route support in version 4.

My hope is that NTARH gets obsoleted because Vercel provided developers with some officially supported tooling/hooks for lightweight route execution where handlers are passed fully initialized instances of NextRequest/NextResponse/NextApiRequest/NextApiResponse without ballooning the execution time of the tests. That is: no spinning up the entire Next.js runtime just to run a single test in isolation.

It doesn't seem like it'd be such a lift to surface a wrapped version of the Pages Router's [apiResolver][100] function and a pared-down subclass of the App Router's [AppRouteRouteModule][87], both accessible with something like import { ... } from 'next/test'. This is essentially what NTARH does.

History: The Very Very First Version of Ntarh

Was looking over some ancient Next.js projects and found some of the very first versions of what would eventually become NTARH. My inner code hoarder requires I note this code's existence somewhere.

Oh how far we've come 🙂

![alt text][101]

Published Package Details

This is a [CJS2 package][x-pkg-cjs-mojito] with statically-analyzable exports built by Babel for use in Node.js versions that are not end-of-life. For TypeScript users, this package supports both "Node10" and "Node16" module resolution strategies.

Expand details

That means both CJS2 (via require(...)) and ESM (via import { ... } from ... or await import(...)) source will load this package from the same entry points when using Node. This has several benefits, the foremost being: less code shipped/smaller package size, avoiding [dual package hazard][x-pkg-dual-package-hazard] entirely, distributables are not packed/bundled/uglified, a drastically less complex build process, and CJS consumers aren't shafted.

Each entry point (i.e. ENTRY) in [package.json's exports[ENTRY]][x-repo-package-json] object includes one or more [export conditions][x-pkg-exports-conditions]. These entries may or may not include: an [exports[ENTRY].types][x-pkg-exports-types-key] condition pointing to a type declaration file for TypeScript and IDEs, a [exports[ENTRY].module][x-pkg-exports-module-key] condition pointing to (usually ESM) source for Webpack/Rollup, a exports[ENTRY].node and/or exports[ENTRY].default condition pointing to (usually CJS2) source for Node.js require/import and for browsers and other environments, and [other conditions][x-pkg-exports-conditions] not enumerated here. Check the [package.json][x-repo-package-json] file to see which export conditions are supported.

Note that, regardless of the [{ "type": "..." }][x-pkg-type] specified in [package.json][x-repo-package-json], any JavaScript files written in ESM syntax (including distributables) will always have the .mjs extension. Note also that [package.json][x-repo-package-json] may include the [sideEffects][x-pkg-side-effects-key] key, which is almost always false for optimal [tree shaking][x-pkg-tree-shaking] where appropriate.

License

See [LICENSE][x-repo-license].

Contributing and Support

[New issues][x-repo-choose-new-issue] and [pull requests][x-repo-pr-compare] are always welcome and greatly appreciated! 🤩 Just as well, you can [star 🌟 this project][x-badge-repo-link] to let me know you found it useful! ✊🏿 Or [buy me a beer][x-repo-sponsor], I'd appreciate it. Thank you!

See [CONTRIBUTING.md][x-repo-contributing] and [SUPPORT.md][x-repo-support] for more information.

Contributors

Thanks goes to these wonderful people ([emoji key][x-repo-all-contributors-emojis]):

Bernard 🚇 💻 📖 🚧 ⚠️ 👀	Kevin Jennison 📖	jonkers3 📖	Valentin Hervieu 💻 🤔 🔬 ⚠️	Dana Woodman 🚇	Rhys 🤔
Prakhar Shukla 🐛	Jake Jones 🐛 🤔 🔬	Diego Esclapez 🐛	k2xl 🔬	Jeremy Walker 💡	Adrian Kriegel 💡
hems.io 🐛 🔬 🤔 💡	Steve Taylor 🤔	Will Nixon 🐛 🔬	Sebastien Powell 💡	Hajin Lim 🤔	Jane 💡
Jan Hesters 🐛	Bence Somogyi 🐛 💻 🔬 ⚠️	Tony 🔬	Jaakko Jokinen 🐛 🔬 🤔	Arun Sathiya 🔬 💻	Scott Symmank 🔬 🐛
Matias De Carli 📖	Xing Xiang 📖	Kaarle Järvinen 🐛	Rory Ou