codeceptjs-run-analysis

CodeceptJS 运行分析

运行 npx codeceptjs run 后，跟踪产物会保存在 output/ 中。此技能通过 Bash 工具高效读取这些产物——找到正确的步骤、文件，以及大型 HTML 快照中的正确片段，而无需通过 MCP 重新运行。

没有唯一的最终目标：根据具体情况选择对应的用例。基础知识适用于所有用例。

基础知识

• 必须启用 aiTrace。 所有分析都依赖 output/trace_<TestName>_<hash>/trace.md。请在当前配置中确认（如果不确定，请运行 codeceptjs-fundamentals）。若未启用，则只有截图和 pageInfo 转储——建议先启用并重新运行，再进行深入分析。
• run_step_by_step 仅用于交互；aiTrace 是逐步文件的唯一来源。临时运行 run_code / snapshot 仍会在 output/trace_run_code_* / output/snapshot_* 下生成一次性文件包。
• 定位跟踪记录：重新运行会创建新目录——不确定时，取最新的目录（ls -dt output/trace_*）。
• 先读 trace.md——它是索引，链接到每个步骤的产物。
  • 聚焦失败的步骤；若没有标记，则聚焦跟踪记录中的最后一个步骤。
  • 若标记了多个失败，通常第一个才是原因；其余都是连带问题。

目标步骤（NNNN_<step>）的产物读取顺序

产物	何时读取
NNNN_*_aria.txt	首先读取——精简、结构清晰，便于扫描重复项
NNNN_*_screenshot.png	用于视觉确认——布局、动画、“已渲染但不正确”的情况
NNNN_*_console.json	用于查看 JS 错误、4xx/5xx 响应、解释元素消失原因的弃用警告
NNNN_*_storage.json	查看此步骤的 Cookie 和 localStorage——怀疑身份验证时，首先检查这里
NNNN_*_page.html	最后才读取，并且只能通过 grep

切勿完整读取大型文件

• HTML 快照：使用 grep 搜索（文本、class、aria-label、data-*）——行号和上下文标志能让匹配结果更易读。
• console.json：使用 jq 筛选，不要读取每一条记录。
• 扫描多个文件：使用 grep -l 仅获取文件名。

用例

验证修复是否有效

定位最新的跟踪记录 → 阅读 trace.md → 确认没有 FAILED 标记。顺便查看 console.json，留意值得修复的警告。

对 CI 批次中的错误进行归类

从每个 trace.md 提取失败步骤所在行，按特征分组（grep + sort + uniq -c），再按频率排序。

• 多个测试出现相同错误 = 系统性问题（环境变量、身份验证、基础 URL、部署回归）——修复一次根本原因，然后重新运行整个批次。
• 每个测试出现不同错误 = 局部问题——逐个排查。 从最常见的根本原因入手；修复后重新运行，查看多少个测试因此恢复正常。

诊断不稳定问题

将同一测试重新运行 5–10 次；比较每条跟踪记录中失败的步骤。

• 每次运行失败步骤都不同 → 时序、环境或外部服务问题
• 失败步骤相同，但状态不同 → 缺少等待或等待方式有误——对比各次运行中该步骤的 ARIA 快照（使用 diff）
• 各次运行的 console.json 不同 → 后端或网络瞬时错误
• 边界框不同 → 布局重新排版或内容延迟加载

调查单次失败

失败步骤；若没有则选最后一步 → 先看 ARIA 和截图，再看 console，最后看 HTML（仅用 grep）。提出一个假设。若跟踪记录不够，或页面需要实时操作 → 转交给 debugging-codeceptjs-tests。

分析之后

• 系统性原因 → 一次性修复根本原因（环境、身份验证、部署），不要逐个测试修复
• 定位器偏移 → codeceptjs-exploration
• 时序或等待问题 → 参考 fundamentals/writing 技能中的等待指南；用特定的 waitFor* 替换 I.wait(N)
• 静态分析无法解决 → debugging-codeceptjs-tests（实时 MCP 循环）
• 测试通过 → 完成，但仍应顺便查看 console.json

应避免的事项

• 完整读取大型 HTML 或 console.json——使用 grep / jq。
• 停在最后一个标记的失败处，而不是第一个。
• 尚未归类就逐个排查失败。
• 仅凭一次运行就判断存在不稳定问题——至少需要重新运行 5 次。
• 调查期间删除 output/。

相关技能

• codeceptjs-fundamentals — 配置内容、aiTrace -p 覆盖项
• codeceptjs-exploration — 定位器偏移修复
• debugging-codeceptjs-tests — 实时循环 + 通过 codeceptq 离线解析定位器