api-testing

API 测试（Playwright + REST Assured）

全面的 API 测试技能，涵盖 Playwright TypeScript（request fixture、Supertest、Zod）和 Java（REST Assured、AssertJ、JSON Schema Validator）。

何时使用此技能

• 为 REST 或 GraphQL 端点创建 API 测试
• 验证请求/响应架构（Zod、JSON Schema）
• 测试身份验证流程（OAuth2、JWT、API 密钥、Bearer 令牌）
• 验证错误处理（400、401、403、404、409、422、500）
• 测试分页、筛选、排序的边界情况
• 验证 PUT/DELETE 操作的幂等性
• 测试服务之间的契约
• 验证速率限制

不要用于

• 由浏览器驱动的 UI 流程（Playwright 测试规范请使用 playwright-e2e-testing，Selenium 请使用 webapp-selenium-testing）
• 实时交互式浏览器会话或快照（请使用 playwright-cli）
• 视觉/布局回归（不在范围内 — 不涉及 DOM）
• 必须通过真实浏览器跨页面执行的端到端流程

前置条件

技术栈	要求
TypeScript	Node.js 18+、@playwright/test 或 supertest、zod
Java	Java 21+、REST Assured 5.x、AssertJ、Jackson、json-schema-validator

核心原则

1. 验证每个响应的架构 — 绝不信任未经验证的响应
2. 测试所有 HTTP 状态码 — 成功路径和错误状态都要测试
3. 身份验证测试是必须的 — 验证受保护端点是否返回 401/403
4. 数据驱动 — 使用有效、无效、边界和空值进行测试
5. 尽可能保持无状态 — 每项测试都应清理数据或使用唯一数据

快速参考 — Playwright

import { test, expect } from "@playwright/test";

test("GET /api/users returns 200 with valid schema", async ({ request }) => {
  const response = await request.get("/api/users");
  expect(response.ok()).toBeTruthy();
  const body = await response.json();
  expect(body).toMatchObject({ data: expect.any(Array) });
});

快速参考 — REST Assured

import static io.restassured.RestAssured.*;
import static org.hamcrest.Matchers.*;

import java.util.List;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

@Test
@DisplayName("GET /api/users returns 200 with valid schema")
void getUsers() {
    String token = "test-token";

    given()
        .header("Authorization", "Bearer " + token)
    .when()
        .get("/api/users")
    .then()
        .statusCode(200)
        .body("data", is(instanceOf(List.class)))
        .body("data.size()", greaterThan(0));
}

---

危险信号

如果生成的 API 测试中出现以下任何情况，请停下来重新考虑：

• 只断言状态码，不验证响应正文/架构 — 未经验证的响应会掩盖契约偏差。
• 在测试文件中提交硬编码的密钥/令牌 — 应从环境变量或密钥管理器中读取。
• 测试共享可变状态且没有清理 — 容易不稳定，且依赖执行顺序。
• 跳过身份验证测试（没有对受保护端点断言 401/403）— 存在安全回归风险。
• 未覆盖错误状态（只有成功路径的 200 响应）— 未测试错误处理。

---

参考资料

文档	内容
REST API 模式	CRUD、分页、筛选、错误模式
Playwright API 测试	Request fixture、Supertest、TypeScript 模式
REST Assured 测试	REST Assured、AssertJ、Java 模式
架构验证	Zod（TS）、JSON Schema（Java）、严格与宽松
契约测试	请求/响应契约、幂等性、版本管理

模板

• Playwright API 测试规范 — API 测试入门文件
• REST Assured 测试 — Java 测试类入门文件

脚本

• API 健康检查 — 验证 API 端点是否能正确响应

故障排除

问题	解决方案
经过身份验证的端点返回 401	确认令牌仍然有效；检查是否过期；重新进行身份验证
API 测试不稳定	添加重试逻辑；检查是否触发速率限制；使用唯一的测试数据
架构验证过于严格	对灵活字段使用 .passthrough()（Zod）或 additionalProperties: true
慢速端点超时	增加请求选项中的 timeout；检查服务负载

---

验证

• 已设置架构验证 — 每个响应都根据架构（Zod 或 JSON Schema）进行验证
• 已测试身份验证 — 受保护的端点在没有有效凭据时返回 401
• 已验证幂等性 — 多次调用 PUT/DELETE 会产生相同结果
• 已覆盖边缘情况 — 空载荷、无效类型、边界值、SQL 注入尝试