企业官网建设流程全解析

如何用e2e让编码智能体自动调试失败的测试？完整指南

【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e

e2e 是一个开源的下一代端到端测试框架，它专为「让编码智能体（Coding Agent）自己干活」而设计：智能体用自然语言驱动应用执行测试，测试失败后，它读取结构化的失败证据、定位原因、修改代码，再重跑验证——整个调试失败测试的过程几乎全自动。本文将手把手带你看懂 e2e 的智能体调试闭环：从一条命令初始化，到读懂 trace 页面，全程不需要手写复杂代码。

为什么 e2e 适合交给智能体调试

传统测试框架的失败报告是"给人看的"：HTML 报告、视频回放，智能体很难利用。e2e 从设计之初就把智能体当作第一读者：

• 每次失败都生成 Markdown trace 页面：哪一行失败、每个步骤做了什么、应用日志、失败时的屏幕截图，全部写成智能体可以直接读取的文本；
• 标准化的退出码和错误码：智能体可以据此判断"该修应用、该修定位器，还是该换模型"；
• init 自动安装技能包和 MCP 服务：智能体既"会查手册"，又能"亲眼操作"你的应用。

官方对这套机制的完整说明见 docs/coding-agents.mdx#L7-L9。

一键初始化：给智能体装上"调试技能" 🧰

在项目里运行一条命令：

npx e2e init

init会完成三件关键的事：

1. 安装技能（Skill）：写入.agents/skills/e2e/（Claude Code 用户还会在.claude/skills/e2e/得到软链接）。技能里包含总览 skills/e2e/SKILL.md 和分主题参考文档——其中 skills/e2e/references/debugging.md 就是一份"运行失败时该查什么"的速查手册；
2. 注册 MCP 服务：写入.mcp.json（Claude Code）或.cursor/mcp.json（Cursor），让智能体能直接"看到并操作"正在运行的应用；
3. 生成配置和示例测试：e2e.config.ts和一个可以跑通的测试。

升级 e2e 后重跑一次init即可刷新技能。此外，e2e包自带全套文档（node_modules/e2e/docs），智能体即使离线也能"查手册"。

智能体调试失败测试的 4 步循环 🔄

这是整篇文章的核心。智能体（或你）按这个循环操作，绝大多数失败都能自愈：

第 1 步：运行单个测试文件

调试时永远只跑一个文件，反馈越快越好：

npx e2e run tests/checkout.e2e.ts

第 2 步：读 trace 页面（关键证据 📸）

测试到达执行阶段后，每个失败的测试都会生成一份 trace 页面，终端会在失败项下面直接给出路径：

❯ trace .e2e/results/<test>/trace.md

这份页面浓缩了所有关键信息：

• Look at:失败发生在哪一行；
• 每个步骤的实际行为：动作落在哪个节点、断言在等待期间读到了什么值（"16 次读取全是0 remaining"说明期望值错了或应用没到那个状态）；
• 回放缓存的决策：这一步是重放的、交还给智能体的，还是重新跑的；
• 应用日志：控制台报错、未捕获异常、4xx/5xx失败请求；
• 智能体最后几轮的"思考"，以及失败瞬间的屏幕（截图 + 每行一个节点的无障碍树）。

举个例子，docs/debugging.mdx#L54-L112 中展示的真实 trace：断言期望1 remaining，实际一直是0 remaining；顺着应用日志一看，POST /api/todos 500 Internal Server Error——原来是应用自身的 bug，测试没写错。这种"测试失败 → 证据链 → 结论"的推理，智能体完全可以独立完成。

第 3 步：用退出码和错误码定位方向

退出码帮智能体快速分诊（完整表格见 docs/debugging.mdx#L27-L35）：

错误码则指向具体修法，比如：LOCATOR_NOT_FOUND→ 角色或名称写错了；LOCATOR_AMBIGUOUS→ 匹配到两个元素，需要加限定条件；ASSERTION_FAILED→ 期望值错误或状态 5 秒内没稳定。全部错误码见 docs/reference/errors.mdx。

第 4 步：修改后只重跑失败项

npx e2e run --last-failed

智能体改完代码后只重跑上次失败的测试，快速确认修复，然后继续下一个。

三个"放大镜"：--headed、--debug、--ai-trace 🔍

当 trace 页面还不足以说明问题时，e2e 提供了三个调试旗标（用法见 skills/e2e/references/debugging.md#L100-L111）：

• --headed：用可见的浏览器运行，智能体可以"亲眼看着"失败的那一步如何发生；
• --debug：在 stderr 输出每个智能体步骤的耗时、模型调用次数、token 用量和成本，并把每步的模型对话存成工件；
• --ai-trace：把每一次模型调用写入.e2e/ai-trace.json，用于检查"模型到底看到了什么、调用了什么工具"。

排查回放缓存导致的失败时，加--no-cache让智能体现场真跑一遍，即可排除"旧录像"的干扰；用--workers 1 --retries 0则能排除并行与重试的干扰。

让智能体"亲眼看"应用：MCP 服务 👀

e2e mcp启动一个 MCP 服务器，编码智能体通过它打开真实的浏览器会话，获得一组工具：observe（读取当前屏幕的节点列表）、locate（写测试前先验证一个定位器是否恰好匹配一个元素，匹配成功还会直接返回可用的测试代码）、screenshot、tap、type、scroll等。

这意味着智能体的工作流变成：先开一个 MCP 会话把页面点一遍 → 确认按钮叫什么、元素叫什么 → 再写测试。写出来的测试天然更稳，失败率更低。每个智能体（包括子智能体）都开自己的会话，可以并行操作应用。完整工具清单见 docs/reference/mcp.mdx。

回放缓存：修一次，之后"免费"重放 💰

e2e 有一个巧妙的机制：agent.act()步骤一旦被后续断言验证通过，它的操作序列会记录到.e2e/cache/；下一次运行直接重放，不调用模型。如果 UI 变了导致重放失败，智能体会自动从当前屏幕接管、重新操作，并在下次通过时重新录像。

对调试的意义是：智能体修好一个测试后，后续 CI 里这一步零成本、零波动；而当某个缓存条目引发失败时，trace 页面会写明"回放停在哪一步、为什么"，配合--no-cache即可二分定位。原理详见 docs/cache.mdx。

上手前先看看：官方示例项目

examples/目录下有 Vite、Next.js、SwiftUI、Jetpack Compose、Flutter 等每个都带可跑通测试套件的完整项目，是观察"智能体如何写测试、跑测试"的现成教材，索引见 examples/README.md：

比如 Vite 示例里的 examples/with-vite/tests/greeting.e2e.ts 就是一个"输入名字 → 验证问候"的最小完整测试，非常适合对照本文的 4 步循环做实验。

关键文件速查表 📌

小结 ✅

用 e2e 让编码智能体自动调试失败测试，只需要记住三件事：

1. npx e2e init：一条命令给智能体装好技能手册和"眼睛"（MCP）；
2. 读 trace 页面：.e2e/results/<test>/trace.md是智能体的"事故现场"，包含失败行、步骤细节、应用日志和失败截图；
3. 靠退出码 + 错误码分诊，用--headed/--debug/--ai-trace放大细节，--last-failed快速重跑验证。

把这套闭环交给 Claude Code、Cursor 等编码智能体后，"测试红了 → 智能体自己排查修复 → 再跑变绿"就会成为日常。e2e 目前仍在快速迭代中，具体行为以仓库内文档为准。

【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e