api-test-suite-builder

API 测试套件构建器

扫描各类框架（Next.js App Router、Express、FastAPI、Django REST、Go net/http）的 API 路由定义，分析请求和响应架构，并生成全面的测试套件，覆盖身份验证、授权、输入验证、错误处理、分页、文件上传、速率限制、契约测试和负载测试。输出可直接运行的测试文件，支持 Vitest+Supertest（Node）、Pytest+httpx（Python）或 k6（负载测试）。

核心功能

• 路由检测与分析 — 扫描源文件以提取端点、解析请求和响应架构，并检测 Node、Python 和 Go 框架中的身份验证中间件及授权规则。
• 测试矩阵生成 — 身份验证（有效/无效/过期令牌、角色错误）、输入验证（缺失/类型错误/边界值/注入）、错误路径（400/401/403/404/409/422/429/500）、分页、文件上传和速率限制。
• 契约测试 — 将 OpenAPI 转为测试、Pact 消费者驱动契约测试，以及用于检测破坏性变更的架构快照测试。
• 负载测试 — 提供具有渐增模式和 SLA 阈值的 k6 脚本、延迟百分位跟踪（P50/P95/P99）及并发用户模拟。

适用场景

• 新增 API — 在实现前生成测试脚手架（TDD）。
• 没有测试的旧版 API — 扫描并生成基线覆盖。
• 发布前 — 确保所有路由至少有冒烟测试。
• API 契约变更 — 检测并测试破坏性变更。
• 安全审计 — 生成对抗性输入测试。
• 性能验证 — 创建负载测试基线。

请先确认

生成套件前，请确认以下输入。如果有任何内容未知或含糊不清，请先询问，不要自行假设：

• 目标框架 — Vitest+Supertest、Pytest+httpx 或 k6（通过 --framework 决定生成的测试文件格式）
• 规范或路由来源 — OpenAPI 规范或要扫描的源文件（生成器解析的输入）
• 测试范围 — 身份验证、输入验证、契约、负载或完整矩阵（要生成哪些测试类别）

停止规则：只询问对输出影响最大的 2-3 项。如果用户表示“直接起草”，则继续操作，并在产物开头列出假设。

工具

工具	用途	命令
test_generator.py	根据 OpenAPI/Swagger 规范生成 API 测试框架	python scripts/test_generator.py spec.json --framework vitest --output tests/
coverage_analyzer.py	对比规范中的端点与现有测试文件，找出覆盖缺口	python scripts/coverage_analyzer.py spec.json tests/ --threshold 95
contract_validator.py	根据 OpenAPI 架构契约验证响应样本	python scripts/contract_validator.py spec.json samples/ --strict

参考资料

根据任务加载对应的参考资料 — 保持此文件精简，按需获取详细信息：

• references/route-detection-and-matrices.md — 各框架的路由检测 shell 命令，以及完整的身份验证、输入验证和分页测试矩阵，并附有详尽的 TypeScript 示例。扫描代码库或编写核心测试用例时阅读。
• references/contract-and-load-testing.md — 完整的 Pact 消费者驱动契约测试和 k6 负载测试脚本，以及在本地、预发布环境和云端运行负载测试的命令。添加契约或性能测试时阅读。
• references/workflow-and-quality.md — 9 步生成工作流、可复用的测试辅助工具模式（身份验证、已验证身份的请求、工厂函数）、常见问题、最佳实践、故障排查表和成功标准。生成套件以及交付前阅读。

范围与限制

此技能涵盖：

• 根据路由定义，为 Node.js、Python 和 Go 框架的 REST API 生成测试套件
• 生成身份验证、授权、输入验证、分页和错误路径测试
• 使用 Pact 进行消费者驱动的契约测试，以及验证模式快照
• 使用 k6 和 Artillery 生成负载和性能测试脚本

此技能不涵盖：

• GraphQL API 测试（模式审查模式请参阅 engineering/api-design-reviewer）
• 端到端浏览器测试或 UI 交互测试（请参阅 engineering/playwright-pro）
• 数据库迁移测试或模式验证（请参阅 engineering/database-schema-designer）
• 超出输入清理检查范围的安全渗透测试（请参阅 engineering/skill-security-auditor）

集成点

技能	集成方式	数据流
engineering/api-design-reviewer	在生成测试前验证 API 设计	设计审查输出会定义此技能所生成测试对应的端点契约
engineering/ci-cd-pipeline-builder	将生成的测试嵌入 CI/CD 流水线	生成的测试文件和 k6 脚本会作为带有通过/失败门禁的流水线阶段加入
engineering/playwright-pro	通过 E2E 浏览器测试补充 API 测试	API 测试套件验证后端行为；Playwright 测试验证使用这些 API 的前端
engineering/database-schema-designer	使测试夹具与数据库模式保持一致	模式定义会为生成的测试辅助工具中使用的工厂函数和种子数据提供依据
engineering/observability-designer	在生产环境中监控由测试覆盖的端点	负载测试阈值（P95、P99）会用于同一生产端点仪表板的告警规则
engineering/performance-profiler	调查未达到负载测试阈值的端点	k6 结果会识别缓慢的端点；性能分析技能会在代码层面追踪根本原因