_NextJS's conventions are not TDD-friendly, but with some work and a little structure we can enjoy a smooth red-green ride._

Let's say we need a NextJS API route that gives us dictionary definitions. The route handler should validate the request, query a 3rd-party dictionary API, extract desired data from the response, and relay it to the front end.

We want a fast feedback loop and low chances of future regressions, so we decide to develop it test-first.

## 0/4 Prep

Install the [node-mocks-http](https://www.npmjs.com/package/node-mocks-http) package.

We'll assume a working `jest` setup. Start it in watch mode with:

```sh
npx jest --watch
# or
pnpm jest --watch
```

## 1/4 Basic test

Create the simplest possible test in `src/server/api/definitions.test.ts`:

```ts
import { NextApiRequest, NextApiResponse } from "next";
import {
 createMocks,
 createRequest,
 createResponse,
} from "node-mocks-http";
import { createHandler } from "./definitions";
type ApiRequest = NextApiRequest &
 ReturnType<typeof createRequest>;
type ApiResponse = NextApiResponse &
 ReturnType<typeof createResponse>;

describe("/api/definitions", () => {
 const getDeps = () => {
 return {
 fetch: jest.fn(),
 env: {
 DICTIONARY_API_KEY: "abcdef123456",
 },
 };
 };

 test("responds with error if no query was provided", async () => {
 const deps = getDeps();
 const { req, res } = createMocks<
 ApiRequest,
 ApiResponse
 >({
 method: "GET",
 url: "/api/definitions",
 });

 const handler = createHandler(deps);
 await handler(req, res);

 expect(res.statusCode).toBe(400);
 });
});
```

### Things to note

1. `node-mocks-http` allows to execute handlers in the test environment without having to launch and control a server as part of the test. Running a server would increase accuracy (we have no assurance that the mocking library 100% matches the server's request processing) but decrease simplicity (we'd need to tightly manage the server lifecycle, ports, and state to ensure tests stay self-contained), control (harder to test for error conditions), and speed (the overhead of launching servers might slow down large test suites). We especially want test to run fast so that our attention doesn't have a chance to drop, se we accept the trade off in favour of speed and use a mocking library.

2. Instead of expecting `./definitions` to export a handler _function_, we expect it to export a handler _factory_:

```ts
import { createHandler } from "./definitions";
```

We prefer a factory to a function because it allows configuration to be provided at the call site instead of being statically defined in the `./definitions` module. This lets us configure the handler depending on the environment (dev/test/prod) by just passing a parameter object instead instead of doing `jest.mock` acrobatics.

Also note that we begin to state expectations long before the first call to `test()`.

3. The configuration we pass to the handler factory consists of external dependencies:

```ts
const getDeps = () => {
 return {
 fetch: jest.fn(),
 env: {
 DICTIONARY_API_KEY: "abcdef123456",
 },
 };
};
```

_External_ can be thought of as "anything the function doesn't know by looking at the arguments".

To justify why we pass `env` and even `fetch` as external dependencies, let's look at the handler function signature:

```ts
export declare type NextApiHandler<T = any> = (
 req: NextApiRequest,
 res: NextApiResponse<T>,
) => unknown | Promise<unknown>;
```

- Can the handler know the content of `process.env` by just looking at `req` or `res`? No → pass `env` as part of the configuration.
- Can the handler know the content of 3rd-party APIs by just looking at `req` or `res`? No → pass a `fetch` implementation to the factory as configuration.

If the 3rd-party dictionary service provided an SDK (or if we were willing to write a minimal one ourselves), the above could become:

```ts
const getDeps = () => {
 return {
 dictionaryClient: { lookup: jest.fn() },
 };
};
```

4. We don't place files in the usual `src/pages/api` folder so we don't need to worry about Next misinterpreting test files as handlers, nor we need to modify `next.config.js` to prevent such misinterpretation.

(Eventually we'll place just a minimal file there to configure the handler for dev/prod and activate the route.)

## 2/4 Basic implementation

Write the simplest implementation of `src/server/api/definitions.ts` capable of making the test pass:

```ts
import crossFetch from "cross-fetch";
import { NextApiHandler } from "next";

export const createHandler =
 ({
 fetch,
 env,
 }: {
 fetch: typeof crossFetch;
 env: {
 DICTIONARY_API_KEY: string;
 };
 }): NextApiHandler =>
 async (req, res) => {
 if (!("q" in req.query)) {
 res.status(400).end();
 return;
 }
 };
```

## 3/4 Iterate

From here on it's the usual TDD flow:

1. write another test;
2. write the code that makes it pass;
3. occasionally stop and improve other qualities of the code (understandability, performance, ...) while using tests to confirm that nothing broke.

For example, work on the invocaiton of the 3rd-party API, we could start by writing the following test:

```ts
test("invokes the dictionary API", async () => {
 // Setup
 const deps = getDeps();
 deps.fetch.mockResolvedValue({
 async json() {
 return {
 word: "cat",
 definition: "A mammal popular in memes",
 usage: { queriesLeft: 100 },
 };
 },
 });
 const { req, res } = createMocks<
 ApiRequest,
 ApiResponse
 >({
 method: "GET",
 url: "/api/definitions",
 query: { q: "cat" },
 });
 const handler = createHandler(deps);

 // Execution
 await handler(req, res);

 // Assertion
 expect(res.statusCode).toBe(200);
 expect(res._getJSONData()).toEqual({
 definition: "A mammal popular in memes",
 });
 expect(deps.fetch).toHaveBeenCalledWith(
 "https://dict.example.com/api",
 {
 headers: { "x-api-key": "abcdef123456" },
 },
 );
});
```

And the following implementation:

```ts
import crossFetch from "cross-fetch";
import { NextApiHandler } from "next";

export const createHandler =
 ({
 fetch,
 env,
 }: {
 fetch: typeof crossFetch;
 env: {
 DICTIONARY_API_KEY: string;
 };
 }): NextApiHandler =>
 async (req, res) => {
 if (!("q" in req.query)) {
 res.status(400).end();
 return;
 }

 const dictRes = await fetch(
 "https://dict.example.com/api",
 {
 headers: {
 "x-api-key": env.DICTIONARY_API_KEY,
 },
 },
 );
 const data = await dictRes.json();

 res.json({ definition: data.definition });
 };
```

## 4/4 Make the handler available to Next

Create `src/pages/api/definitions.ts`:

```ts
import crossFetch from "cross-fetch";
import { createHandler } from "src/server/api/definitions";

const handler: NextApiHandler = async (req, res) => {
 const { DICTIONARY_API_KEY } = process.env;

 return createHandler({
 fetch: crossFetch,
 env: { DICTIONARY_API_KEY },
 })(req, res);
};

export default handler;
```

### Things to note

1. We configure the handler for production and development environments.
2. We could have written a shorthand `export default (req, res) => { return createHandler... }` but TypeScript doesn't (at least at the time of writing) allow typing default exports, so we go for the extra variable.
3. There's no real need to make the handler async here, but, in some cases, a dependency of the handler might have to be initialized asynchronously (e.g. `const db = async createDbConnection()`).

## 5/4 What next

If you'd like me to cover what's left for a production-grade API route handler (validation, authorization, error handling, ...), let me know via [mail](mailto:hyperstruct@gmail.com?subject=Hello) or [twitter](https://twitter.com/MaxIsBuilding).

If you'd like to read more about the why's of TDD, check out Kent Becks' classic [Aim, Fire](https://users.csc.calpoly.edu/~djanzen/setopics/testing/IEEESoftwareBeck.pdf) or [some of my own notes](https://massimilianomirra.com/notes/cafe-tech-chat-tdd-and-vs-testing).

MM

Tagged “nextjs”