Package Exports
- next-test-api-route-handler
- next-test-api-route-handler/package
- next-test-api-route-handler/package.json
Readme
next-test-api-route-handler
Trying to unit test your Next.js API route handlers? Want to avoid mucking around with custom servers and writing boring test infra just to get some unit tests working? Want your handlers to receive actual NextApiRequest and NextApiResponse objects rather than having to hack something together with express? Then look no further! 🤩
next-test-api-route-handler
(NTARH) uses Next.js's internal API resolver to
precisely emulate API route handling. To guarantee stability, this package is
automatically tested against each release of Next.js. Go forth and
test confidently!
Install
If you don't have Next.js available, ensure it is installed as it is a required peer dependency:
npm install --save-dev next@latest
Install NTARH:
npm install --save-dev next-test-api-route-handler
[additional details]
Note: you probably don't need to read through this! This information is primarily useful for those attempting to bundle this package or for people who have an opinion on ESM versus CJS.
This is a dual CJS2/ES module package. That means this package exposes both CJS2 and ESM entry points.
Loading this package via require(...)
will cause Node and Webpack to use the
CJS2 bundle entry point, disable tree shaking in Webpack
4, and lead to larger bundles in Webpack 5. Alternatively, loading this package
via import { ... } from ...
or import(...)
will cause Node to use the ESM
entry point in versions that support it, as will Webpack.
Using the import
syntax is the modern, preferred choice.
For backwards compatibility with Webpack 4 (compat with Webpack 4 is not
guaranteed!) and Node versions < 14, package.json
retains the
module
key, which points to the ESM entry point, and the
main
key, which points to the CJS2 entry point explicitly
(using the .js file extension). For Webpack 5 and Node versions >= 14,
package.json
includes the exports
key,
which points to both entry points explicitly.
Though package.json
includes
{ "type": "commonjs"}
, note that the ESM entry points are ES
module (.mjs
) files. package.json
also includes the
sideEffects
key, which is false
for optimal tree
shaking, and the types
key, which points to a TypeScript
declarations file.
Additionally, this package does not maintain shared state and so does not exhibit the dual package hazard.
Legacy Next.js Support
As of version 2.1.0
, NTARH is fully backwards compatible with Next.js going
allll the way back to next@9.0.0
when API routes were first
introduced!
If you're working with next@<9.0.6
(so: before next-server
was merged into
next
), you might need to install next-server
manually:
npm install --save-dev next-server
Usage
// ESM
import { testApiHandler } from 'next-test-api-route-handler';
// CJS
const { testApiHandler } = require('next-test-api-route-handler');
Quick start:
/* File: test/unit.test.ts */
import { testApiHandler } from 'next-test-api-route-handler';
// Import the handler under test from the pages/api directory
import endpoint, { config } from '../pages/api/your-endpoint';
import type { PageConfig } from 'next';
// Respect the Next.js config object if it's exported
const handler: typeof endpoint & { config?: PageConfig } = endpoint;
handler.config = config;
await testApiHandler({
handler,
requestPatcher: (req) => (req.headers = { key: process.env.SPECIAL_TOKEN }),
test: async ({ fetch }) => {
const res = await fetch({ method: 'POST', body: 'data' });
console.log(await res.json()); // ◄ outputs: "{hello: 'world'}"
}
});
// NTARH also supports typed response data via TypeScript generics:
await testApiHandler<{ hello: string }>({
// The next line would cause TypeScript to complain:
// handler: (_, res) => res.status(200).send({ hello: false }),
handler: (_, res) => res.status(200).send({ hello: 'world' }),
requestPatcher: (req) => (req.headers = { key: process.env.SPECIAL_TOKEN }),
test: async ({ fetch }) => {
const res = await fetch({ method: 'POST', body: 'data' });
// The next line would cause TypeScript to complain:
// const { goodbye } = await res.json();
const { hello } = await res.json();
console.log(hello); // ◄ outputs: "world"
}
});
The interface for testApiHandler
without generics looks like this:
async function testApiHandler({
requestPatcher,
responsePatcher,
paramsPatcher,
params,
url,
handler,
test
}: {
requestPatcher?: (req: IncomingMessage) => void;
responsePatcher?: (res: ServerResponse) => void;
paramsPatcher?: (params: Record<string, unknown>) => void;
params?: Record<string, unknown>;
url?: string;
handler: (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
test: ({
fetch: (init?: RequestInit) => ReturnType<typeof fetch>;
}) => Promise<void>;
});
🚩 requestPatcher
is a function that receives an IncomingMessage. Use
this function to modify the request before it's injected into Next.js's
resolver. To just set the request url, e.g.
requestPatcher: (req) => (req.url = '/my-url?some=query')
, use the url
shorthand, e.g. url: '/my-url?some=query'
.
More often than not, manually setting the request url is unnecessary. Only set the url if your handler expects it or you want to use automatic query string parsing instead of
params
/paramsPatcher
.
🚩 responsePatcher
is a function that receives a ServerResponse. Use this
function to modify the response before it's injected into Next.js's resolver.
🚩 paramsPatcher
is a function that receives an object representing
"processed" dynamic routes, e.g. testing a handler that expects /api/user/:id
requires paramPatcher: (params) => (params.id = 'test-id')
. Route parameters
can also be passed using the params
shorthand, e.g.
params: { id: 'test-id', ... }
. If both paramsPatcher
and the params
shorthand are used, paramsPatcher
will receive an object like
{ ...queryStringURLParams, ...params }
.
Route parameters should not be confused with query string parameters, which are automatically parsed out from the url and added to the params object before
paramsPatcher
is evaluated.
🚩 handler
is the actual route handler under test (usually imported from
pages/api/*
). It should be an async function that accepts NextApiRequest
and NextApiResponse objects as its two parameters.
🚩 test
is a function that returns a promise (or async) where test assertions
can be run. This function receives one parameter: fetch
, which is a simple
unfetch instance (note that the url parameter, i.e. the first parameter
in fetch(...)
, is omitted). Use this to send HTTP requests to the
handler under test.
Real-World Examples
Testing Next.js's Official Apollo Example @ pages/api/graphql
You can easily run this example 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. Requires
curl
,node
, andgit
.
git clone --depth=1 https://github.com/vercel/next.js /tmp/ntarh-test
cd /tmp/ntarh-test/examples/api-routes-apollo-server-and-client
npm install
npm install next-test-api-route-handler jest babel-jest @babel/core @babel/preset-env graphql-tools
# You could test with an older version of Next.js if you want, e.g.:
# npm install next@9.0.6 --force
# Or even older:
# npm install next@9.0.0 next-server --force
echo 'module.exports={"presets":["next/babel"]};' > babel.config.js
mkdir test
curl -o test/my.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw
npx jest
The above script will clone the Next.js repository, install NTARH and configure dependencies, download the following script, and run it with jest.
Note that passing the route configuration object (imported below as
config
) through to NTARH and settingrequest.url
to the proper value is crucial when testing Apollo endpoints!
/* File: examples/api-routes-apollo-server-and-client/tests/my.test.js */
import { testApiHandler } from 'next-test-api-route-handler';
// Import the handler under test from the pages/api directory
import handler, { config } from '../pages/api/graphql';
// Respect the Next.js config object if it's exported
handler.config = config;
describe('my-test', () => {
it('does what I want 1', async () => {
expect.hasAssertions();
await testApiHandler({
handler,
url: '/api/graphql', // Set the request url to the path graphql expects
test: async ({ fetch }) => {
const query = `query ViewerQuery {
viewer {
id
name
status
}
}`;
const res = await fetch({
method: 'POST',
headers: {
'content-type': 'application/json' // Must use correct content type
},
body: JSON.stringify({
query
})
});
expect(await res.json()).toStrictEqual({
data: { viewer: { id: '1', name: 'John Smith', status: 'cached' } }
});
}
});
});
it('does what I want 2', async () => {
// Exactly the same as the above...
});
it('does what I want 3', async () => {
// Exactly the same as the above...
});
});
Testing an Unreliable API 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?
/* File: test/unit.test.ts */
// Import the handler under test from the pages/api directory
import endpoint, { config } from '../pages/api/unreliable';
import { testApiHandler } from 'next-test-api-route-handler';
import type { PageConfig } from 'next';
const expectedReqPerError = 10;
// Respect the Next.js config object if it's exported
const handler: typeof endpoint & { config?: PageConfig } = endpoint;
handler.config = config;
it('injects contrived errors at the required rate', async () => {
expect.hasAssertions();
// Signal to the endpoint (which is configurable) that there should be 1
// error among every 10 requests
process.env.REQUESTS_PER_CONTRIVED_ERROR = expectedReqPerError.toString();
await testApiHandler({
handler,
test: async ({ fetch }) => {
// Run 20 requests with REQUESTS_PER_CONTRIVED_ERROR = '10' and
// record the results
const results1 = await Promise.all(
[
...Array.from({ length: expectedReqPerError - 1 }).map(() =>
fetch({ method: 'GET' })
),
fetch({ method: 'POST' }),
...Array.from({ length: expectedReqPerError - 1 }).map(() =>
fetch({ method: 'PUT' })
),
fetch({ method: 'DELETE' })
].map((p) => p.then((r) => r.status))
);
process.env.REQUESTS_PER_CONTRIVED_ERROR = '0';
// Run 10 requests with REQUESTS_PER_CONTRIVED_ERROR = '0' and record the
// results
const results2 = await Promise.all(
Array.from({ length: expectedReqPerError }).map(() =>
fetch().then((r) => r.status)
)
);
// We expect results1 to be an array with eighteen `200`s and two
// `555`s in any order
//
// https://github.com/jest-community/jest-extended#toincludesamemembersmembers
// because responses could be received out of order
expect(results1).toIncludeSameMembers([
...Array.from({ length: expectedReqPerError - 1 }).map(() => 200),
555,
...Array.from({ length: expectedReqPerError - 1 }).map(() => 200),
555
]);
// We expect results2 to be an array with ten `200`s
expect(results2).toStrictEqual([
...Array.from({ length: expectedReqPerError }).map(() => 200)
]);
}
});
});
Testing a Flight Search API 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?
/* File: test/unit.test.ts */
import endpoint, { config } from '../pages/api/v3/flights/search';
import { testApiHandler } from 'next-test-api-route-handler';
import { DUMMY_API_KEY as KEY, getFlightData, RESULT_SIZE } from '../backend';
import type { PageConfig } from 'next';
// Respect the Next.js config object if it's exported
const handler: typeof endpoint & { config?: PageConfig } = endpoint;
handler.config = config;
it('returns expected public flights with respect to match', async () => {
expect.hasAssertions();
// Get the flight data currently in the test database
const expectedFlights = getFlightData();
// Take any JSON object and stringify it into a URL-ready string
const encode = (o: Record<string, unknown>) =>
encodeURIComponent(JSON.stringify(o));
// This function will return in order the URIs we're interested in testing
// against our handler. Query strings are parsed by NTARH automatically.
//
// DO NOTE: setting the request url manually using encode(), while valid, is
// unnecessary here; we could have used `params` or `paramPatcher` to do this
// more easily without explicitly setting a dummy request url.
//
// Example URI for `https://site.io/path?param=yes` would be `/path?param=yes`
const genUrl = (function* () {
// For example, the first should match all the flights from Spirit airlines!
yield `/?match=${encode({ airline: 'Spirit' })}`;
yield `/?match=${encode({ type: 'departure' })}`;
yield `/?match=${encode({ landingAt: 'F1A' })}`;
yield `/?match=${encode({ seatPrice: 500 })}`;
yield `/?match=${encode({ seatPrice: { $gt: 500 } })}`;
yield `/?match=${encode({ seatPrice: { $gte: 500 } })}`;
yield `/?match=${encode({ seatPrice: { $lt: 500 } })}`;
yield `/?match=${encode({ seatPrice: { $lte: 500 } })}`;
})();
await testApiHandler({
// Patch the request object to include our dummy URI
requestPatcher: (req) => {
req.url = genUrl.next().value || undefined;
// Could have done this instead of `fetch({ headers: { KEY }})` below:
// req.headers = { KEY };
},
handler,
test: async ({ fetch }) => {
// 8 URLS from genUrl means 8 calls to fetch:
const responses = await Promise.all(
Array.from({ length: 8 }).map(() =>
fetch({ headers: { KEY } }).then(async (r) => [
r.status,
await r.json()
])
)
);
// We expect all of the responses to be 200
expect(responses.some(([status]) => status != 200)).toBe(false);
// We expect the array of flights returned to match our
// expectations given we already know what dummy data will be
// returned:
// https://github.com/jest-community/jest-extended#toincludesamemembersmembers
// because responses could be received out of order
expect(responses.map(([, r]) => r.flights)).toIncludeSameMembers([
expectedFlights
.filter((f) => f.airline == 'Spirit')
.slice(0, RESULT_SIZE),
expectedFlights
.filter((f) => f.type == 'departure')
.slice(0, RESULT_SIZE),
expectedFlights
.filter((f) => f.landingAt == 'F1A')
.slice(0, RESULT_SIZE),
expectedFlights.filter((f) => f.seatPrice == 500).slice(0, RESULT_SIZE),
expectedFlights.filter((f) => f.seatPrice > 500).slice(0, RESULT_SIZE),
expectedFlights.filter((f) => f.seatPrice >= 500).slice(0, RESULT_SIZE),
expectedFlights.filter((f) => f.seatPrice < 500).slice(0, RESULT_SIZE),
expectedFlights.filter((f) => f.seatPrice <= 500).slice(0, RESULT_SIZE)
]);
}
});
// We expect these two to fail with 400 errors
await testApiHandler({
handler,
url: `/?match=${encode({ ffms: { $eq: 500 } })}`,
test: async ({ fetch }) =>
expect((await fetch({ headers: { KEY } })).status).toBe(400)
});
await testApiHandler({
handler,
url: `/?match=${encode({ bad: 500 })}`,
test: async ({ fetch }) =>
expect((await fetch({ headers: { KEY } })).status).toBe(400)
});
});
Check out the tests for more examples.
Documentation
Further documentation can be found under docs/
.
License
Contributing and Support
New issues and pull requests are always welcome and greatly appreciated! 🤩 Just as well, you can star 🌟 this project to let me know you found it useful! ✊🏿 Thank you!
See CONTRIBUTING.md and SUPPORT.md for more information.