api-testing

使用 Postman 和 Bruno 进行基于工具的 API 测试的专家级技能。涵盖集合组织、环境管理、测试脚本编写、响应验证和 CI/CD 集成。

此技能可补充 testing-skill（基于代码的测试）和 api-design-skill（API 结构）。当你需要使用专用工具测试现有 API，而不是编写程序化测试时，请使用此技能。

关键区别：

• testing-skill：基于代码的测试（supertest、MSW、pytest requests）
• api-testing-skill：基于工具的测试（Postman、Bruno 集合）
• api-design-skill：如何设计 API（结构、约定）

<quick_start> Postman 快速测试：

// Tests tab in Postman
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response has user data", function () {
    const json = pm.response.json();
    pm.expect(json).to.have.property("id");
    pm.expect(json).to.have.property("email");
});

Bruno 快速测试：

// tests/get-user.bru
meta {
  name: Get User
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/api/users/{{userId}}
}

tests {
  test("should return 200", function() {
    expect(res.status).to.equal(200);
  });
}

环境设置：

{
  "baseUrl": "https://api.example.com",
  "apiKey": "test_key_xxx"
}

</quick_start>

<success_criteria> 满足以下条件时，API 测试才算成功：

• 所有端点至少有一个正常路径测试
• 已测试错误情况（4xx、5xx 响应）
• 已验证响应架构（不只是状态码）
• 所有可配置值都使用环境变量
• 按资源/域组织集合
• 已端到端测试身份验证流程
• CI 流水线在每个 PR 上运行集合
• 测试数据可复现（固定数据或动态生成） </success_criteria>

<tool_comparison>

Postman 与 Bruno 对比

特性	Postman	Bruno
存储	云端/本地	原生 Git（.bru 文件）
协作	团队同步	Git 分支
定价	免费层级 + 付费版	免费且开源
离线使用	桌面应用	完全离线
脚本编写	JavaScript	JavaScript
CI/CD	Newman CLI	Bruno CLI
架构	JSON	纯文本 .bru
最适合	团队、API 文档	Git 工作流、隐私

何时使用

选择 Postman 的情况：

• 团队需要实时协作
• API 文档是主要产出
• 前端开发需要模拟服务
• OAuth 流程复杂，且需要刷新令牌

选择 Bruno 的情况：

• 倾向于原生 Git 工作流
• 需要隐私保护/自行托管
• 测试场景较简单
• 开发者偏好类代码语法 </tool_comparison>

<collection_organization>

集合结构

文件夹层级

my-api-tests/
├── auth/
│   ├── login.bru
│   ├── refresh-token.bru
│   └── logout.bru
├── users/
│   ├── create-user.bru
│   ├── get-user.bru
│   ├── update-user.bru
│   └── delete-user.bru
├── orders/
│   ├── create-order.bru
│   ├── get-orders.bru
│   └── cancel-order.bru
├── environments/
│   ├── local.bru
│   ├── staging.bru
│   └── production.bru
└── collection.bru

命名约定

元素	约定	示例
文件夹	kebab-case，使用复数	users、auth-flows
请求	动词-名词	create-user、get-orders
变量	camelCase	{{baseUrl}}、{{authToken}}
环境	小写	local、staging、production

请求排序

对于存在依赖关系的请求，使用序号：

1. auth/login.bru          (seq: 1)
2. users/create-user.bru   (seq: 2) - needs auth token
3. users/get-user.bru      (seq: 3) - uses created user ID

</collection_organization>

<test_patterns>

测试断言模式

断言类型	检查内容	示例
状态码	200、201、400、401、404	pm.response.to.have.status(200)
响应正文	必需字段、类型、模式	pm.expect(json).to.have.property("id")
响应时间	低于阈值	pm.expect(pm.response.responseTime).to.be.below(500)
标头	Content-Type、X-Request-Id	pm.response.to.have.header("Content-Type")
JSON 架构	完整架构验证	pm.response.to.have.jsonSchema(schema)

完整的断言模式及 Postman 和 Bruno 示例，请参阅 reference/test-design.md。 </test_patterns>

<environment_management>

环境管理

**变量作用域（Postman）：**全局 → 集合 → 环境 → 数据 → 本地（优先级最高）。

使用环境文件为每个环境（local/staging/production）配置 baseUrl、apiKey。通过保存响应值（pm.environment.set("authToken", json.accessToken)）串联请求，以便在后续请求中使用。

有关环境文件格式、动态变量和请求串联模式，请参阅 reference/data-management.md。 </environment_management>

<authentication_testing>

身份验证测试

身份验证类型	方法	密钥模式
Bearer 令牌	从登录响应中保存，并在 Authorization 标头中使用	pm.environment.set("accessToken", json.accessToken)
API 密钥	标头（X-API-Key）或查询参数	{{apiKey}} 变量
OAuth 2.0	请求前脚本检查是否过期，并自动刷新	使用 pm.sendRequest() 刷新令牌

务必测试：不带令牌时返回 401，角色不正确时返回 403。

有关 OAuth 2.0 刷新流程和身份验证失败测试模式，请参阅 reference/postman-patterns.md。 </authentication_testing>

<error_testing>

错误响应测试

测试每类错误：400（验证错误，包含 details 数组）、404（未找到）、429（包含速率限制标头）、5xx（包含 requestId）。

有关错误响应断言模式，请参阅 reference/test-design.md。 </error_testing>

<ci_integration>

CI/CD 集成

工具	CLI	运行命令
Postman	Newman	newman run collection.json -e staging.json
Bruno	Bruno CLI	bru run --env staging

通过 GitHub Actions 集成：安装 CLI、运行集合，并将 HTML 报告作为构建产物上传。敏感环境变量使用 ${{ secrets.* }}。

有关 GitHub Actions 工作流、报告器和密钥处理，请参阅 reference/ci-integration.md。 </ci_integration>

<data_management>

测试数据管理

使用数据文件（newman run -d test-data.json）进行基于迭代的测试。Postman 内置动态变量（{{$guid}}、{{$randomEmail}}、{{$timestamp}}）。在请求后脚本中添加清理脚本，以删除创建的资源。

有关数据文件格式、动态生成和清理模式，请参阅 reference/data-management.md。 </data_management>

## API 测试清单

创建集合前：

• 已审阅 API 文档
• 已确定身份验证方式
• 已定义所有环境的基础 URL
• 已确定测试数据策略

对于每个端点：

• 正常路径测试（预期输入、预期输出）
• 必填字段验证（400 错误）
• 身份验证测试（不带令牌时返回 401）
• 授权测试（权限不正确时返回 403）
• 未找到测试（无效 ID 时返回 404）
• 已验证响应架构
• 已断言响应时间

集合组织：

• 按资源分组请求
• 为依赖请求设置序列号
• 为本地/预发布/生产环境创建环境配置
• 将敏感值标记为密钥

CI 集成：

• 已配置 Newman/Bruno CLI
• 已创建 GitHub Actions 工作流
• 已将测试报告作为构建产物上传
• 已将密钥存储在 CI 环境中

如需详细模式，请加载相应参考资料：

主题	参考文件	加载时机
Postman 高级模式	reference/postman-patterns.md	集合、脚本、监视器
Bruno 工作流	reference/bruno-patterns.md	.bru 文件、git 集成
测试用例设计	reference/test-design.md	覆盖策略、边界情况
测试数据策略	reference/data-management.md	固定数据、动态数据、清理
CI/CD 流水线	reference/ci-integration.md	Newman、GitHub Actions、报告

加载方式： 请求具体主题，或查看上下文是否有相关提示。

输出结果旁注文件

最后一步，将以下内容写入 ~/.claude/skill-analytics/last-outcome-api-testing.json：

{"ts":"[UTC ISO8601]","skill":"api-testing","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"tests_created":[n],"endpoints_tested":[n],"assertions_written":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果部分阶段失败但已生成结果，请使用状态 "partial"。只有未生成任何输出时才使用 "error"。