Unit testing Next.js API routes

Unit testing Next.js API routes is possible with jest and straightforward once you see an example.

Straight from the Next.js docs, API route handlers look like this:

// pages/api/user.js
export default (req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'application/json');
  res.end(JSON.stringify({ name: 'John Doe' }));
};

Hey, that's just a function! Those are easy to test!

I hear you, internet friend. It is a function indeed and functions are easy to test, but this has a bit more going on than just adding 2 numbers.

Example API route#

This blog is built with Next.js so I added this /api/animal/[animal] route, which accepts a dynamic [animal] parameter at the end and returns a JSON object with a dynamic message.

// /pages/api/[animal].js
export default function handleAnimal(req, res) {
  const {
    query: { animal },
  } = req;

  res.statusCode = 200;
  res.setHeader('Content-Type', 'application/json');
  res.end(JSON.stringify({ message: `Your favorite animal is ${animal}` }));
}

The unit test#

The key here is the createMocks utility provided by node-mocks-http. It creates mock req and res objects that you can later interrogate after your async route handler executes.

// __tests__/animal.test.js
// 🚨 Remember to keep your `*.test.js` files out of your `/pages` directory!
import { createMocks } from 'node-mocks-http';
import handleAnimal from '../pages/api/animal/[animal]';

describe('/api/[animal]', () => {
  test('returns a message with the specified animal', async () => {
    const { req, res } = createMocks({
      method: 'GET',
      query: {
        animal: 'dog',
      },
    });

    await handleAnimal(req, res);

    expect(res._getStatusCode()).toBe(200);
    expect(JSON.parse(res._getData())).toEqual(
      expect.objectContaining({
        message: 'Your favorite animal is dog',
      }),
    );
  });
});

That's it! Know of a better way? Find me on Twitter and share!

Table of Contents
Example API route
The unit test
Building an MVP?

I partner with founders to turn your vision into a product that ships.

Strategy, architecture, and hands-on development from someone who has led 50+ product launches.

Let's talk about your MVP