React / 系统课时
测试 Express 接口
测试 Express 接口
本课用 Vitest 与 Supertest 为一个 Express 用户创建接口编写自动化测试,覆盖正常路由、参数校验、Bearer 认证和统一异常响应。完成后,你将得到一组可重复运行、无需真实监听端口的接口测试。
学习目标
- 使用 Supertest 直接调用 Express 应用并断言状态码与响应体
- 为参数错误、认证失败和服务端异常设计独立测试
- 理解测试应用与启动服务器分离的原因
明确接口测试边界
接口测试关注从 HTTP 请求进入应用,到中间件、路由处理器和错误处理中间件返回响应的完整链路。它不应依赖浏览器,也不必真的启动一个网络端口,因此执行速度比端到端测试更快。

本课测试的接口是 POST /api/users。请求必须携带 Authorization: Bearer test-token,请求体中的 name 至少两个字符,age 必须是不小于 18 的数字。
| 场景 | 预期状态码 | 核心断言 |
|---|---|---|
| 合法请求 | 201 | 返回新用户数据 |
| 参数非法 | 400 | 返回 VALIDATION_ERROR |
| 缺少令牌 | 401 | 返回 UNAUTHORIZED |
| 路由抛错 | 500 | 返回统一异常结构 |
创建可测试的 Express 应用
先安装测试依赖。下面的命令假设项目已经配置 TypeScript 和 npm。
bash
npm install express supertest
npm install -D vitest typescript @types/express @types/supertest预期结果
text
added <N> packages
found 0 vulnerabilities<N> 会随现有依赖和 npm 版本变化。接着创建 src/app.ts,只导出应用对象,不在文件中调用 listen。
ts
import express, { type NextFunction, type Request, type Response } from "express";
export const app = express();
app.use(express.json());
function requireAuth(req: Request, res: Response, next: NextFunction) {
if (req.header("authorization") !== "Bearer test-token") {
return res.status(401).json({
code: "UNAUTHORIZED",
message: "缺少或无效令牌",
});
}
next();
}
app.post("/api/users", requireAuth, (req, res, next) => {
const { name, age } = req.body as { name?: unknown; age?: unknown };
if (
typeof name !== "string" ||
name.trim().length < 2 ||
typeof age !== "number" ||
age < 18
) {
return res.status(400).json({
code: "VALIDATION_ERROR",
message: "name 至少两个字符,age 必须不小于 18",
});
}
// 用固定输入触发异常,便于稳定验证错误处理中间件。
if (name === "error") {
return next(new Error("模拟数据库异常"));
}
return res.status(201).json({
id: "u-1001",
name: name.trim(),
age,
});
});
app.use(
(error: Error, _req: Request, res: Response, _next: NextFunction) => {
return res.status(500).json({
code: "INTERNAL_ERROR",
message: error.message,
});
},
);该文件的生效行为是:请求先经过 JSON 解析与认证,再进入参数校验和业务处理;未捕获异常统一交给最后的错误处理中间件。测试环境可以直接导入 app,生产入口再单独调用 app.listen(<PORT>)。
编写四类接口断言
创建 test/users.test.ts。每个测试只验证一个结果,失败时更容易定位是认证、校验、路由还是异常处理出了问题。
ts
import request from "supertest";
import { describe, expect, it } from "vitest";
import { app } from "../src/app";
describe("POST /api/users", () => {
it("合法请求返回 201", async () => {
const response = await request(app)
.post("/api/users")
.set("Authorization", "Bearer test-token")
.send({ name: "Alice", age: 20 });
expect(response.status).toBe(201);
expect(response.body).toEqual({
id: "u-1001",
name: "Alice",
age: 20,
});
});
it("参数非法返回 400", async () => {
const response = await request(app)
.post("/api/users")
.set("Authorization", "Bearer test-token")
.send({ name: "A", age: 16 });
expect(response.status).toBe(400);
expect(response.body.code).toBe("VALIDATION_ERROR");
});
it("缺少令牌返回 401", async () => {
const response = await request(app)
.post("/api/users")
.send({ name: "Alice", age: 20 });
expect(response.status).toBe(401);
expect(response.body.code).toBe("UNAUTHORIZED");
});
it("路由异常返回 500", async () => {
const response = await request(app)
.post("/api/users")
.set("Authorization", "Bearer test-token")
.send({ name: "error", age: 20 });
expect(response.status).toBe(500);
expect(response.body).toEqual({
code: "INTERNAL_ERROR",
message: "模拟数据库异常",
});
});
});运行并判断结果
执行全部测试:
bash
npx vitest run预期输出
text
✓ test/users.test.ts (4 tests)
Test Files 1 passed (1)
Tests 4 passed (4)具体耗时可能不同,但测试文件和四个测试都应通过。若出现连接端口失败,通常是测试导入了启动服务器的文件;应把 app 与 listen 拆开。若 500 用例返回了 HTML,说明错误处理中间件没有放在所有路由之后,或其中缺少四个参数。
按自己的节奏,确认真正理解。