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。

js
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() 钩子负责关闭监听句柄。三条测试分别覆盖健康检查、成功创建和参数缺失。

js
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。

bash
node --test --test-reporter=tap app.test.mjs

预期输出(关键行;端口与耗时属于动态值,不要求固定):

text
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()、数据库连接池、定时器和消息队列客户端是否在清理钩子中释放;接口测试是否可重复执行,不只取决于断言,还取决于每次运行后是否留下外部状态。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编写接口测试

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通