writing-codeceptjs-tests

编写 CodeceptJS 4 测试

编写时从未执行过的测试并不可靠。通过 CodeceptJS MCP 服务驱动真实浏览器，在实时页面上验证每个定位器，只提交已通过的步骤。

根据你对流程的了解程度，选择两种模式之一：

• 模式 A — 增量 run_code：每次调用发送一两行 I.*，读取响应后重复。适用于扩展现有测试、熟悉的流程以及移植手动计划。
• 模式 B — 搭建脚手架后暂停（推荐用于全新项目或未知流程）：编写一个包含 I.amOnPage('/...'); pause(); 的占位 Scenario，通过 MCP run_test 运行。浏览器打开后会在 pause() 处暂停并交出控制权；通过 run_code 操作实时页面，然后用已验证的步骤替换 pause()。

两种模式共用相同的发现、定位器和提交步骤；区别在于进行中的探索发生在哪里。

工作流

1. 先掌握基础知识 — 运行 codeceptjs-fundamentals。你需要：已启用的 Web 助手、基础 URL、插件（aiTrace、auth）、AI 提供商、页面对象、环境变量。
2. 了解现有内容 — 使用 check / list / dry-run（参见 fundamentals § Discover）。这有助于发现重复内容，并确认计划中的流程尚未由自定义步骤或页面对象方法覆盖。
   • ⚠ dry-run 不会初始化插件：即使实际运行正常，Before(({ login }) => login('admin')) 在 dry-run 下也会报错，提示 "login is not a function"。使用 --steps 检查结构；忽略插件注入错误；通过实际运行验证身份验证。
3. 身份验证 — 登录后才能访问的路径 → 调用 codeceptjs-auth 技能。已配置角色：Before(({ login }) => login())。未配置：身份验证技能会指导你添加配置。公开路径：跳过。
4. 类似测试和页面对象 — 扫描功能区域中的 Scenarios、include 下的 POs、actor 文件中的自定义步骤以及数据工厂。如果某个 PO 方法已封装该区域的定位器，就通过它操作，而不要直接串联 I.click。
5. 起始页面 — 必须是身份验证完成后的真实 URL，不能猜测；如果未知，请询问用户。仅使用相对 URL — 主机地址由配置指定（例如 helpers.Playwright.url）。
6. aiTrace + MCP 接线：
   • MCP 模式：MCP 服务会强制启用 aiTrace — 无需配置。
   • CLI 运行：不会自动启用 — 在配置中声明或传入 -p aiTrace，否则第 11 步不会生成供运行分析使用的 output/trace_*/ 产物。
   • 默认以无头模式运行（导出 CI=1 并使用 setHeadlessWhen(CI)，或设置 show: false）。
   • 确认 MCP 客户端指向 node_modules/codeceptjs/bin/mcp-server.js，并已设置 CODECEPTJS_CONFIG 和 CODECEPTJS_PROJECT_DIR。
7. 启动实时会话（选择一种模式）：
   • 模式 A：使用 run_code 搭建脚手架 — 如有需要，先执行 login(<role>)，然后执行 I.amOnPage(<start URL>)。响应内容（URL、ARIA 快照、屏幕截图、控制台）是之后所有操作的事实依据。
   • 模式 B：在测试文件中编写精简但真实的草稿：

     Before(({ login }) => login('admin'))   // 如有需要
     
     Scenario('draft - feature exploration', ({ I }) => {
       I.amOnPage('/dashboard')
       pause()
     })
     

     通过 MCP run_test 运行 → { status: 'paused', pausedAfter, page, suggestions }。此时，测试自身的 I / 浏览器由 run_code 驱动。
8. 了解页面 — 交由 codeceptjs-exploration 处理：先查看 ARIA 快照，必要时回退到 HTML；枚举并区分候选项；只有在通过 run_code 验证定位器恰好匹配一个元素后，才提交该定位器。模式 B 下，这些操作在暂停期间进行。
9. 构建 Scenario — 每次通过 run_code 向暂存区添加一到两条命令。每次之后都要确认：URL/ARIA 是否按预期变化？是否出现新的控制台错误？获取的值是否符合预期？
   • 步骤失败 → 尝试其他定位器，添加具体的 waitFor*，或重新考虑流程。
   • 确实存在歧义（两个 Save 按钮、空状态不明确、可能有功能开关）→ 停止并询问用户。
   • 可选的 UI 元素（如 Cookie 横幅）→ 使用 await tryTo(...)，而不是 if（fundamentals § Effects）— 让 Scenario 保持线性。
10. 提交已验证的序列：
    • 遵循现有命名规范；每个文件使用一个 Feature。
    • 适用时使用页面对象方法 / 自定义步骤 — 不要重复定义选择器。
    • 将每个定位器转换为易读形式（优先级见下文）。除非没有其他合适方式，否则提交代码中严格使用 { css } / { xpath } 是审查警示信号。
    • 凭据只能来自环境变量，并使用 secret(...) 包装。
    • 模式 B：将 pause() 行替换为操作序列；将 draft - ... 重命名为实际意图。
11. 最终验证：启用 aiTrace 后运行 npx codeceptjs run --grep '<scenario>' --steps → 将输出交给 codeceptjs-run-analysis，确认流程在 output/trace_*/ 中运行成功。只有在此处通过后才算完成。

定位器优先级（编写时）

始终传入上下文——原因见 codeceptjs-fundamentals § Locators。优先级从高到低：

1. 语义字符串——可见文本、标签、占位符、name、aria-label：I.click('Save', '.toolbar')
2. ARIA 角色——上下文中的文本有歧义（例如既有“Delete”链接又有“Delete”按钮），或断言中包含角色：I.click({ role: 'button', name: 'Sign In' }, '#login-form')
3. 通过 customLocator 使用 $name——应用广泛提供 data-testid/data-qa
4. locate() 构造器——结构条件；结构部分通常适合作为上下文：I.click('Edit', locate('tr').withText('Acme Corp'))
5. 严格的 { id } / { name } / { css }——以上方法都不适用时的最后手段
6. { xpath }——构造器无法表达的轴或文本谓词

编写时除基础规则外还需注意：

• 普通字符串已经会匹配 aria-label——切勿写成 'aria-label=Save' 或 { css: '[aria-label="Save"]' }。
• 优先使用稳定的上下文：页面区域（nav、main、{ role: 'dialog' }）、应用外壳容器（.sidebar、.modal）、通过数据识别的行或卡片。
• I.see / I.dontSee 需要上下文——第一个参数是会在整个页面中匹配的普通文本；不限定范围时，导航栏或页脚中的内容可能导致误判通过。
• 匹配到多个元素时，使用 step.opts({ elementIndex: N })（从 1 开始、负数、'first'/'last'）或 step.opts({ exact: true })；从 codeceptjs/steps 导入 step。

编写时等待

• 自动等待会处理交互；在 MCP 步骤之间通过实时 HTML/ARIA 检查门控元素（加载旋转图标覆盖层、数据获取后的渲染）→ 选择稳定的选择器和具体的 waitFor*。
• 编写时可以接受使用 I.wait(N) 来验证对时序的假设——如果添加睡眠后步骤通过，说明原因是时序问题。提交前应替换为具体的 waitFor*。

应避免的事项

• 根据想象编写定位器或路由——所有内容都应来自实时页面。
• 在语义定位、ARIA 定位或 locate() 适用时使用严格定位器。
• 使用冗长且未限定范围的定位器，而非简短的定位器加上下文。
• 拼写出可访问名称，或在调用处重复写 [data-testid=...]。
• 在任何位置硬编码凭据。
• 跳过相似测试 / 页面对象检查。
• 对普通操作步骤使用 await（基础规则中的 await 规则）；尚未检查自动等待行为前就臆测并添加 waitFor*。
• 在已提交的测试中保留 I.wait(N) 或 pause()。
• 对于流程确实未知的情况使用 Mode A——它比 Mode B 慢，也更容易丢失状态。
• 未运行端到端 aiTrace 就宣告完成。

相关技能

• codeceptjs-fundamentals — 规则、影响、探索（先运行）
• codeceptjs-exploration — 页面检查、WebElement API
• codeceptjs-auth — 登录 / 会话复用
• codeceptjs-run-analysis — 跟踪验证
• debugging-codeceptjs-tests — 已提交的测试行为异常时使用