debugging-codeceptjs-tests

调试 CodeceptJS 4 测试

失败信息会骗人——错误通常指向更早某个操作产生的副作用（身份验证过期、未切换框架、网络调用仍在等待）。先复现并捕获状态，再读取状态，然后修复问题。

路径

• MCP 优先（AI Agent）：run_test / 测试内的 pause() 会在测试使用的同一个 I / 浏览器上，将控制权交给 Agent。通过 run_code / snapshot 检查；通过 run_step_by_step + continue 逐步执行。
• CLI 后备方案（人工 / CI / 框架内部）：依次使用 --debug → --verbose → DEBUG="codeceptjs:*"。只有怀疑框架内部问题时才使用 DEBUG 应急方案：Recorder 卡住、插件竞争、事件泄漏、“步骤从未运行”。命名空间：codeceptjs:recorder、codeceptjs:pause、codeceptjs:ai、codeceptjs:plugin:<name>。

pause() 会根据操作者调整行为：TTY → readline REPL；MCP → 将控制权交给 Agent；非 TTY、非 MCP 子进程 → 打印提示并返回（避免 CI 陷入死锁）。

工作流

1. 基础知识 — 运行 codeceptjs-fundamentals：helper、插件（aiTrace、screenshot、pageInfo、retryFailedStep、pause、auth）、环境变量、MCP 可用性。如果未声明 aiTrace，只需添加一次：plugins: { aiTrace: { enabled: true } } — 此技能的大部分内容都依赖它的输出。

   • 只声明一次；切勿通过编辑配置来更改其触发条件。 按次运行时使用 -p aiTrace:on=step|fail|test|file|url 覆盖（fundamentals § Plugins from CLI）。精简 CI 复现时用 on=fail，诊断时用 on=step。在配置中切换 on: 会造成仓库变更，并影响其他运行。

2. 尽可能精简地复现：npx codeceptjs run --grep '<scenario>' --steps。如果是 CI 特有问题，添加 -c codecept.ci.conf.js。开始插桩前先确认能够复现。

3. 选择工具：

   • MCP run_test <test> — 在进程内运行；返回 reporter 结果，或 { status: 'paused', pausedAfter, page, suggestions }
   • MCP run_step_by_step + continue — 每一步后暂停；适用于观察完整流程
   • MCP run_code — 在实时会话中运行任意代码；无论会话刚启动还是已暂停都适用；返回生成的值、控制台输出和最终状态快照
   • MCP snapshot — 不执行操作，获取当前浏览器状态（URL、Cookie、存储、HTML、ARIA、截图、控制台）
   • MCP list_actions — 检查某个 I.* 方法是否存在
   • CLI npx codeceptjs run --grep '<scenario>' --debug — 不使用 MCP 时的首选操作；--verbose 会额外显示 promise 队列、重试和超时日志

4. 断点：

   • 测试内的 pause() — 适用于已在编辑代码，或要在 within/循环/hook 中暂停的情况
   • 在 run_test 上设置 pauseAt: N — 无需编辑测试；在第 N 个叶子步骤后暂停
   • 查找 N：npx codeceptjs dry-run --debug --grep '<scenario>' --numbers --no-ansi（从 1 开始，每个测试单独编号；填写要停止在其后的行号）
   • 暂停期间：使用 run_code 检查，通过 snapshot 捕获干净状态，在 output/trace_<TestName>_<hash>/trace.md 中查看之前的步骤，并用 continue 恢复

5. 阅读跟踪记录 — 交由 codeceptjs-run-analysis 处理；重点关注第一个失败的步骤——后续失败通常是更早出现的静默遗漏所造成的副作用。它还涵盖如何搜索大型 HTML、对多个跟踪记录中的错误进行聚类，以及比较重新运行的结果。

6. 提出假设：

   症状	可能原因
   找不到元素，页面为 /login	Auth：会话缓存过期、缺少环境变量
   元素在 HTML 中，但 display: none	使用了 waitForVisible，而不是 waitForElement
   定位器匹配到 2 个或更多元素（严格模式）	缩小范围：先用 context 参数，再用 ARIA role，最后用 step.opts({ elementIndex })
   元素在截图 N+1 中出现，但在 N 中缺失	动画 / 延迟加载 → waitForVisible(loc, t)
   console.json 中出现 401/403	API token 过期或缺少环境变量
   步骤通过，接下来的 I.see 失败	未切换到对应框架 → within({ frame })
   CI 与本地结果不同	setHeadlessWhen(CI)、视口、时序、环境变量
   Recorder 卡住，步骤始终未触发	DEBUG="codeceptjs:recorder"
   插件行为异常	DEBUG="codeceptjs:plugin:<name>"

7. 在实时页面上验证修复 — 在编辑文件之前，通过 run_code 尝试候选替代步骤（暂停期间也适用，并使用同一个 I）。在 TTY 中工作的用户可通过测试内的 pause() 达到相同效果。

8. 应用修复并重新运行：编辑后运行 npx codeceptjs run --grep '<scenario>' --steps；通过 codeceptjs-run-analysis 确认失败没有转移到其他步骤。如果修复中引入了 waitFor* 或 step.opts，请留下单行 Why: 注释——这些注释值得保留。

使用 codeceptq 查询跟踪 HTML

aiTrace 会为每个步骤写入 <NNNN>_<step>_page.html 快照（每行一个元素——行号与元素一一对应）。codeceptq 可针对已保存的快照解析任意 CodeceptJS 定位器。

• 不要手动将页面 HTML 加载到上下文中——快照有数千行；codeceptq 只会返回匹配的元素及其行号。
• 在通过 run_code 应用定位器前，先离线测试候选定位器——命中意味着可以尝试实时操作，但不保证成功（可见性、重新渲染等因素仍会影响结果）。
• 如果有多个匹配项，不要编写更脆弱的 XPath；应按 codeceptq 的输出顺序，使用 step.opts({ elementIndex }) 消除歧义。

npx codeceptq '#submit-btn' --file output/trace_*/0007_*_page.html     # CSS
npx codeceptq 'Email' --field --file output/trace_*/0003_*_page.html   # semantic field
npx codeceptq 'Save' '.modal' --click --file output/trace_*/0005_*_page.html  # scoped clickable
npx codeceptq 'Username' --field --json --file ...                     # machine-readable

关键标志：--field/--click/--checkable/--select 强制使用语义策略；--xpath/--css 覆盖自动检测（像 select.foo 这样的裸标签名会被视为模糊文本）；退出代码：0 匹配 / 1 无匹配 / 2 输入无效。

⚠ 第二个位置参数 [context] 不会限定范围（CodeceptJS 4.1.0）。它会输出 N matches within '<ctx>'，但返回的是整个页面的结果——lib/command/query.js 会针对上下文节点计算绝对 XPath（//…），而 //foo 会重新以文档为根。因此，即使容器中没有该元素，它也会报告容器内有匹配项。若要离线检查限定范围的定位器，请传入一个组合选择器（codeceptq '.modal button[aria-label="Save"]'），并将其匹配数量与不限定范围的形式进行比较；只有运行步骤，才能真正验证依赖上下文的定位器。

深入检查

如果跟踪说明了什么操作失败，但你需要更多页面状态信息（“这个按钮真的被禁用了吗？”“真的有两个 Save 按钮吗？”），请交由 codeceptjs-exploration 处理。针对调试的进一步检查：

• 按钮已渲染，但点击无效 → 使用 grabWebElement('Submit') + isEnabled() + getBoundingBox()（是否被禁用？是否在屏幕外？）
• 严格模式下出现多个匹配项 → 使用 exploration 的广泛 XPath 迭代并消除歧义模式
• iframe 内容 → 将失败步骤包装在 within({ frame }) 中

检查时优先采用此方式，而非 usePlaywrightTo/useWebDriverTo——不同辅助函数使用相同代码，样板代码更少。

原生辅助函数的应急方案

仅当 I.* 接口确实无法满足需求时使用（网络拦截、存储操作、仅限辅助函数的 API）：

• Playwright：I.usePlaywrightTo('label', async ({ browser, browserContext, page }) => { ... })
• Puppeteer：I.usePuppeteerTo('label', async ({ page }) => { ... })
• WebDriver：I.useWebDriverTo('label', async ({ browser }) => { ... })

标签会显示在步骤输出和跟踪中。在 MCP run_code 中也可使用。这会让测试与特定辅助函数耦合——仅作为最后手段。

辅助函数注意事项

• Playwright：strict: true 在有多个匹配项时会抛出异常；优先使用 'load'/'domcontentloaded'，而非 'networkidle'；trace: 'on' → output/trace.zip（npx playwright show-trace）
• Puppeteer：长轮询页面上的 'networkidle0' 会一直挂起——请使用 'networkidle2' 或 'domcontentloaded'
• WebDriver：smartWait 仅适用于操作，不适用于断言；executeScript 的参数必须可序列化为 JSON

身份验证相关故障

测试过程中重定向到 /login，或控制台出现 401/403 → 修复身份验证，而不是失败的步骤：检查插件的 check、凭据环境变量，以及 output/<role>_session.json 中过期的缓存会话（删除该文件以强制重新登录）。完整模式见 codeceptjs-auth。

不稳定问题与等待

大多数“间歇性”故障都是因为遗漏等待。使用跟踪 HTML/ARIA 找出实际的门控元素，而不是添加通用延迟（fundamentals § Waiting 中介绍了对应关系）。调试时使用 I.wait(N) 可验证对时序的推测——提交前应将其替换为具体的 waitFor*。

应避免的做法

• 不阅读跟踪信息，只根据错误消息修复问题。
• 未通过 run_code 验证修复效果，就编辑测试。
• 提交 pause() 调用——它仅用于调试。
• 盲目使用 waitFor*，而不找出真正的拦截元素。
• 在已提交的测试中留下 I.wait(N)。
• 在不同运行之间编辑配置中的 aiTrace 的 on:——只声明一次，并在每次运行时覆盖。
• 跳过配置检查——setHeadlessWhen(CI) / 由环境变量驱动的 URL 能解释许多“本地运行正常，CI 中失败”的情况。
• 用 retries 隐藏失败，而不是修复根因。

相关技能

• codeceptjs-fundamentals — 副作用、通过 CLI 加载插件、等待规则
• codeceptjs-exploration — 检查 WebElement、消除宽泛 XPath 的歧义
• codeceptjs-run-analysis — 阅读 trace.md、错误聚类、比较重新运行结果
• codeceptjs-auth — 身份验证失败模式