api-test-suite-builder

API 测试套件生成器

等级: POWERFUL 分类: Engineering 领域: 测试 / API 质量

---

概述

扫描多种框架（Next.js App Router、Express、FastAPI、Django REST）中的 API 路由定义，自动生成覆盖认证、输入校验、错误码、分页、文件上传和速率限制的完整测试套件。可输出可直接运行的测试文件，分别基于 Vitest+Supertest（Node）或 Pytest+httpx（Python）。

---

核心能力

• 路由检测 — 扫描源文件，提取所有 API 端点
• 认证覆盖 — 有效/无效/过期令牌，缺失认证头
• 输入校验 — 缺失字段、错误类型、边界值、注入尝试
• 错误码矩阵 — 每个路由覆盖 400/401/403/404/422/500
• 分页 — 首页/末页/空页/超大页码
• 文件上传 — 有效文件、超大文件、错误 MIME 类型、空文件
• 速率限制 — 突发检测、按用户与全局限制的区分

---

使用场景

• 新增 API — 在编写实现之前生成测试脚手架（TDD）
• 没有测试的遗留 API — 扫描并生成基线覆盖
• API 契约审查 — 验证现有测试是否与当前路由定义一致
• 发布前回归检查 — 确保所有路由至少具备冒烟测试
• 安全审计准备 — 生成对抗性输入测试

---

路由检测

Next.js App Router

# Find all route handlers
find ./app/api -name "route.ts" -o -name "route.js" | sort

# Extract HTTP methods from each route file
grep -rn "export async function\|export function" app/api/**/route.ts | \
  grep -oE "(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)" | sort -u

# Full route map
find ./app/api -name "route.ts" | while read f; do
  route=$(echo $f | sed 's|./app||' | sed 's|/route.ts||')
  methods=$(grep -oE "export (async )?function (GET|POST|PUT|PATCH|DELETE)" "$f" | \
    grep -oE "(GET|POST|PUT|PATCH|DELETE)")
  echo "$methods $route"
done

Express

# Find all router files
find ./src -name "*.ts" -o -name "*.js" | xargs grep -l "router\.\(get\|post\|put\|delete\|patch\)" 2>/dev/null

# Extract routes with line numbers
grep -rn "router\.\(get\|post\|put\|delete\|patch\)\|app\.\(get\|post\|put\|delete\|patch\)" \
  src/ --include="*.ts" | grep -oE "(get|post|put|delete|patch)\(['\"][^'\"]*['\"]"

# Generate route map
grep -rn "router\.\|app\." src/ --include="*.ts" | \
  grep -oE "\.(get|post|put|delete|patch)\(['\"][^'\"]+['\"]" | \
  sed "s/\.\(.*\)('\(.*\)'/\U\1 \2/"

FastAPI

# Find all route decorators
grep -rn "@app\.\|@router\." . --include="*.py" | \
  grep -E "@(app|router)\.(get|post|put|delete|patch)"

# Extract with path and function name
grep -rn "@\(app\|router\)\.\(get\|post\|put\|delete\|patch\)" . --include="*.py" | \
  grep -oE "@(app|router)\.(get|post|put|delete|patch)\(['\"][^'\"]*['\"]"

Django REST Framework

# urlpatterns extraction
grep -rn "path\|re_path\|url(" . --include="*.py" | grep "urlpatterns" -A 50 | \
  grep -E "path\(['\"]" | grep -oE "['\"][^'\"]+['\"]" | head -40

# ViewSet router registration
grep -rn "router\.register\|DefaultRouter\|SimpleRouter" . --include="*.py"

---

测试生成模式

认证测试矩阵

对于每个需要认证的端点，生成：

测试用例	预期状态码
无 Authorization 请求头	401
令牌格式无效	401
令牌有效，但用户角色错误	403
过期的 JWT 令牌	401
令牌有效，角色正确	2xx
已删除用户的令牌	401

输入校验矩阵

对于每个带请求体的 POST/PUT/PATCH 端点：

测试用例	预期状态码
空请求体 {}	400 或 422
缺少必填字段（逐个测试）	400 或 422
类型错误（应为整数却传入字符串）	400 或 422
边界：值为 min-1	400 或 422
边界：值为 min	2xx
边界：值为 max	2xx
边界：值为 max+1	400 或 422
字符串字段中的 SQL 注入	400 或 200（已净化）
字符串字段中的 XSS 载荷	400 或 200（已净化）
必填字段为 null	400 或 422

---

示例测试文件

→ 详见 references/example-test-files.md

基于路由扫描生成测试

给定一个代码库时，按以下流程操作：

1. 扫描路由：使用上述检测命令
2. 阅读每个路由处理器，了解：
   • 预期的请求体结构
   • 认证要求（中间件、装饰器）
   • 返回类型与状态码
   • 业务规则（所有权、角色检查）
3. 按路由组生成测试文件，使用上述模式
4. 为测试命名时要具描述性：使用 "returns 401 when token is expired" 而非 "auth test 3"
5. 使用工厂函数或 fixtures 准备测试数据，切勿硬编码 ID
6. 断言响应结构，而不仅仅是状态码

---

常见误区

• 只测试正常路径 — 80% 的 Bug 出现在错误路径中，应优先测试这些路径
• 硬编码测试数据 ID — 使用工厂函数或 fixtures；ID 会因环境不同而变化
• 测试之间共享状态 — 始终在 afterEach/afterAll 中清理
• 测试实现而非行为 — 测试 API 返回了什么，而不是它如何实现
• 缺少边界测试 — 差一错误在分页和限制逻辑中极为常见
• 未测试令牌过期 — 过期令牌的行为与无效令牌不同
• 忽略 Content-Type — 测试 API 是否会拒绝错误的内容类型（期望 JSON 却传入 XML）

---

最佳实践

1. 每个端点使用一个 describe 代码块——这样可以隔离故障，便于阅读
2. 仅准备最少的数据——不要加载整个数据库；只创建测试所需的数据
3. 使用 beforeAll 进行共享设置，使用 afterAll 进行清理——不要使用 beforeEach 执行耗时操作
4. 断言具体的错误消息或字段，而不只是状态码
5. 测试响应中是否完全不包含敏感字段（密码、密钥）
6. 对于身份验证测试，始终将“缺少请求头”的情况与“无效令牌”分开测试
7. 最后添加速率限制测试——如果并行运行，它们可能会干扰其他测试套件