React / 系统课时

测试 Express 接口

测试 Express 接口

本课用 Vitest 与 Supertest 为一个 Express 用户创建接口编写自动化测试,覆盖正常路由、参数校验、Bearer 认证和统一异常响应。完成后,你将得到一组可重复运行、无需真实监听端口的接口测试。

学习目标

  • 使用 Supertest 直接调用 Express 应用并断言状态码与响应体
  • 为参数错误、认证失败和服务端异常设计独立测试
  • 理解测试应用与启动服务器分离的原因

明确接口测试边界

接口测试关注从 HTTP 请求进入应用,到中间件、路由处理器和错误处理中间件返回响应的完整链路。它不应依赖浏览器,也不必真的启动一个网络端口,因此执行速度比端到端测试更快。

Express 接口测试调用链

本课测试的接口是 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,说明错误处理中间件没有放在所有路由之后,或其中缺少四个参数。

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

目录与阅读设置

阅读设置

17

记录一个想法

测试 Express 接口

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

登录哪都通