api-blackbox-test-executor

name	api-blackbox-test-executor
description	编码后接口黑盒测试执行 Skill。当测试用例评审通过或有条件通过后，根据测试方案或测试用例执行真实 HTTP/gRPC 请求，使用 db-mcp 构造或获取测试数据，记录 curl 请求、接口响应、接口 x 字段语义等价类矩阵单元执行状态、场景 x 边界/异常覆盖单元执行状态、跨接口一致性用例、跨接口集成编排链路和数据库验证结果时使用。

编码后接口黑盒测试执行

目标

根据 planner 阶段输出的测试用例、测试数据计划、接口 x 字段语义等价类矩阵、跨接口一致性用例和接口编排/集成链路，以及 reviewer 阶段通过或有条件通过的评审结论，执行真实接口请求并产出可供 reporter 汇总的证据。

执行记录格式必须使用 references/execution-template.md。主文件只保留执行规则；新增或调整记录表格时优先修改 reference 模板。

文件输出

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

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

规则：

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

执行前评审门禁

• 执行前必须读取或确认同一需求目录下的 测试用例评审.md。
• 只有评审结果为 通过 或 有条件通过 时，才允许执行真实接口请求。
• 执行前必须读取 reviewer 输出的影响点与影响范围评估，并检查现有测试方案、矩阵单元、跨接口一致性用例和编排链路是否覆盖直接影响和扩散影响。
• 如果上下文中没有影响点与影响范围评估，必须先基于需求分析和技术方案判断测试范围是否充分，再按需使用 GitNexus、代码搜索、代码 diff、API 文档和调用链分析识别公共方法、共享组件、关联接口、调用方、数据模型、副作用、缓存/异步、安全边界、兼容性和观测影响。
• 如果发现直接影响或扩散影响未被覆盖，不得直接执行原测试方案；必须先输出补充测试要求或补充用例草案，说明缺失的测试用例、矩阵单元、跨接口一致性用例、编排链路或断言。关键范围缺口必须回到 api-blackbox-test-planner 完整补方案；非关键补证项可回到 api-blackbox-test-reviewer 评审补充内容。只有补充内容评审通过或有条件通过后才允许执行。
• 评审结果为 有条件通过 时，必须把评审中列出的 executor 执行关注项纳入执行记录，并在对应用例或链路中补证。
• 评审结果为 不通过 时，必须阻塞执行，并提示回到 api-blackbox-test-planner 按退回项完善测试方案后重新评审。
• 评审结果为 阻塞、缺少评审记录或无法确认评审结论时，不得执行 executor；必须先完成 api-blackbox-test-reviewer。

执行原则

• 以真实接口行为为准，不用单元测试结果替代黑盒验证结论。
• 涉及数据库准备、查询、断言时，优先使用 db-mcp。
• 未确认测试环境安全前，不修改生产或疑似生产数据。
• 新建测试数据应带有清晰标记，例如 codex_api_test_、时间戳、请求 ID 或测试用例 ID。
• 表结构不明确时，先用 db_describe 查看字段，再构造数据。
• 所有已执行接口请求都必须保留 curl 形式记录，包含请求参数、返回数据、通过状态和不通过原因。
• 必须按 接口 x 字段语义等价类矩阵 的每个矩阵单元记录状态：已执行、跳过 或 阻塞，并记录证据路径。证据路径可以指向本执行记录中的章节锚点、curl 记录编号、DB 验证编号、日志文件或截图/附件路径。
• 必须按 场景 x 边界/异常覆盖矩阵 的每个必测覆盖单元记录状态：已执行、跳过 或 阻塞，并记录证据路径。核心业务场景只有 Happy Path 执行证据时，必须标记为覆盖缺口并回到 reviewer 或 planner 补充。
• 必测矩阵单元不得静默遗漏；无法执行时必须标记 阻塞 并说明环境、凭证、依赖、数据或安全授权缺口；主动不执行时必须标记 跳过 并说明依据。
• 必测场景覆盖单元不得静默遗漏；无法执行时必须标记 阻塞，主动不执行时必须标记 跳过 并说明依据。
• 逻辑类似接口必须分别真实请求并记录证据。不得用接口 A 的成功结果替代接口 B 的执行状态。
• 编排测试中从前置接口提取的数据必须记录来源字段、提取值用途和传递到后续接口的位置。
• 无法执行的用例必须标记为 Blocked，并说明缺少的环境、凭证、接口、依赖或数据。

阻塞前自动补救

标记用例、链路或矩阵单元为 阻塞 前，必须先完成与阻塞类型匹配的 preflight 自动补救，并把尝试记录写入 references/execution-template.md 的“阻塞前自动补救记录”。能自动解除时必须继续执行，不得提前交给 reporter。

• 鉴权缺失：搜索项目 README、脚本、环境变量、配置文件、测试账号文档和登录接口；能获取 token 或测试凭证时，继续执行并记录来源。不得伪造凭证或越权使用非测试账号。
• DB 不匹配：使用 db_list_instances、db_switch、db_describe，按目标 user_id、order_id、source_id 或业务主键查询定位；能确定目标库和表时，继续准备数据和验证。
• 服务不可用：检查 base URL、健康接口、端口、启动脚本、README、Makefile、package scripts、docker compose 或进程管理配置；可控制时自动构建、启动或重启，最多 3 次。
• 数据缺失：确认当前数据库是测试库或安全隔离环境后，构造带 codex_api_test_ 标记的最小数据，并记录定位条件和清理方式。
• 依赖服务不可用：检查健康接口、日志、本地 mock/stub、启动脚本或降级配置；可控制时启动或切换到测试替代方案。

只有 preflight 证据证明 agent 无法自行解除时，才能写 阻塞。阻塞原因必须明确最小缺口、已尝试动作、失败证据和解除后复验范围；需要用户或外部系统输入时交给 reporter 进入 WAIT_USER_INPUT，而不是把流程结束。

使用 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。
• 记录实际状态码、响应体和关键响应头。
• 有数据库副作用的用例，必须同时验证接口响应和数据库状态后才能判定通过。

每个已执行接口请求必须按 references/execution-template.md 形成请求记录。记录要求：

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

执行矩阵单元

在执行用例后，必须按 references/execution-template.md 回填 planner/reviewer 中的 接口 x 字段语义等价类矩阵。

执行要求：

• 执行状态 只能写 已执行、跳过 或 阻塞。
• 一个用例覆盖多个矩阵单元时，可以复用同一 curl/DB 证据路径，但每个矩阵单元必须独立列行。
• 证据路径 必须可定位到实际证据，不能只写“见上方”或“已验证”。
• 必测矩阵单元如果没有 已执行 状态，必须进入执行摘要的阻塞或跳过统计，并交给 reporter 判断最终结论。

执行业务场景边界/异常覆盖单元

在执行用例后，必须按 references/execution-template.md 回填 planner/reviewer 中的 场景 x 边界/异常覆盖矩阵。

执行要求：

• 执行状态 只能写 已执行、跳过 或 阻塞。
• 一个用例覆盖多个场景覆盖单元时，可以复用同一 curl/DB 证据路径，但每个覆盖单元必须独立列行。
• 证据路径 必须可定位到实际证据，不能只写“见上方”或“已验证”。
• 必测覆盖单元如果没有 已执行 状态，必须进入执行摘要的阻塞或跳过统计，并交给 reporter 判断最终结论。

执行跨接口一致性用例

对 planner/reviewer 标识的逻辑类似接口组，必须分别执行每个参与接口，并按 references/execution-template.md 记录对比结果。

执行要求：

• 每个参与接口都必须有独立 curl 记录和响应证据。
• 对比状态码、错误码、空结果语义、响应字段语义、权限过滤和数据库副作用。
• 如果某接口因权限或环境不可执行，应只标记该接口对应矩阵单元和一致性用例为 阻塞，不得用其他接口的结果补位。

执行接口编排/集成链路

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

执行要求：

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

使用 db-mcp 验证数据库

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

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

执行阶段输出

输出必须使用 references/execution-template.md，并能被 reporter 直接使用，至少包含：

• 测试环境和基础配置。
• 影响点与影响范围覆盖核对结果；如有补充用例，记录补充原因、评审结果和关联影响点。
• 测试数据准备记录。
• 单接口请求记录。
• 接口 x 字段语义等价类矩阵执行状态。
• 场景 x 边界/异常覆盖执行状态。
• 跨接口一致性执行记录。
• 接口编排链路执行记录。
• DB 验证记录。
• 失败、阻塞和跳过原因。
• 测试数据清理状态。