api-blackbox-test-executor

name	api-blackbox-test-executor
description	编码后接口黑盒测试执行 Skill。当用户需要根据测试方案或测试用例执行真实 HTTP/gRPC 请求，使用 db-mcp 构造或获取测试数据，记录 curl 请求、接口响应、跨接口集成编排链路和数据库验证结果时使用。

编码后接口黑盒测试执行

目标

根据 planner 阶段输出的测试用例、测试数据计划和接口编排/集成链路，执行真实接口请求并产出可供 reporter 汇总的证据。

文件输出

本阶段必须将完整执行记录写入 Markdown 文件。默认路径为：

tests/【需求】_YYYYMMDD/执行记录.md

规则：

• 【需求】 必须与 planner 阶段目录保持一致；如果已有 tests/【需求】_YYYYMMDD/测试方案.md，应复用同一目录。
• YYYYMMDD 使用执行当天日期，例如 20260428；如果用户或 planner 阶段已确定日期，以既有目录为准。
• 文件名中的 /、空格、冒号、引号等不适合作为路径的字符应替换为 _。
• 写入文件后，在回复中说明文件路径、执行通过/失败/阻塞数量和关键失败原因。
• 无法写入文件时，必须标记为阻塞并说明原因，不得只在对话中输出完整执行记录后视为完成。

执行原则

• 以真实接口行为为准，不用单元测试结果替代黑盒验证结论。
• 涉及数据库准备、查询、断言时，优先使用 db-mcp。
• 未确认测试环境安全前，不修改生产或疑似生产数据。
• 新建测试数据应带有清晰标记，例如 codex_api_test_、时间戳、请求 ID 或测试用例 ID。
• 表结构不明确时，先用 db_describe 查看字段，再构造数据。
• 所有已执行接口请求都必须保留 curl 形式记录，包含请求参数、返回数据、通过状态和不通过原因。
• 编排测试中从前置接口提取的数据必须记录来源字段、提取值用途和传递到后续接口的位置。
• 无法执行的用例必须标记为 Blocked，并说明缺少的环境、凭证、接口、依赖或数据。

使用 db-mcp 准备数据

• 多实例场景先用 db_list_instances 或 db_switch 确认目标数据库。
• 不确定表结构时先用 db_describe。
• 可复用安全数据时用 db_query 查询。
• 需要新建数据时用 db_insert 或 db_batch_insert。
• 只对测试明确拥有的数据使用 db_update。
• 只有确认逻辑删除语义可接受时，才使用 db_delete 或 db_batch_delete 做清理。
• 多表准备需要原子性时使用 db_transaction。

记录每条创建或复用数据的定位条件，保证后续能重复查询和验证。

执行真实接口请求

• HTTP 接口使用 curl、项目已有 API 脚本或集成测试工具。
• gRPC 接口使用 grpcurl 或项目已有工具。
• 证据中要包含方法、路径、base URL、headers、鉴权信息处理方式、query 参数和 JSON body。
• 记录实际状态码、响应体和关键响应头。
• 有数据库副作用的用例，必须同时验证接口响应和数据库状态后才能判定通过。

每个已执行接口请求必须形成一条请求记录：

| 用例 ID | curl 请求 | 请求参数 | 返回数据 | 是否通过 | 不通过原因 |
| --- | --- | --- | --- | --- | --- |

记录要求：

• curl 请求 使用可复现命令，敏感 token 可脱敏为 <TOKEN>，但 header 名称和鉴权方式必须保留。
• 请求参数 写明 path 参数、query 参数、body 和关键 header。
• 返回数据 至少包含 HTTP 状态码、关键响应头和响应体摘要；失败时保留错误码和错误消息。
• 是否通过 只能写通过、失败、阻塞或跳过。
• 不通过原因 必须基于接口响应、数据库证据或环境阻塞事实，不做无证据猜测。

执行接口编排/集成链路

对接口编排和集成测试用例，按链路顺序执行并记录每一步。链路中可以包含本次未变更但业务流程必需的接口。

| 链路 ID | 步骤 | curl 请求 | 提取数据 | 传递到 | 步骤结果 | 失败原因 |
| --- | --- | --- | --- | --- | --- | --- |

执行要求：

• 串行链路必须等待前一步响应，提取字段后再构造下一步请求。
• 并行前置链路必须分别记录每个前置接口的请求和响应，再记录合并后的后续请求。
• 条件分支链路必须记录分支判断依据，例如响应字段、状态码或数据库状态。
• 对未变更接口，也必须记录 curl、响应、提取字段和它在当前业务链路中的作用。
• 前置步骤失败时，不得伪造后续请求；应记录后续步骤为阻塞，并说明依赖哪个步骤失败。
• 每一步都要记录 curl、请求参数、返回数据、是否通过和不通过原因。
• 每个被传递的数据值都要记录来源接口、来源字段、目标接口和目标字段。

使用 db-mcp 验证数据库

每个相关请求后，用 db-mcp 验证：

• 新增或变更的行/文档。
• 参数校验失败时没有产生意外写入。
• 逻辑删除字段、审计字段和更新时间。
• 归属关系、租户、用户、状态、金额、计数器、时间戳和关联关系。
• 老客户端可能依赖的兼容性可见字段。
• 编排链路中每个步骤产生的中间状态和最终状态，避免只验证最后一个接口。

执行阶段输出

输出必须能被 reporter 直接使用，至少包含：

• 测试环境和基础配置。
• 测试数据准备记录。
• 单接口请求记录。
• 接口编排链路执行记录。
• DB 验证记录。
• 失败、阻塞和跳过原因。
• 测试数据清理状态。