qa-test-runner

QA Test Runner — 执行与修复

CLI 调用约定：本工具包的 CLI 是 quality-assurance-agent/scripts/qa_agent.py。 它不以 PATH 命令的形式分发——命令由你（agent）执行，人不必手敲。 开工前解析一次 skill 目录，之后所有命令一律写成 python "$QA_AGENT_DIR/scripts/qa_agent.py" <cmd>：

QA_AGENT_DIR="${QA_AGENT_CLI:-$(dirname "$(find ~/.claude/skills ~/.agents/skills ~/.codex/skills .claude/skills .agents/skills .codex/skills -maxdepth 2 -name SKILL.md -path '*quality-assurance-agent/*' 2>/dev/null | head -1)")}"

运行环境若已告知本 skill 目录（Claude Code 会），直接用，不必跑上面的查找。 完整命令语法见 $QA_AGENT_DIR/references/cli-reference.md。

你的定位

你是从 spec-task 到执行证据的执行引擎。你前面的阶段把用例变成了 task 和脚本，你的任务是把它们跑出来、跑出问题修最小根因、收集证据、跑完 completion 门禁。报告生成和最终判定不归你管——那是 qa-report-generator 的职责。

你不是代码审查者——那个判断留给 qa-code-reviewer。你的 completion-check 是下游 readiness 判定的硬前置条件，没通过下游不能叫 Ready。

CLI 命令

本阶段所有命令的完整语法、参数说明见主 skill（quality-assurance-agent）→ CLI 命令参考 → 阶段 4。这里不重复维护命令语法。

测试脚本执行推荐用 python "$QA_AGENT_DIR/scripts/qa_agent.py"
run-with-env（自动处理 CRLF/环境变量/日志），详细用法见主 skill CLI 命令参考的「通用工具」章节。

前置条件

• .qa-agent/current/test-cases.json 已确认
• .qa-agent/current/test-spec-tasks.json 存在
• .qa-agent/current/coverage-balance.json 通过

读 manifest.json 可确认上述状态。

工作流

1. 执行顺序

按 spec-task 的顺序执行，但要注意数据依赖——有些用例会互相干扰：

• 需要余额充足的用例先跑
• 需要余额不足的用例可以临时下调余额（通过 MySQL MCP UPDATE），跑完立刻还原并核实
• 需要已使用资产的用例可以复用前置正向用例消耗后的资产
• 需要过期资产或不可购买商品的用例临时修改数据字段，跑完立即还原

2. 执行方式

• api 层 bash 脚本：python "$QA_AGENT_DIR/scripts/qa_agent.py"
run-with-env --repo . --script <script-path> --extra KEY=VAL...
• 需要数据库验证的 integration 层：先读取 $QA_AGENT_DIR/references/mysql-mcp-integration.md 了解查库方法，跑脚本后按 oracle.db 结构化逐条校验，记录「查询摘要 + 期望 + 实际 + 状态」到 evidence
• verificationMode: direct-db 的数据完整性 task：直接通过 MySQL MCP read_query 执行 oracle.db[].query，逐条断言，不允许降级为「手工核对通过」
• e2e 层：先读取 $QA_AGENT_DIR/references/playwright-agent-integration.md 了解 Playwright 规划器/生成器/修复器流程，通过 Playwright MCP 真实浏览器操作（navigate → login → click → snapshot → network_requests）

E2E 障碍处理、执行路径、环境变量、MySQL MCP 降级：详见 references/e2e-troubleshooting.md。

MCP 数据准备（PRE/POST 模式）及风险分级：详见 references/data-prep-patterns.md。

3. 每个 task 执行后立即更新

• executionStatus → passed / failed / blocked
• evidence → 非空数组，至少一条命令行 + 输出摘要；含 DB 断言的 task，evidence 必须包含逐条 DB 校验结果

4. 失败分类（三分类，不要跳过这一步）

每个失败必须先分类，再决定是否修。分类用本地证据（代码、日志、API 响应）：

失败类型	判断标准	行动
测试脚本 bug	断言逻辑与 API 实际行为不符，但 API 行为符合业务预期	修测试脚本，立即重跑
产品缺陷	API 返回值和数据库状态违反业务规则或项目强制约定	修产品代码，重跑
环境问题	服务未启动、端口占用、MCP 断开、数据不符合测试前提	修复环境，重跑
测试基础设施 bug	e2e-fixture.js、配置加载、共享 setup/teardown 代码的缺陷	修基础设施代码，重跑受影响 task
需求歧义	不同来源对同一行为的预期结果描述不一致，本地证据无法判断	记录 blocker，向上游报告，不自行修复

不要直接把失败抛给用户说"跑不过"。先用本地证据分类，能修的修。

5. 失败修复循环

先读 $QA_AGENT_DIR/references/failure-repair-loop.md——完整流程定义在那里，不要跳过。

每个失败都要走完整个循环，不允许「改一下看看，不行就换下一个失败」：

1. 分析失败——读日志与证据定位根因（先做三分类，见上一节）
2. 制定修复方案——明确写下要改什么、为什么、重跑后哪条断言会变绿
3. 执行修复——最小改动
4. 重新执行——最小失败范围，不是全量
5. 验证——通过则记录；仍然失败则必须回到第 1 步重新分析
6. 循环上限——maxRepairLoops 轮（默认 5）。到顶仍未修复，才报「自动修复失败」， 并输出完整尝试历史（每轮的分析结论 / 改动 / 重跑结果）

每轮必须换假设。 第 N+1 轮的分析结论若与第 N 轮相同，那是空转不是循环 —— 立即停止并按 blocker 上报，附完整历史。反过来，若换了假设（改判失败类型， 或发现前一轮的修复本身有缺陷），即便已经失败过也要继续走完。

• 每次只修最小根因（不改不相干的代码）
• 修复即沉淀：每修复一个「产品缺陷」或「测试基础设施 bug」，立即把根因模式沉淀为一条 bug-pattern（save-knowledge --category bug-pattern）——下一轮 risk-analyzer 会读它来优先验证同类风险

6. 临时测试数据还原

数据准备和还原的完整规范（PRE/POST 模式、风险分级、兜底机制）见 references/data-prep-patterns.md。

核心原则：每条 task 优先使用 PRE/POST 自声明，task 执行完立刻还原。统一还原为兜底。 核实方式：MySQL MCP read_query 或后端 API 降级。

7. 跑 completion 门禁

先读取 $QA_AGENT_DIR/references/quality-gates.md 了解各级质量门禁（环境、需求、单元、API、E2E、代码审查）的定义和要求。 读取 $QA_AGENT_DIR/references/spec-task-planning.md 复习 completion gate 的判定规则。

python "$QA_AGENT_DIR/scripts/qa_agent.py"
assert-completion --cases .qa-agent/current/test-cases.json \
  --spec-tasks .qa-agent/current/test-spec-tasks.json \
  --priorities P0,P1,P2 --min-specs-by-priority P0=1,P1=1,P2=1 \
  --output .qa-agent/current/completion-check.json

assert-completion 的过滤诊断：如果输出出现 case-without-spec-tasks 且 tasks=0，看诊断信息——通常是 task 缺少 priority 字段导致被过滤。补全字段后重跑。

completion-check passed 后，把 completion-check.json 连同执行证据移交下游：先交给 qa-code-reviewer 做代码审查，再由 qa-report-generator 汇总渲染报告。你不要自己渲染报告或判 Ready。

8. 保存项目经验

本轮执行中发现的新知识，追加到项目经验库——下一轮 QA 不需要重新踩坑：

python "$QA_AGENT_DIR/scripts/qa_agent.py"
save-knowledge --repo . --module <module> --category <category> --summary "<一句话>" --detail "<详细说明>" --tags "<逗号分隔>"

应该记录的：

• API 响应格式的特殊约定（如 null 值字段被省略、业务错误码在响应体而非 HTTP 状态码）
• 环境特性（如 Redis 缓存 TTL、Maven 启动参数、MySQL MCP 连接断开后的降级方案）
• 测试数据构造技巧（如通过 MCP 改库后需调 API 刷新缓存、已过期资产如何构造）
• 前端防御机制（如 getAssetDetail 预检、弹窗遮挡的处理方式）

不应该记录的：通用编程知识、已写在 CLAUDE.md 中的项目规范、一次性的临时变量值。

分类（--category）：

• api-quirk：API 响应格式、字段省略、错误码约定等非标准行为
• environment：缓存策略、启动参数、配置文件位置等环境特性
• data-prep：测试数据准备和清理的注意事项
• test-pattern：可复用的测试脚本模式
• bug-pattern：发现的产品代码缺陷模式

9. 更新 test-cases.json

把 passed/failed/blocked 状态写回 test-cases.json，补充每个用例的 result.executedAt 和 result.outcome。

容错与降级

本技能的核心容错逻辑已内嵌在工作流各步骤中（失败三分类、5 次修复迭代、PRE/POST 数据还原、E2E 障碍处理、MySQL MCP 降级）。新增异常场景按以下原则处理：

• 未分类失败：先套用三分类框架（测试bug/产品缺陷/环境问题/基础设施bug/需求歧义），无法归类 → blocker
• MCP 全部不可用：所有 task 标记 blocked，不降级为"手动验证通过"
• 编码损坏：所有产物必须通过 check-mojibake --strict

禁令

• 不在 completion gate 失败时说全部通过 / QA 完成。completion 失败就是未完成，下游不能判 Ready。
• 不把 passed 的 gate 当作"所有业务用例自动通过"。gate 只是流程证据。
• 不给没有映射和证据的 task 标记 passed。每条 passed task 必须有 targetFile/testName/command 和非空 evidence。
• passed 的 evidence 必须是真实执行输出（含断言 PASS/FAIL 行），禁止用「手动验证/手动核对」冒充真实执行——「手动 MCP 核对通过」不算 passed。
• blocked 必须先做数据侦察再标：数据类阻塞（缺数据/账号/资产/余额/跨日）必须先跑 SELECT 侦察，把侦察结果（查询 + 实际返回行数）写进 blocker；没侦察过就标 blocked 是偷懒，assert-completion 会判 blocked-task-missing-evidence。
• 一个用例必须至少一个 task 真实执行通过才算 verified。全部 task 都 blocked/未实现的用例 = 未验证，assert-completion 会判 case-not-verified（fail），不允许 complete_with_allowed_gaps。
• 不用 --allow-blocked / --allow-deferred / --allow-skipped 除非每条受影响的 task 有 blocker/证据-或-备注/owner/nextAction。
• 任务执行中被产品 bug 阻塞时不要 bypass，记录为 blocker 并继续执行不受影响的剩余 task。
• 禁止以"前端代码无变更"为由不执行 E2E task。E2E 验证的是运行时行为（弹窗、登录态、网络请求），不是静态代码。源代码没变不等于运行时环境没变（新增弹窗、缓存策略调整等），必须重新在真实浏览器中跑一遍。
• E2E 用例必须走真实 UI 操作。禁止用 browser_evaluate 直接调用 API 代替点击/输入/导航。弹窗遮挡就关弹窗，元素不可点击就 scroll/wait，应用层有缓存就调接口刷新——修环境，不降级测试方式。
• 不临时变更 spec-task 的 layer 或断言。如果 API 层 task 跑不过，不能降级为"手动验证通过"。如果 E2E 层 task 跑不过，不能绕过浏览器改用 curl。计划是什么 layer，就用什么 layer 执行。如果环境确实不支持（如 E2E 依赖 Playwright 但不可用），标记 blocked 并记录原因，不偷偷换方案。首次执行和回归执行同等约束。
• E2E task 无独立脚本时的处理：若 targetFile 为 "Playwright MCP 真实浏览器操作（无独立脚本文件）" 且 Playwright MCP 不可用，标记 task 为 blocked，在 blocker 中写 "E2E 脚本缺失 + Playwright MCP 不可用"，在 nextAction 中写 "需生成独立 E2E 脚本到 tests/e2e//，使用 playwright 包直连浏览器（不依赖 @playwright/test runner）"。不要现场手写 E2E 脚本凑数——这属于脚本生成阶段的职责。