Auto QA (OpenClaw Browser)

用于一期 MVP：

• - 自动执行网页关键路径
• 自动采集失败证据（截图、console、network、trace）
• 自动输出 CTO 可读报告与修复任务包
• 自动重试、断点续跑、健康检查与失败分类（环境/产品）

实际组件构成（一期 MVP）

1. 1. INLINECODE0

• - 位置：INLINECODE1
• 作用：声明测试步骤、断言条件、期望结果。
• 输入：业务路径（P0 场景）。
• 输出：可执行步骤序列（供执行编排器读取）。

1. 2. INLINECODE2

• - 位置：INLINECODE3
• 作用：读取场景并调用 openclaw browser 执行动作。
• 输入：场景 JSON、浏览器 profile、run_id。
• 输出：步骤结果、证据文件、汇总报告与修复提示包。

1. 3. INLINECODE5

• - 位置：OpenClaw CLI INLINECODE6
• 作用：点击、输入、等待、快照、截图、日志与 trace。
• 输入：编排器下发的步骤参数。
• 输出：结构化 JSON 结果和调试数据。

1. 4. INLINECODE7

• - 位置：INLINECODE8
• 作用：按 run 归档步骤明细、截图、console、network、trace。
• 输入：执行过程中的实时证据。
• 输出：可追溯的失败证据包。

1. 5. INLINECODE9

• - 位置：demo/reports/run-<run_id>/report.json、INLINECODE11
• 作用：给出通过率、阻断项、Go/No-Go 判定。
• 输入：步骤结果 + 证据统计。
• 输出：机器可读（JSON）与演示可读（HTML）报告。

1. 6. INLINECODE12

• - 位置：demo/reports/run-<run_id>/fix_plan.json、next_window_prompt.md、INLINECODE15
• 作用：将"测试失败证据"转成"可直接执行的修复任务"。
• 输入：失败步骤、console、network、trace 路径。
• 输出：根因假设、检查方向、修改方向、验收标准、下一窗口提示词。

1. 7. INLINECODE16

• - 位置：INLINECODE17
• 作用：减少"主画面外运行"时的抖动风险，提升演示稳定度。
• 能力：

- 步骤自动重试（默认每步 1 次重试） - 断点续跑（从失败步骤继续） - 健康检查（off/on-failure/each-step） - 失败分类（environment/product/unknown）

1. 8. INLINECODE18

• - 位置：INLINECODE19
• 作用：将采证数据升级为发布门禁判定，防止"假 GO"。
• 默认规则：

- console error -> 违规（critical） - 同域 network 4xx -> 违规（critical） - 同域 network 5xx -> 违规（blocker）

• - 报告输出：

- gateViolations - gateViolationCountsBySeverity - riskLevel - releaseDecision（GO / CONDITIONALGO / NOGO） - reviewStatus（consistent / needs_inspection） - reviewConclusion（复核一致 / 复核需进一步检验） - reviewFindings（需进一步检验时的具体项）

1. 9. INLINECODE30

• - 位置：INLINECODE31
• 作用：把步骤时间窗与 trace 时间线自动对齐，便于"步骤 -> 证据"快速追溯。
• 输出：每个步骤对应的 trace 事件计数、帧计数、console/API/network 样本。

1. 10. INLINECODE32

• - 位置：src/skills/auto-qa/scripts/run_autoqa.py（运行参数触发）
• 作用：自动截取 report.html 全页图并发送到聊天频道。
• 规则：

- 传入 --notify-channel 时触发。 - 未传 --notify-target 时，自动从 openclaw status --json 最近会话推断目标（当前频道优先）。

一期范围（防跑偏）

• - 仅网页 P0 场景（3-5 条关键路径）
• 证据四件套：INLINECODE38
• 交付最小集合：

- report.json - report.html - fix_plan.json - next_window_prompt.md - INLINECODE43

目录约定

CODEBLOCK0

场景 JSON（最小格式）

CODEBLOCK1

场景 JSON（门禁规则示例）

CODEBLOCK2

场景 JSON（动作展示配置示例）

CODEBLOCK3

说明：

• - focusTabBeforeStep：每步前尽量聚焦受控 tab，减少后台节流导致的观感抖动。
• INLINECODE45：动作前后节奏等待，提升"可见点击/跳转"观感。
• INLINECODE46：动作前高亮目标元素。

支持动作（MVP）

• - INLINECODE47
• INLINECODE48
• INLINECODE49
• INLINECODE50
• INLINECODE51
• INLINECODE52
• INLINECODE53
• INLINECODE54
• INLINECODE55
• INLINECODE56
• INLINECODE57
• INLINECODE58
• INLINECODE59
• INLINECODE60
• INLINECODE61
• INLINECODE62

场景 JSON 校验层（安全网）

INLINECODE63 在加载 scenario 时自动执行 pre-flight 校验：

1. 1. JSON 语法：解析失败会报告精确行号/列号
2. 必须字段：每个 step 必须含 action 字段
3. 动作白名单：action 值必须在上述"支持动作"列表内，否则报错并列出全部合法值
4. 参数完整性：open/navigate 须含 url；click/hover/type 须含 ref；assert_* 须含 INLINECODE74

校验在执行前触发，出错时给出明确的 step 索引和原因——不会默默失败。

生成 scenario 时请确保遵守上述约束。id 字段建议保留（格式 step-NNN），缺省时引擎会自动补全。

场景 JSON（探索配置与返回边覆盖）

CODEBLOCK4

说明：

• - depth：步骤所属探索层级（用于覆盖统计）。
• INLINECODE78：该步骤计入"返回边"覆盖统计（back 动作默认计入）。

运行方式

在仓库根目录执行：

CODEBLOCK5

执行协议（强约束）

当用户表达"跑 QA / 再测一次 / 做自动回归 / 开始测试"等执行意图时，默认进入直接执行，不先回复"计划确认"。

场景生成优先级（核心规则 — 严格按此顺序执行）

正常流程不使用预设脚本。场景（scenario）应由 agent 智能生成。

优先级 1：用户给了测试要求（自然语言）

用户可能说："测一下登录功能"、"检查购物车流程"、"用以下用例做自动 QA 测试：……"。

agent 必须：

1. 1. 用 openclaw browser open <url> 打开目标
2. 用 openclaw browser snapshot --interactive --labels 扫描页面结构
3. 理解用户的自然语言要求，对照页面上实际存在的元素（表单、按钮、链接、输入框等）
4. 生成包含用户所有要求的 scenario JSON（每条要求对应具体的 action + expected + assertion）
5. 将 scenario JSON 写入 INLINECODE82
6. 用 --scenario <path> --force-direct-scenario-path 执行

严禁忽略用户的任何测试要求。 如果页面上找不到用户要求的元素，在 scenario 中仍要包含该步骤并标注 expected，让执行引擎报告失败——而不是静默跳过。

优先级 2：用户只给了 URL，没有具体要求

agent 必须：

1. 1. 用 openclaw browser open <url> 打开目标
2. 用 openclaw browser snapshot --interactive --labels 扫描页面结构
3. 分析页面上的所有可交互元素：链接、按钮、表单、输入框、导航菜单等
4. 智能生成覆盖以下维度的 scenario JSON：

- 页面可访问性（navigate + assert_url） - 核心可交互元素（click 按钮、填写表单、点击链接） - 导航完整性（跳转 + 返回） - 内容断言（asserttextcontains 关键文案）

1. 5. 将 scenario JSON 写入 demo/scenarios/_generated/<run-id>.json 并执行
2. 执行完成后，BFS 探索引擎自动补充未覆盖的同域页面

生成的 scenario 必须基于实际页面内容，不能凭空猜测。 每个 step 的 ref、url、text 必须来自 snapshot 的真实数据。

优先级 3（极端后备）：snapshot 失败或浏览器不可用

仅当以上两种方式都失败时（如浏览器无法启动、目标不可达），才回退到预设脚本：

• - 使用注册表默认 defaultScenarioId 或 INLINECODE88
• 必须向用户明确警告："无法扫描目标，已回退到通用模板，测试覆盖度有限"

预设脚本（scenario-id）仅用于以下场景：

• - 用户明确要求使用某个 scenario-id（调试/演示用途）
• 浏览器/网络故障导致无法扫描目标
• 开发者本地调试

频道与目标策略

• - 不做固定频道硬编码；频道可变且应随会话上下文切换。
• 未显式指定通知目标时，沿用脚本默认"最近活跃会话自动推断"能力。

汇报口径

• - 一旦命中执行意图，先回"已开始执行 + 本次 run 参数摘要"，随后立即落地执行。
• 执行完成后再返回报告路径与结论，不把"执行前计划说明"作为前置阻塞。

常用参数：

• - --scenario <path>：直传 scenario JSON 路径（需配合 --force-direct-scenario-path）
• INLINECODE91：从注册表选择场景（仅调试/演示；默认注册表：demo/scenarios/registry.json）
• INLINECODE93：指定场景注册表路径
• INLINECODE94：覆盖场景变量（可重复；用于模板场景的 {{start_url}}/{{start_domain}} 等占位）
• INLINECODE96：允许接收 --scenario <path> 直传请求（默认关闭；默认会回退注册表默认场景）
• INLINECODE98：强制执行直传路径（智能生成场景时必须开启）
• INLINECODE99：手动指定 run id
• INLINECODE100：输出根目录
• INLINECODE101：允许执行仓库 demo/scenarios 目录外的场景（默认关闭，防误跑）
• INLINECODE103：允许执行 meta.legacy=true 的旧场景（默认关闭）
• INLINECODE105：关闭 trace 录制
• INLINECODE106：指定 OpenClaw 可执行名（默认 openclaw）
• INLINECODE108：指定完整命令前缀（例如 pnpm --dir src openclaw）
• INLINECODE110：每步默认重试次数（默认 1）
• INLINECODE112：重试间隔（默认 800）
• INLINECODE114：启用复核执行并与主执行结果对照（默认开启）
• INLINECODE115：复核执行遇到差异后是否继续（默认开启）
• INLINECODE116：复核执行默认重试次数（默认 0）
• INLINECODE118：复核执行重试间隔（默认 500）
• INLINECODE120：复核执行时间预算（默认 90000，超时即提前收口并继续产出最终报告）
• INLINECODE122：从指定步骤开始续跑
• INLINECODE123：从某次历史失败 run 的首个失败步骤续跑
• INLINECODE124：从同一场景最近一次失败 run 自动续跑
• INLINECODE125：健康检查频率（默认 on-failure）
• INLINECODE127：trace 启动时机（默认 auto）
• INLINECODE129：自动发送报告截图到指定频道（支持 discord/.../auto/current，不依赖固定频道名）
• INLINECODE131：频道目标（不传则自动推断最近会话目标）
• INLINECODE132：可选 accountId
• INLINECODE133：可选通知文案
• INLINECODE134：未显式指定频道/目标时，自动发到最近活跃会话（默认开启）
• INLINECODE135：自动推断会话的最大"最近活跃时间"（默认 30 分钟）
• INLINECODE136：运行前自动清理多余 OpenClaw 专用 Chrome 进程（默认开启）

最终形态执行约束（当前实现）：

• - Analysis Pass：无视觉、全量执行、深度固定 3；默认"失败优先截图"（analysisAutoScreenshot=false），保留 console/network/trace 全量采证。
• Showcase Pass：只跑 Analysis 产出的主链路 + 失败链路，并按 trace 对齐复核。
• Showcase Pass 中若场景步骤是 open，复核执行自动改为同 tab navigate，避免额外新开 tab。
• 若两次执行不一致：报告标注 needs_inspection，不阻塞本轮交付。
• 若 Showcase 触发时间预算：标注 partial_timeout，并继续生成 report.html/report_full.png 与回传。

执行超时建议（重要）：

• - 从外层 exec 调脚本时，必须设置 timeout >= 900 秒。
• 300 秒在"analysis + showcase + trace + 通知"组合下容易被外层提前杀掉，导致看起来"截图回传丢失"。

次佳演示模式（同机不抢主画面）

你关心的"炫酷演示 + 不打断主画面工作"建议这样跑：

CODEBLOCK6

说明：

• - 该模式可在同一台机器运行，不要求你一直把测试窗口放在主画面。
• 但若你手动频繁干预同一浏览器窗口，仍会增加波动；重试与健康检查用于兜底并在报告中标注风险归因。
• 在 trace-start-mode=auto 下，若首步是 open/navigate，trace 会延后到第一步后启动，减少 about:blank 首屏干扰。
• 默认会生成报告全页截图（report_full.png，兼容名 report_screenshot.png）。
• 默认会尝试把截图和结论自动发到最近活跃的当前会话频道（可用 --no-notify-auto-current-channel 关闭）。

可视化演示场景（新增）

• - 文件：INLINECODE153
• 特点：包含"首屏截图 -> 下翻 -> 下翻后截图 -> 点击跳转同域目标页 -> 返回首页"的强可视化动作链，适合 CTO 演示。
• 场景 ID：wehub_demo（演示门禁配置，已忽略已知 index.css 404 噪音）
• 严格门禁 ID：wehub_release（发布判定，不忽略已知 4xx）

运行示例（含自动发当前 Discord 频道）：

CODEBLOCK7

泛用模板场景（仅调试/演示用）

• - 文件：INLINECODE157
• 场景 ID：INLINECODE158
• 模板内置变量占位：

- {{start_url}} - {{start_domain}}

• - 注意：正常流程应使用智能生成（优先级 1/2），此模板仅在极端后备或调试时使用。
• 示例：

CODEBLOCK8

失败到修复闭环

• - 失败时自动生成 fix_plan.json：

- 问题摘要 - 高概率根因（含置信度） - 检查方向 - 修改方向 - 验收标准 - 回滚条件

• - 自动生成 next_window_prompt.md：可直接贴到下一窗口执行
• 自动生成 standby_prompt.txt：一句确认即可启动修复流程

最近验证样例（2026-02-20）

• - runId：INLINECODE164
• 报告路径：

- /Users/chikakochou/.openclaw/workspace/demo/reports/run-wehub-gate-sample-20260220-v2/report.json - /Users/chikakochou/.openclaw/workspace/demo/reports/run-wehub-gate-sample-20260220-v2/report.html

• - 结果摘要：

- releaseDecision = NO_GO - riskLevel = high - 门禁违规命中：console error、同域 network 404

Trace 修复记录（2026-02-21）

• - 修复范围：openclaw browser trace start/stop 在嵌套子命令下丢失 --browser-profile 参数的问题。
• 根因：CLI 只读取了一层父命令选项，导致 trace 子命令回退到默认 profile（通常是 chrome）。
• 修复后验证：

- trace start/stop 在 --browser-profile openclaw 下可正常生成 trace。 - AutoQA run wehub-trace-fix-20260221-v1 已验证 tracePath 存在且报告无 trace warning。

工程注意事项

• - 若 openclaw browser 无法连接，请先启动 OpenClaw 网关/浏览器服务。
• INLINECODE177 依赖快照 ref，场景需要提供稳定 ref 或结合 wait/evaluate 先定位。
• 一期先保证可执行和可追溯，不在本阶段引入跨浏览器矩阵和全量性能压测。