verify

验证

每项更改发布时都附有来自真实环境的证据。单元测试通过，并不能证明 CLI 打印了正确的行、定位器能在真实页面上找到节点，或 Agent 步骤可以重放。测试台和基准测试就是这里的应用：它们像用户一样使用构建后的包。在整个过程中使用这项技能，而不只是最后才用：更改、构建、运行、查看、重复。

设置

pnpm install --frozen-lockfile
pnpm --filter @e2e-dev/web exec playwright-core install chromium
pnpm build                    # every consumer below runs dist; rebuild after each change

过时的 dist 是最常见的错误结果来源。信任任何运行结果之前，以及切换分支之后，都要重新构建。

选择验证面

更改	运行	验证内容
Runner、collect、locator、config、sessions、CLI 标志	测试台套件，或覆盖该功能的文件	构建后的 CLI 在确定性应用上的端到端表现
Reporters（list、json、markdown、junit）	测试台文件及 test:stress	打印和写入的输出，包括恶意标题
@e2e-dev/web	测试台文件，然后运行 web 基准测试的 tests/	在普通和复杂页面上运行真实 Chromium
Agent（src/agent/）、提示词、trace cache	运行 web 基准测试的 tests-agent/ 重放，然后使用 --no-cache --ai-trace	重放仍能命中，且在线 Agent 仍能达成目标
@e2e-dev/mobile	在模拟器或仿真器上运行移动端基准测试	真实设备；参见 apps/mobile-benchmark
e2e mcp	在测试台上运行 e2e MCP 服务	编码 Agent 所看到的工具
e2e init、打包、技能	在 /tmp 下的临时项目中测试打包后的 tarball	新用户从 npm 获得的内容
文档页面	pnpm docs:check	链接、锚点、示例、包管理器标签页和徽标
@e2e-dev/github	PR 自身的 e2e-github 评论	用户的 PR 会收到的评论

命令（在应用目录中运行；直接调用 CLI，因为 pnpm run <script> -- --flag 会转发 --，而 CLI 会将该标志当作文件读取）：

cd apps/testbed && node node_modules/e2e/dist/cli/bin.js run tests/todos.e2e.ts
cd apps/web-benchmark && pnpm run build     # the Next.js app, once per scenario change
cd apps/web-benchmark && node node_modules/e2e/dist/cli/bin.js run tests/<scenario>.e2e.ts
cd apps/web-benchmark && node node_modules/e2e/dist/cli/bin.js run --config e2e.agent.config.ts
pnpm test:testbed && pnpm test:web-benchmark          # the whole gate, as CI runs it

如果某项行为必须持续得到验证，就在它旁边添加确定性测试：Runner 功能使用测试台页面及对应测试，复杂页面使用基准测试场景（尽量减少场景差异，绝不要修复预设的 bug）。测试遵循消费方技能 skills/e2e；本仓库是它的首个消费者。

Agent 运行需要 AI_GATEWAY_API_KEY。基准测试的 Agent 套件会重放已提交的录制内容，并且只会在没有录制内容的步骤调用模型，与 CI 一样；如果某个步骤在这里消耗了模型调用，说明它的录制内容已经过时。仅在更改 Agent 时，才使用 --no-cache --ai-trace 进行在线测试；使用 unbox-ai 阅读 trace（比较 main 和分支），绝不要直接打开它。重新录制的条目会在同一个 PR 中提交（参见 AGENTS.md 中的“已提交的录制内容”）。

MCP 服务

.mcp.json 会在测试台上注册 e2e mcp。先调用 open_session，然后调用 call {tool: "observe"}、locate、screenshot 和各个操作动词。为基准测试调用 open_session 时传入 config: "../web-benchmark/e2e.config.ts"。服务进程运行的是启动时加载的 dist：重新构建后，验证 MCP 或引擎更改之前，请重启服务（在 Claude Code 中使用 /mcp）。 可以同时打开多个会话（--max-sessions，默认值为 4）；每次调用都要传入会话 ID，并在完成后调用 close_session。

可用它编写定位器（locate 会打印 screen.* 调用），在测试前查看页面，验证 MCP 工具本身的更改；还可在引擎支持录制视频时录下操作过程（web 和 mobile 均支持）：设置好页面后调用一次 start_recording，再调用 stop_recording 获取文件路径。

像用户一样操作

• 运行构建好的 CLI，而不是单元测试框架。查看它打印的内容和写入的内容（.e2e/report.json、.e2e/results/<test>/trace.md 下的跟踪页面，以及用于生成 .e2e/summary.md 的 --reporter list,markdown）。
• 也要测试失败路径：更改错误代码、超时或策略拒绝时，应触发相应情况，并查看用户收到的消息。
• 检查副作用：产物应写入文档指定的位置，已填写的密钥不得出现在 .e2e/ 下的任何文件中（使用 grep -r 搜索该值）。
• APP_ALREADY_RUNNING 表示另一个检出目录中的运行占用了应用端口。请等待或询问；切勿停止并非由你启动的进程。
• 移动端：按照 apps/mobile-benchmark/README.md 中的说明使用设备。每台设备一次只运行一个任务。

验证依据

PR 必须展示功能正常（writing-pr）。说明涉及的界面、运行了什么、观察到了什么，并附上媒体：

• **终端输出：**将 CLI 输出中的相关行粘贴到带围栏的 text 代码块中（去除 ANSI 转义序列，缩短路径）。这是验证运行器、CLI 和报告器变更的主要依据。
• 视频：--video（添加 --headed 可观看运行过程）会在支持录制视频的引擎上记录每次尝试，并保存到 .e2e/results/<test>/attempt-<n>/video/：@e2e-dev/web 生成 video.webm，@e2e-dev/mobile 生成 video.mp4。对于查看者能够直观看到的引擎、定位器和 Agent 变更，请附上视频。
• **静帧：**从视频中截取一帧（ffmpeg -ss <seconds> -i <video> -frames:v 1 after.png），或截取文档页面。
• **Bug 修复，主分支与分支对比：**先编写回归测试，并在检出内容仍与 main 一致时运行，确保记录失败结果。若代码已经变更，可在旁边构建 main： git worktree add /tmp/e2e-main origin/main，然后在其中运行 pnpm install --frozen-lockfile && pnpm build，并在两个检出目录中运行相同的命令。
• 上传：gh pr create|edit --body-file body.md --attach ./after.png --attach ./video.webm （gh 2.99+）会上传每个文件、重写正文中的 Markdown 图片路径，并将视频作为播放器附加。若使用较旧的 gh，请在浏览器中将文件拖入 PR，或说明媒体文件存放在本地并解释原因。

如果有内容无法验证，请说明情况并指出阻碍。没有证据的肯定说法，还不如说“无法确定”。

清理

e2e run 会停止它启动的应用。close_session 会停止该 MCP 会话启动的应用。完成后，使用 git worktree remove 移除 /tmp/e2e-main worktree。