testplane-skill

Testplane 技能

Testplane 是基于 Mocha 和 WebdriverIO 的浏览器自动化工具和测试运行器。使用此技能检查真实浏览器状态、调试失败的报告，并按照项目约定编写或修复 Testplane 测试。

初始化

运行此技能中的命令之前，先确定包含此 SKILL.md 的目录，并将其用作 $SKILL_DIR。

一次性设置：

cd $SKILL_DIR && npm run setup

快速检查：

node $SKILL_DIR/scripts/index.js

尽可能从 $SKILL_DIR 运行 @testplane/cli，以便复用已安装的软件包：

cd $SKILL_DIR && npx @testplane/cli --help

核心规则

• 优先使用项目中现有的脚本、配置、辅助工具、页面对象、测试夹具和自定义命令。
• 优先使用从应用或报告中发现的真实选择器，而非猜测选择器。
• 优先使用稳定的选择器：测试 ID／数据属性、语义选择器、稳定的 ID／名称，然后再使用备用 CSS 选择器。
• 优先使用 @testplane/cli snapshot，而不是截图。仅在需要视觉证据时使用截图。
• 不要使用 browser.pause() 修复测试。应等待明确的页面状态、文本、URL、元素可见性／存在性或特定应用结果。
• 除非用户明确提供，否则绝不读取机密、凭据、.env 文件、原始 Cookie、令牌或私有身份验证材料。请使用现有的身份验证辅助工具或浏览器状态文件。
• 如果用户提供了 Testplane HTML 报告的路径或 URL，请先检查报告，再修改测试。
• 如果命令语法不明确，请运行 npx @testplane/cli --help 或 npx @testplane/cli <command> --help。

使用 @testplane/cli 探索浏览器

需要查看应用的渲染结果、发现选择器、验证身份验证状态，或在编写／修复测试前了解行为时，请使用此方法。

cd $SKILL_DIR
npx @testplane/cli navigate http://localhost:3000
npx @testplane/cli click --role button --name "Save"
npx @testplane/cli snapshot

常用命令：

• navigate <url> --timeout 60000：打开页面；如有需要，会自动启动浏览器。
• snapshot：捕获精简的 DOM 快照；较大的快照会保存到临时文件中。
• click、hover、type、select、wait：与真实元素交互。
• console：读取基于 Chromium 的会话中尚未查看的浏览器控制台消息。
• run-code：在没有合适内置命令时执行 Testplane／WebdriverIO 代码。
• list-tabs、new-tab、switch-tab、close-tab：操作标签页。
• attach --session <json>：连接到运行 Testplane 并使用 --keep-browser 后打印的浏览器 JSON。
• --session-name <name>：为不同流程保留独立的浏览器会话。

探索流程：

1. 导航到相关浏览器状态，或连接到该状态。
2. 执行一个针对性操作。
3. 每当状态发生重要变化后，捕获快照。
4. 在测试中使用已发现的选择器和可见行为。

除非需要自定义浏览器配置，否则请避免使用 launch。navigate 等常规命令会自动启动浏览器。

根据 Testplane 报告调试

用户提供本地或远程 Testplane HTML 报告时，请先使用此工作流。远程报告 URL 会由 CLI 自动下载并缓存。

cd $SKILL_DIR
npx @testplane/cli test-results <report> --status failed --fields name,status,browser,attempt,duration,file,error
npx @testplane/cli inspect-result <report> --name "full test name" --browser chrome --attempt 0

报告工作流：

1. 使用 test-results 列出失败项；必要时添加 --grep、--browser、--duration、--grep-error、--meta key=value 或 --file。
2. 使用精确的 name、browser，以及可选的 attempt，通过 inspect-result 检查具体结果。
3. 编辑代码前，先阅读状态、错误、步骤、元数据、图片和附件。
4. 如果结果包含 Time Travel 快照附件，请使用 time-travel-snapshot 检查。
5. 然后再判断问题出在测试代码、应用行为、身份验证／环境、时序还是视觉基线数据。

对于大量结果，请保存结构化 JSON：

npx @testplane/cli test-results <report> --status failed --save-json

检查时间旅行快照

当报告包含 Testplane Time Travel 数据或用户提供了快照 zip 时，使用 time-travel-snapshot。它会重放 rrweb 录制内容，并返回所选时间点的 DOM 快照。

npx @testplane/cli time-travel-snapshot <report> \
  --name "full test name" \
  --browser chrome \
  --attempt 0 \
  --time 1400

提示：

• 输出会列出带偏移量的测试步骤；将这些偏移量用作 --time 值。
• 使用 --diff-from <time> 比较两个时间点，并聚焦于发生变化的 DOM 节点。
• 默认快照遗漏有用细节时，使用 --include-attrs data-qa href class 或 --max-text-length 200。
• 直接检查快照时，使用 --snapshot-file /path/to/snapshot.zip --time 100。

当测试期间浏览器进入异常状态，且实时会话已结束时，这尤其有用。

使用 Testplane REPL 调试

当运行中的测试已将浏览器带入需要检查的状态时，REPL 模式很有用。它让你留在项目运行环境中，因此 Agent 可以使用已有的页面对象、自定义命令、测试夹具和辅助函数，而不必通过原始选择器重新构建行为。

连接到现有的 Testplane REPL 会话：

cd $SKILL_DIR
npx @testplane/cli attach-repl --port 4444

目前，REPL 会话仅支持两种 CLI 操作：

npx @testplane/cli snapshot
npx @testplane/cli run-code "await browser.getUrl()"

使用 run-code 执行适配项目的代码片段，例如调用测试进程中已加载的辅助函数。click、type 和 wait 等其他交互命令目前尚不支持 REPL 模式。

安全处理身份验证

优先使用现有的登录辅助函数或测试夹具。需要复用浏览器状态时，使用 save-state 和 restore-state，而不要读取机密信息。

cd $SKILL_DIR
npx @testplane/cli save-state ./tmp/auth-state.json
npx @testplane/cli restore-state ./tmp/auth-state.json

注意：

• 状态可以包含 Cookie、localStorage 和 sessionStorage。
• 命令输出会报告数量，不会显示 Cookie 值。
• 保存的文件可能包含真实的身份验证材料；除非用户明确要求，否则不要打印、提交或检查该文件。
• 使用 --cookies false、--local-storage false 或 --session-storage false 等选项，只保存所需内容。
• restore-state 默认会刷新页面，以便应用代码读取恢复后的状态。

运行并修复现有测试

使用范围最小且可复现的命令。

npx testplane --grep "Check search field presence"
npx testplane tests/login.testplane.ts

如果 package.json 中有脚本，优先使用这些脚本：

npm run test:e2e -- --grep "Check search field presence"

检查清单：

1. 找出能够复现问题的最小命令。
2. 阅读测试以及附近的辅助函数、页面对象和测试夹具。
3. 如果有报告，先检查报告。
4. 如果浏览器行为不明确，使用 CLI 快照或 REPL。
5. 使用明确的等待条件和已确认的选择器，替代休眠等待和猜测的选择器。
6. 区分测试问题、应用问题、视觉基准问题、身份验证状态和环境故障。

如果应用只有在测试期间才会进入需要检查的页面，并且有 --keep-browser 选项，则使用该选项运行，然后连接到输出的浏览器会话 JSON：

npx @testplane/cli attach --session '{"sessionId":"...","capabilities":{...}}'
npx @testplane/cli snapshot

编写新测试

从头编写之前，尽可能先探索真实应用。

1. 确认项目脚本、配置、浏览器设置和本地应用启动方式。
2. 使用 @testplane/cli 打开目标路由。
3. 捕获快照，并审慎选择选择器。
4. 复用现有的辅助函数、页面对象、身份验证、清理逻辑和断言模式。
5. 断言用户可观察到的结果，而不是实现细节。
6. 使用明确的等待条件，确保测试具有确定性。

视觉测试：

• 仅在行为涉及视觉效果时使用 assertView。
• 截图前稳定动画、加载状态和动态内容。
• 不需要视觉覆盖时，优先使用 DOM 断言。