HTTP API 测试运行器

使用此技能将一次性的 HTTP 检查转化为可复用的 .http 测试用例，并生成一个可执行的验证脚本。

前提条件

必需的运行时依赖项：

• bash
• curl
• python3

快速自检：

bash --version
curl --version
python3 --version

默认生成两个产物：

• .api-tests.http
• .api-verify.sh

.http 文件是事实来源（source of truth）。Shell 脚本用于执行各测试用例，输出可读的 PASS/FAIL/SKIP 结果；当任意非跳过（non-skipped）用例失败时，脚本以非零退出码退出。

快速上手

1. 仅收集缺失的输入：主机地址（host）、HTTP 方法（method）、认证方式（auth）、请求数据（request data）、测试用例（cases）以及预期结果（expected results）。
2. 选择起点：
   • 对于新接口端点，使用 templates/ 目录下的模板。
   • 若目标端点与现有示例相似，参考 examples/ 目录。
   • 如涉及多步骤或高级校验逻辑，请查阅 references/complex-scenarios.md。
3. 生成或更新以下两个文件：
   • .api-tests.http
   • .api-verify.sh
4. 验证所生成脚本的正确性：

bash -n './.api-verify.sh'
bash './.api-verify.sh'
COOKIE='完整的 Cookie 请求头' AUTH_TOKEN='token value' bash './.api-verify.sh'
# （可选）针对不稳定网络环境：
MAX_TIME=40 RETRY_COUNT=2 RETRY_DELAY=1 bash './.api-verify.sh'

5. 若测试用例失败，在修改断言前先对问题归类：
   • 认证不匹配（auth mismatch）
   • 请求结构不匹配（request shape mismatch）
   • 环境或测试夹具不匹配（environment or fixture mismatch）
   • 业务逻辑断言不匹配（business assertion mismatch）

参见 references/debugging-cookbook.md 获取失败排查清单。

如需最简可行路径，请先查阅 GET_STARTED.md。

需要收集的内容

仅向用户询问其尚未提供的字段。

对于基于 Cookie 的测试，请提示用户从浏览器开发者工具 Network 面板中复制一次成功请求的完整 Cookie: 请求头。请勿尝试从 Storage 面板中拼接还原 Cookie。

生成的注释及最终使用说明应遵循用户的语言习惯。

选择你的起点

• templates/basic.api-tests.txt
  • 新建接口端点的最快路径。
  • 包含一组常用变量和断言的最小集合。
• templates/basic.api-verify.sh
  • 具备超时处理、基于环境变量注入密钥、格式化输出能力的可执行 Shell 脚本。
• examples/resource-detail/
  • 使用 Cookie 认证并进行 JSON 字段断言的资源详情查询示例。
• examples/auth-login-required/
  • 未认证及非法认证场景的测试用例。
• examples/list-assertions/
  • 列表投影（projection）、成员存在性（membership）及缺失性（absence）检查。
• examples/async-job-polling/
  • “提交 → 轮询 → 校验”模式的异步任务工作流，配套提供可执行的预置步骤脚本（pre-step script）。

注意：面向发布的技能资产使用 .api-tests.txt 后缀以满足上传限制，但实际运行时生成的产物仍应使用 .api-tests.http 后缀。

场景索引

产物契约（Artifact Contract）

生成的 .http 文件应满足：

• 声明变量，例如 @host、@cookie、@token、@resourceId
• 每个测试用例使用 ### 作为标题分隔符
• 每个用例仅包含一个请求
• 添加明确的 expect.* 注释用于描述期望行为
• 默认不将真实密钥写入该文件

生成的 Shell 脚本应满足：

• 读取 .http 文件内容
• 解析 {{variable}} 占位符
• 支持通过环境变量传入密钥（secrets）
• 为每个用例打印 PASS/FAIL/SKIP 输出
• 打印汇总行（summary line）
• 任一非跳过用例失败时，以非零退出码退出

安全规则

• 禁止提交真实的 Cookie、Token、密码或内部凭证。
• 使用占位符表达密钥，例如 @cookie = 和 @token = 。
• 当密钥缺失时，已认证的用例应明确跳过（SKIP），并附带清晰原因，而非导致解析器崩溃。
• 在发布或提交生成的产物前，请运行轻量级密钥扫描：

rg -n "password|secret|session_id|auth_token|access_token|refresh_token" 
rg -n "Authorization: Bearer [A-Za-z0-9._-]+|C[o]okie: [A-Za-z0-9_%-]+=" 

参考文档地图

• 最快首次运行指南：GET_STARTED.md
• 断言语法参考：references/assertion-cheatsheet.md
• 复杂流程与高级校验：references/complex-scenarios.md
• 失败诊断与分类处理：references/debugging-cookbook.md
• 常见问题解答（FAQ）：references/faq.md
• 轻量级、可发布的示例：references/http_test_artifact_example.md

默认运行检查项

生成产物后，请执行以下检查：

bash -n './.api-verify.sh'
bash './.api-verify.sh'
COOKIE='完整的 Cookie 请求头' AUTH_TOKEN='token value' bash './.api-verify.sh'

结果解读：

• bash -n 可捕获 Shell 语法错误。
• 不传入密钥运行，用于验证脚本解析逻辑及预期的 SKIP 行为是否正常。
• 传入密钥运行，用于验证实际 API 行为及断言逻辑是否符合预期。