Node.js / 系统课时
编写接口测试
编写接口测试
接口测试从真实 HTTP 边界发起请求,验证状态码、响应头和响应体是否符合约定,同时确认异常输入能得到稳定的错误响应。下面用 Node.js 内置 HTTP 服务和测试运行器启动一个临时端口,完成成功、校验失败与资源清理三个关键环节。
学习目标
- 在测试进程中启动 HTTP 应用,并使用系统分配的临时端口避免端口冲突。
- 同时断言状态码、响应头和 JSON 响应体,而不是只检查请求是否成功。
- 在测试结束后关闭服务器,避免测试进程因未释放句柄而挂起。
启动真实 HTTP 边界
接口测试不要固定写死 3000 端口,因为并行测试或本地开发服务可能已经占用它。让 server.listen(0, '127.0.0.1') 交给操作系统分配空闲端口,再通过 server.address().port 读取实际值,测试之间更不容易互相干扰。

这一流程里必须同时控制启动、请求和清理三个阶段。若测试只发送请求却不关闭服务器,断言虽然可能全部通过,Node.js 进程仍可能因为监听句柄未释放而不能正常退出。
构造最小测试应用
将下面内容保存为 app.mjs。应用提供健康检查和创建用户两个接口;请求体不是合法 JSON 时返回 INVALID_JSON,缺少 name 时返回 INVALID_ARGUMENT,正常创建返回 201。
import { createServer } from 'node:http';
function sendJson(res, statusCode, body) {
// 所有分支统一序列化 JSON,测试可以固定响应格式。
const payload = JSON.stringify(body);
res.writeHead(statusCode, {
'content-type': 'application/json; charset=utf-8',
'content-length': Buffer.byteLength(payload)
});
res.end(payload);
}
export function createApp() {
return createServer(async (req, res) => {
if (req.method === 'GET' && req.url === '/health') {
return sendJson(res, 200, { status: 'ok' });
}
if (req.method === 'POST' && req.url === '/users') {
// 直接读取请求体,示例只关注 HTTP 契约而不引入框架依赖。
let raw = '';
for await (const chunk of req) raw += chunk;
let body;
try {
body = JSON.parse(raw || '{}');
} catch {
return sendJson(res, 400, { code: 'INVALID_JSON' });
}
// 把缺少 name 固定成客户端可观察的 400 错误契约。
if (typeof body.name !== 'string' || body.name.trim() === '') {
return sendJson(res, 400, { code: 'INVALID_ARGUMENT' });
}
return sendJson(res, 201, { id: 'u-1', name: body.name });
}
return sendJson(res, 404, { code: 'NOT_FOUND' });
});
}预期结果:保存 app.mjs 不会自行监听端口;它只导出 createApp(),测试文件负责启动与关闭服务器。
这里故意把测试数据保持最小:固定用户 ID 为 u-1,避免数据库自增值或随机 UUID 让断言变得不稳定。生产项目可以在应用工厂中注入仓库,再为接口测试换成独立测试数据库或内存实现。
验证状态码、响应体与异常场景
将下面内容保存为 app.test.mjs。示例以 Node.js 22+ 为运行基线,使用内置 fetch() 发起请求,并在顶层启动服务器;after() 钩子负责关闭监听句柄。三条测试分别覆盖健康检查、成功创建和参数缺失。
import test, { after } from 'node:test';
import assert from 'node:assert/strict';
import { createApp } from './app.mjs';
const server = createApp();
// 使用端口 0 让系统分配空闲端口,避免并行测试争抢固定端口。
await new Promise((resolve, reject) => {
server.once('error', reject);
server.listen(0, '127.0.0.1', resolve);
});
const address = server.address();
const baseUrl = `http://127.0.0.1:${address.port}`;
after(async () => {
// 无论测试是否通过,都要在测试进程结束前释放监听句柄。
await new Promise((resolve, reject) => {
server.close((error) => error ? reject(error) : resolve());
});
});
test('GET /health returns service status', async () => {
// 接口测试断言客户端真正看到的状态码、头和响应体。
const response = await fetch(`${baseUrl}/health`);
assert.strictEqual(response.status, 200);
assert.strictEqual(
response.headers.get('content-type'),
'application/json; charset=utf-8'
);
assert.deepStrictEqual(await response.json(), { status: 'ok' });
});
test('POST /users returns 201 and created user', async () => {
const response = await fetch(`${baseUrl}/users`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ name: 'Ada' })
});
assert.strictEqual(response.status, 201);
assert.deepStrictEqual(await response.json(), { id: 'u-1', name: 'Ada' });
});
test('POST /users rejects a missing name', async () => {
const response = await fetch(`${baseUrl}/users`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({})
});
assert.strictEqual(response.status, 400);
assert.deepStrictEqual(await response.json(), { code: 'INVALID_ARGUMENT' });
});预期结果:测试文件会启动一个临时 HTTP 服务,定义 3 条请求测试,并在 after() 中关闭服务;真正执行前不会固定占用 3000 等端口。
接口测试应优先断言契约而不是内部实现。上例没有检查“调用了哪个函数”,而是检查客户端真正能观察到的 200、201、400、content-type 和 JSON 字段,这样重构路由内部结构时测试不会无谓失效。
运行测试并检查资源释放
在两个文件所在目录执行。示例按 Node.js 22+ 编写;若项目运行时较旧,应改用项目已经采用的 HTTP 客户端,而不要在测试里依赖不存在的全局 API。
node --test --test-reporter=tap app.test.mjs预期输出(关键行;端口与耗时属于动态值,不要求固定):
TAP version 13
# Subtest: GET /health returns service status
ok 1 - GET /health returns service status
# Subtest: POST /users returns 201 and created user
ok 2 - POST /users returns 201 and created user
# Subtest: POST /users rejects a missing name
ok 3 - POST /users rejects a missing name
1..3
# tests 3
# pass 3
# fail 0命令结束后应立即回到 shell 提示符。如果断言已经通过但进程仍不退出,先检查 server.close()、数据库连接池、定时器和消息队列客户端是否在清理钩子中释放;接口测试是否可重复执行,不只取决于断言,还取决于每次运行后是否留下外部状态。