API 测试

相关源文件

• .gitignore
• api/Conduit.postman_collection.json
• api/README.md
• api/run-api-tests.sh
• apps/documentation/src/content/docs/specifications/backend/api-response-format.md
• media/realworld.png

本文档介绍了 RealWorld 项目中的 API 测试系统，该系统验证后端实现是否正确符合标准化的 API 规范。您将了解如何运行测试、测试验证的内容以及如何解决常见问题。

测试架构

API 测试系统使用 Postman 集合来定义用于验证 API 端点的测试。此集合通过 Newman（Postman 的命令行集合运行器）执行，并由一个 shell 脚本进行编排。

API 测试系统架构

来源： api/Conduit.postman_collection.json, api/run-api-tests.sh

运行 API 测试

您可以在本地或持续集成环境中运行 API 测试，以验证您的后端实现是否正确遵循 RealWorld API 规范。

测试环境设置

run-api-tests.sh 脚本设置了以下环境变量：

可变	默认值	描述
APIURL	https://api.realworld.io/api	要测试的 API 的基本 URL
USERNAME	从时间戳生成	测试用户的唯一用户名
EMAIL	{USERNAME}@mail.com	测试用户的电子邮件
PASSWORD	password	测试用户的密码

本地测试执行

在本地运行测试以针对您的 API 实现

此命令将通过 Newman 执行 Postman 集合，Newman 将向您的 API 发出请求并验证响应。

来源： api/README.md, api/run-api-tests.sh

测试集合结构

Postman 集合包含针对不同 API 端点的已组织测试文件夹。

Postman 集合组织

来源： api/Conduit.postman_collection.json

测试类别和示例

身份验证测试

身份验证测试会验证用户注册、登录、个人资料检索和个人资料更新。

注册测试示例

Request:
POST {{APIURL}}/users
Content-Type: application/json
{
  "user": {
    "email": "{{EMAIL}}",
    "password": "{{PASSWORD}}",
    "username": "{{USERNAME}}"
  }
}

Test Validation:
- Response contains "user" property
- User has "email" property
- User has "username" property
- User has "token" property

来源： api/Conduit.postman_collection.json:13-61

文章测试

这些测试会验证文章的列出、创建、更新和删除操作。

创建文章测试示例

Request:
POST {{APIURL}}/articles
Content-Type: application/json
Authorization: Token {{token}}
{
  "article": {
    "title": "How to train your dragon",
    "description": "Ever wonder how?",
    "body": "Very carefully.",
    "tagList": ["training", "dragons"]
  }
}

Test Validation:
- Response contains "article" property
- Article has "title", "slug", "body", "createdAt", etc.
- Article's "createdAt" is an ISO 8601 timestamp

来源： api/Conduit.postman_collection.json:570-632

评论和标签测试

这些测试会验证评论的添加、检索和删除，以及标签的列出。

添加评论测试示例

Request:
POST {{APIURL}}/articles/{{slug}}/comments
Content-Type: application/json
Authorization: Token {{token}}
{
  "comment": {
    "body": "Test comment text"
  }
}

Test Validation:
- Response contains "comment" property
- Comment has "id", "body", "author", etc.

来源： api/Conduit.postman_collection.json

测试脚本操作

Postman 集合中的每个测试都包含用于验证 API 响应的 JavaScript。这些脚本通常会：

1. 解析 JSON 响应体
2. 检查必需的属性
3. 验证数据类型和格式
4. 验证关系完整性

示例测试脚本摘录

来源： api/Conduit.postman_collection.json:65-83

预期响应格式

测试会验证您的 API 实现返回的响应格式是否符合 RealWorld API 指定的格式。例如，文章响应的预期格式为：

来源： apps/documentation/src/content/docs/specifications/backend/api-response-format.md:36-58

常见问题排查

API URL 配置

如果测试无法连接到您的 API，请检查 `APIURL` 环境变量是否设置正确，并指向您的 API 的根目录。

身份验证失败

身份验证测试失败通常表明 JWT 令牌实现存在问题。请确保您的后端正确处理身份验证请求并以预期格式返回令牌。

响应结构不匹配

如果测试因属性验证错误而失败，请确保您的 API 返回的 JSON 结构与测试所需的结构完全一致，包括所有必需字段及其正确的名称和数据类型。

来源： api/Conduit.postman_collection.json, api/run-api-tests.sh

与 CI/CD 集成

API 测试可以集成到持续集成工作流中，以便在每次更改时自动验证您的 API 实现。

这可以确保代码更改不会破坏 API 兼容性。

来源： api/run-api-tests.sh

测试执行流程

运行测试时，会发生以下过程：

1. run-api-tests.sh 脚本设置环境变量。
2. Newman 执行 Postman 集合。
3. 测试注册新用户、登录并存储身份验证令牌。
4. 后续测试使用令牌进行身份验证请求。
5. 测试结果将在控制台中报告。

这种顺序执行可确保正确处理测试之间的依赖关系（例如，需要身份验证令牌）。

来源： api/Conduit.postman_collection.json:110-164, api/run-api-tests.sh