e2e测试失败排查清单10个高频问题与定位方法【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e跑e2e测试时红灯亮了别慌。e2e 是一个面向 Web 和移动端的下一代端到端e2e测试框架它给每一次失败都准备了完整的证据链错误码、退出码、trace 页面、失败截图和应用日志。本文整理 10 个 e2e 测试失败的高频问题并给出对应的定位方法帮你把排查时间从十几分钟压缩到几分钟。排查第一步看退出码判断问题类型e2e 用退出码告诉你是测试本身失败还是环境出了问题这决定了排查方向详见 docs/debugging.mdx退出码含义排查动作1测试失败断言、定位器、步骤超时打开 trace 页面看具体哪一步挂了2配置 / 收集 / 策略错误先修配置别急着重试3引擎、应用进程、模型服务失败确认是临时故障再重试4运行器内部错误直接反馈给项目方130运行被中断Ctrl-C、CI 取消无需排查 记住一句话退出码 1 查测试退出码 2 查配置退出码 3 查环境。10 个高频失败问题与定位方法以下错误码来自官方错误参考 docs/reference/errors.mdx每个问题都给出现象 → 原因 → 定位动作。1. 定位器找不到元素LOCATOR_NOT_FOUND现象getByRole/getByLabel等定位器在截止时间前始终没等到元素。常见原因可访问名称写错、文本不完全匹配、元素在 iframe 里、页面还没打开就断言。定位方法先看终端里给出的附近相似元素列表不确定时加exact: false重试iframe 用browser.frameLocator仍不确定就用--headed开一个可见浏览器肉眼确认。2. 定位器匹配到多个元素LOCATOR_AMBIGUOUS现象一次只允许匹配一个节点的操作如点击找到了 2 个以上目标立即失败、不做轮询。常见原因页面上有隐藏的重名元素、重复的标签文案。定位方法给定位器补充{ name }缩小范围或限定在容器内或用first()、{ visible: true }区分。3. 断言失败ASSERTION_FAILED现象expect或agent.assert的判定与实际不符例如期望 1 remaining 实际是 0 remaining。定位关键看 trace 里断言的轮询读数。如果 16 次读数全是同一个值多半是期望写错了或应用根本没进入该状态去 App 日志找失败的请求如果读数在中途发生变化说明断言和应用状态存在竞态需要换更稳定的等待条件。4. 应用无法启动APP_UNREACHABLE现象测试跑不到一半报告应用 URL 连不上或app.command迟迟没有就绪。常见原因端口不对、启动命令崩了、启动时间超过startupTimeout。定位方法给app.command配置log后重跑直接读启动日志确认端口没被占必要时调大startupTimeout。移动端出现该码时消息里通常会直接写出自动化 runner 的状态照提示执行恢复命令即可见 docs/mobile.mdx 的 Troubleshooting 章节。5. 端口/应用已在运行APP_ALREADY_RUNNING现象你本机已经手动起过被测应用运行器又想自己起一份readyUrl已被占用。定位方法停掉那个进程或者本地开发时把reuseExisting: true写进配置直接复用已有实例。6. 模型不可用MODEL_UNAVAILABLE/MODEL_PROVIDER_FAILED现象用agent.act/agent.assert的用例在第一步就挂掉。常见原因配置里根本没配模型MODEL_UNAVAILABLEAPI key 无效、限流、余额不足或请求 120 秒无响应MODEL_PROVIDER_FAILED。定位方法检查agents.name.model是否真的构造出了模型实例检查 key 和额度。注意纯定位器 断言的用例不需要模型把失败用例的 agent 步骤拆掉可以快速隔离问题。7. 缓存回放失效REPLAY_STALEe2e 会录制 agent 成功过的操作并回放跳过模型调用详见 docs/cache.mdx。当回放与当前界面不再匹配且开启了严格缓存cache.strict时步骤直接失败而不是回退给 agent。定位方法先用--no-cache跑一次确认是缓存问题然后关闭 strict 模式重新录制并提交新的缓存条目。运行摘要里的replayed / handed off / missed三个计数能快速判断缓存命中率是否异常。8. 步骤超时或预算耗尽STEP_TIMEOUT/STEP_BUDGET_EXHAUSTED现象agent 步骤跑不完动作步数、模型调用次数或时间预算先到头。定位方法把一个目标拆得更小、更具体确需复杂流程时调高maxSteps/maxModelCalls或调大配置里的timeout。--debug会输出每个 agent 步骤的耗时和模型调用表一眼看出卡在哪。9. 断言无法判定ASSERTION_INCONCLUSIVE现象agent.assert问了一个屏幕上根本看不到的东西——数据在别的页面、还在加载中、或者只存在于像素里。定位方法先app.open或等待到正确屏幕再提问如果答案只在像素里比如 Canvas 内容按提示加vision: true。注意它永远是失败不会算通过。10. 配置与收集错误退出码 2 的一族CONFIG_NOT_FOUND、INVALID_CONFIG、NO_TESTS、COLLECTION_ERROR等完整清单见 docs/reference/errors.mdx。现象一个测试都没跑起来就结束了。定位方法这类错误信息本身就会指出最近的正确写法。高频三件事配置文件名必须是e2e.config.ts/e2e.config.mtstargets里 Web 目标必须有app.urltestsglob 至少要匹配到一个文件NO_TESTS会列出相似文件名供你对照。用 trace 页面与证据目录快速定位每个走到测试阶段的运行都会为失败用例生成一个trace 页面.e2e/results/用例名/trace.md这是排查 e2e 测试失败的核心入口逐步时间线每个步骤落在哪个节点、断言等待期间读到的值、回放缓存的决策、页面跳转↪ navigated to /login、屏幕变化新增/删除/改动的节点App 日志console 输出、未捕获异常、失败请求、4xx/5xx 响应并标注发生在哪一步失败瞬间截图.e2e/results/用例名/attempt-1/screenshots/001-failure.png配合同目录的screen-at-failure.txt文本树直接看失败时的界面结构。另一个实用技巧某步骤之后显示screen: unchanged说明那个操作没有产生任何可见效果——通常意味着点击没落到目标上或被遮罩挡住了。四个调试命令按需取用命令用途e2e run --headed开可见浏览器肉眼跟看失败过程e2e run --debug输出每个 agent 步骤的耗时、模型调用与 token 表e2e run --no-cache绕过缓存回放排除旧录制嫌疑e2e run --videoretain-on-failure只保留失败用例的录像回看失败瞬间脚本化排查可读取.e2e/report.json版本化 schema用jq筛出非passed的结果及其error、steps、artifacts字段无需人工翻终端输出。延伸阅读调试指南docs/debugging.mdx —— 错误码速查表、trace 结构、录屏模式错误参考docs/reference/errors.mdx —— 每个错误码的触发条件与退出码缓存机制docs/cache.mdx —— 回放如何生效、unconfirmed/evicted的含义移动端排障docs/mobile.mdx —— 模拟器挂死、daemon 恢复命令完整示例工程examples/with-next/、examples/with-vite/每个都带可运行的测试套件排查口诀退出码定方向 → 错误码定原因 → trace 页面看证据 → 命令复现验证。按这个顺序绝大多数 e2e 测试失败都能在一轮重跑内定位到位。【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
e2e测试失败排查清单10个高频问题与定位方法【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e跑e2e测试时红灯亮了别慌。e2e 是一个面向 Web 和移动端的下一代端到端e2e测试框架它给每一次失败都准备了完整的证据链错误码、退出码、trace 页面、失败截图和应用日志。本文整理 10 个 e2e 测试失败的高频问题并给出对应的定位方法帮你把排查时间从十几分钟压缩到几分钟。排查第一步看退出码判断问题类型e2e 用退出码告诉你是测试本身失败还是环境出了问题这决定了排查方向详见 docs/debugging.mdx退出码含义排查动作1测试失败断言、定位器、步骤超时打开 trace 页面看具体哪一步挂了2配置 / 收集 / 策略错误先修配置别急着重试3引擎、应用进程、模型服务失败确认是临时故障再重试4运行器内部错误直接反馈给项目方130运行被中断Ctrl-C、CI 取消无需排查 记住一句话退出码 1 查测试退出码 2 查配置退出码 3 查环境。10 个高频失败问题与定位方法以下错误码来自官方错误参考 docs/reference/errors.mdx每个问题都给出现象 → 原因 → 定位动作。1. 定位器找不到元素LOCATOR_NOT_FOUND现象getByRole/getByLabel等定位器在截止时间前始终没等到元素。常见原因可访问名称写错、文本不完全匹配、元素在 iframe 里、页面还没打开就断言。定位方法先看终端里给出的附近相似元素列表不确定时加exact: false重试iframe 用browser.frameLocator仍不确定就用--headed开一个可见浏览器肉眼确认。2. 定位器匹配到多个元素LOCATOR_AMBIGUOUS现象一次只允许匹配一个节点的操作如点击找到了 2 个以上目标立即失败、不做轮询。常见原因页面上有隐藏的重名元素、重复的标签文案。定位方法给定位器补充{ name }缩小范围或限定在容器内或用first()、{ visible: true }区分。3. 断言失败ASSERTION_FAILED现象expect或agent.assert的判定与实际不符例如期望 1 remaining 实际是 0 remaining。定位关键看 trace 里断言的轮询读数。如果 16 次读数全是同一个值多半是期望写错了或应用根本没进入该状态去 App 日志找失败的请求如果读数在中途发生变化说明断言和应用状态存在竞态需要换更稳定的等待条件。4. 应用无法启动APP_UNREACHABLE现象测试跑不到一半报告应用 URL 连不上或app.command迟迟没有就绪。常见原因端口不对、启动命令崩了、启动时间超过startupTimeout。定位方法给app.command配置log后重跑直接读启动日志确认端口没被占必要时调大startupTimeout。移动端出现该码时消息里通常会直接写出自动化 runner 的状态照提示执行恢复命令即可见 docs/mobile.mdx 的 Troubleshooting 章节。5. 端口/应用已在运行APP_ALREADY_RUNNING现象你本机已经手动起过被测应用运行器又想自己起一份readyUrl已被占用。定位方法停掉那个进程或者本地开发时把reuseExisting: true写进配置直接复用已有实例。6. 模型不可用MODEL_UNAVAILABLE/MODEL_PROVIDER_FAILED现象用agent.act/agent.assert的用例在第一步就挂掉。常见原因配置里根本没配模型MODEL_UNAVAILABLEAPI key 无效、限流、余额不足或请求 120 秒无响应MODEL_PROVIDER_FAILED。定位方法检查agents.name.model是否真的构造出了模型实例检查 key 和额度。注意纯定位器 断言的用例不需要模型把失败用例的 agent 步骤拆掉可以快速隔离问题。7. 缓存回放失效REPLAY_STALEe2e 会录制 agent 成功过的操作并回放跳过模型调用详见 docs/cache.mdx。当回放与当前界面不再匹配且开启了严格缓存cache.strict时步骤直接失败而不是回退给 agent。定位方法先用--no-cache跑一次确认是缓存问题然后关闭 strict 模式重新录制并提交新的缓存条目。运行摘要里的replayed / handed off / missed三个计数能快速判断缓存命中率是否异常。8. 步骤超时或预算耗尽STEP_TIMEOUT/STEP_BUDGET_EXHAUSTED现象agent 步骤跑不完动作步数、模型调用次数或时间预算先到头。定位方法把一个目标拆得更小、更具体确需复杂流程时调高maxSteps/maxModelCalls或调大配置里的timeout。--debug会输出每个 agent 步骤的耗时和模型调用表一眼看出卡在哪。9. 断言无法判定ASSERTION_INCONCLUSIVE现象agent.assert问了一个屏幕上根本看不到的东西——数据在别的页面、还在加载中、或者只存在于像素里。定位方法先app.open或等待到正确屏幕再提问如果答案只在像素里比如 Canvas 内容按提示加vision: true。注意它永远是失败不会算通过。10. 配置与收集错误退出码 2 的一族CONFIG_NOT_FOUND、INVALID_CONFIG、NO_TESTS、COLLECTION_ERROR等完整清单见 docs/reference/errors.mdx。现象一个测试都没跑起来就结束了。定位方法这类错误信息本身就会指出最近的正确写法。高频三件事配置文件名必须是e2e.config.ts/e2e.config.mtstargets里 Web 目标必须有app.urltestsglob 至少要匹配到一个文件NO_TESTS会列出相似文件名供你对照。用 trace 页面与证据目录快速定位每个走到测试阶段的运行都会为失败用例生成一个trace 页面.e2e/results/用例名/trace.md这是排查 e2e 测试失败的核心入口逐步时间线每个步骤落在哪个节点、断言等待期间读到的值、回放缓存的决策、页面跳转↪ navigated to /login、屏幕变化新增/删除/改动的节点App 日志console 输出、未捕获异常、失败请求、4xx/5xx 响应并标注发生在哪一步失败瞬间截图.e2e/results/用例名/attempt-1/screenshots/001-failure.png配合同目录的screen-at-failure.txt文本树直接看失败时的界面结构。另一个实用技巧某步骤之后显示screen: unchanged说明那个操作没有产生任何可见效果——通常意味着点击没落到目标上或被遮罩挡住了。四个调试命令按需取用命令用途e2e run --headed开可见浏览器肉眼跟看失败过程e2e run --debug输出每个 agent 步骤的耗时、模型调用与 token 表e2e run --no-cache绕过缓存回放排除旧录制嫌疑e2e run --videoretain-on-failure只保留失败用例的录像回看失败瞬间脚本化排查可读取.e2e/report.json版本化 schema用jq筛出非passed的结果及其error、steps、artifacts字段无需人工翻终端输出。延伸阅读调试指南docs/debugging.mdx —— 错误码速查表、trace 结构、录屏模式错误参考docs/reference/errors.mdx —— 每个错误码的触发条件与退出码缓存机制docs/cache.mdx —— 回放如何生效、unconfirmed/evicted的含义移动端排障docs/mobile.mdx —— 模拟器挂死、daemon 恢复命令完整示例工程examples/with-next/、examples/with-vite/每个都带可运行的测试套件排查口诀退出码定方向 → 错误码定原因 → trace 页面看证据 → 命令复现验证。按这个顺序绝大多数 e2e 测试失败都能在一轮重跑内定位到位。【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
