Testing API routes in NextJS - Step-by-Step Execution

Concept Flow - Testing API routes

Write API Route Handler

↓

Write Test Case

↓

Run Test Runner

↓

Send Mock Request to API

↓

API Handler Processes Request

↓

Return Response

↓

Test Runner Checks Response

↓

Pass or Fail Test

↓

End

This flow shows how writing a test sends a fake request to the API route, which processes it and returns a response that the test checks.

Execution Sample

NextJS

import handler from './api/hello';
import { createMocks } from 'node-mocks-http';

test('GET /api/hello returns 200 and message', async () => {
  const { req, res } = createMocks({ method: 'GET' });
  await handler(req, res);
  expect(res._getStatusCode()).toBe(200);
  expect(res._getData()).toBe('Hello World');
});

This test sends a fake GET request to the /api/hello route and checks if it returns status 200 and the message 'Hello World'.

Execution Table

Step	Action	Request Method	API Handler Response Status	API Handler Response Body	Test Assertion
1	Create mock GET request and response objects	GET	N/A	N/A	N/A
2	Call API handler with mock request and response	GET	200	'Hello World'	N/A
3	Check response status code	GET	200	'Hello World'	Pass if status is 200
4	Check response body content	GET	200	'Hello World'	Pass if body is 'Hello World'
5	Test ends	N/A	N/A	N/A	Test passes if all assertions pass

💡 Test ends after all assertions pass or fail

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
req.method	undefined	GET	GET	GET	GET
res.statusCode	undefined	undefined	200	200	200
res.body	undefined	undefined	'Hello World'	'Hello World'	'Hello World'

Key Moments - 3 Insights

Why do we use mock request and response objects instead of real HTTP calls?

Using mock objects lets tests run fast and isolated without needing a real server or network, as shown in Step 1 of the execution_table.

How does the test know if the API route works correctly?

The test checks the response status and body after the handler runs (Steps 3 and 4), confirming the API behaves as expected.

What happens if the API handler returns a different status or message?

The test assertions in Steps 3 and 4 will fail, causing the test to fail and alerting you to the problem.

Visual Quiz - 3 Questions

Look at the execution_table, what is the response status code after Step 2?

A 500

B 404

C 200

D undefined

💡 Hint

Check the 'API Handler Response Status' column at Step 2 in the execution_table.

At which step does the test check the response body content?

A Step 4

B Step 2

C Step 1

D Step 5

💡 Hint

Look at the 'Test Assertion' column in the execution_table for when the body is checked.

If the mock request method was changed to POST, what would likely happen in the test?

A The test would still pass without changes

B The API handler might return a different status, causing test failure

C The response body would be 'Hello World' anyway

D The test runner would crash

💡 Hint

Consider how the API handler processes different methods and how assertions depend on expected responses.

Concept Snapshot

Testing API routes in Next.js:
- Use mock request and response objects to simulate HTTP calls.
- Call the API handler function directly with mocks.
- Check response status and body with assertions.
- Tests run fast without a real server.
- Use libraries like node-mocks-http for mocks.

Full Transcript

Testing API routes in Next.js involves writing test cases that simulate HTTP requests using mock request and response objects. The test calls the API route handler function directly with these mocks. The handler processes the request and sets the response status and body. The test then checks these response values with assertions to confirm the API behaves as expected. This approach avoids real network calls, making tests fast and reliable. Common tools include node-mocks-http to create mock objects. The test flow starts by creating mocks, calling the handler, then checking the response, and finally passing or failing the test based on assertions.