Opik E2E 测试失败排查指南基于 debugging-e2e-tests 技能的证据驱动调试方法论【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm导读本文基于 Opik 开源仓库中debugging-e2e-tests技能文档SKILL.md展开系统讲解当 Opik E2E 测试套件tests_end_to_end/e2e/出现红测时如何从 CI 检查、TestOps 启动、测试名或本地运行四个入口出发收集证据、区分真实回归与偶发 flake并给出可落地的修复建议。读完本文你将掌握一套完整的、只读的诊断流程——包括 Playwright trace 的查看、Allure TestOps 的调用、历史结果的时间线分析以及 Opik 测试套件特有的四类失败透镜DOM 竞态、选择器漂移、最终一致性、fixture 种子错配能够独立回答这个 E2E 测试为什么挂了。一、这个技能解决什么问题debugging-e2e-tests是 Opik 仓库中面向 Agent 与开发者的一套技能skill专门用于调查Opik E2E 测试套件tests_end_to_end/e2e/中的失败用例。它接受来自任意渠道的失败信号——一个变红的 CI 检查、一次 TestOps 启动launch、一个测试名称、或一次本地运行——然后收集证据trace、错误信息、历史记录分类定性判断是真实回归regression还是偶发不稳定flake提出修复建议给出具体的代码/选择器/轮询修改方向。它的边界非常明确这个技能是只读的——只诊断和提议绝不直接修改测试也不在调查过程中重跑整个套件。若开发者决定采纳修复需要交给配套的writing-e2e-tests技能见 .agents/skills/writing-e2e-tests/去执行改到变绿为止的循环。这与 AGENTIC.md 中描述的分工一致写测试与调试测试是两套独立流程。使用该技能时应首先声明Im using the debugging-e2e-tests skill to investigate X.我正在使用 debugging-e2e-tests 技能调查 X。二、证据在哪里本地、CI 与 TestOps 的三层证据体系诊断的前提是知道失败证据存放在哪里。Opik E2E 套件的证据分布在三个层面1. 本地运行证据Playwright trace位于tests_end_to_end/e2e/test-results/失败时被保留配置见下Allure 结果位于allure-results/目录。2. CI 运行证据7 天保留期每次 CI 运行会上传三个产物artifact均保留 7 天产物名内容用途test-results-v2Playwright traces videos查看失败步骤的 DOM 快照与网络/控制台信息playwright-report-v2HTML 报告整体浏览套件结果allure-results-v2Allure 结果与 TestOps 关联的结构化数据下载命令gh run download run-id -n test-results-v2 -D dir3. Allure TestOps 实时证据套件在 CI 期间会把结果实时流式上报到 Allure TestOpscomet.testops.cloud项目 id 为1。启动launch的命名规则为Opik v2 … tier - run_id其中末尾数字是 GitHub Actions 的 run id中间的 tier 段会变化——可以是E2E、Post-Merge、Local、staging、production。根据 package.json 中的脚本test:t1、test:t2、test:t3可以看到套件按标签分档运行t1-smoke、t2-cuj、t3-nightly这些 tier 与 TestOps 启动名中的层级段相互对应。证据保留的实现细节trace、截图与视频的保留策略由 playwright.config.ts 统一定义trace: retain-on-failure—— 失败时保留 tracescreenshot: only-on-failure—— 仅在失败时截图video: retain-on-failure—— 失败时保留视频actionTimeout: 15_000—— 每个 Playwright 动作的默认超时上限为 15 秒防止某个缺失的data-testid把整个测试预算烧在一个 locator 上。此外failure-artifacts.fixture.ts 实现了自定义的失败产物收集器测试通过时静默返回失败时则遍历注册的ArtifactSource把每个来源以failure.name为附件名附加到测试结果中并生成一份failure-manifestJSON包含名称、contentType、大小、附件名若某个来源本身抛出异常还会额外附加.error附件记录错误堆栈。这正是失败即留痕理念的代码级实现。三、核心工具链工具用途关键调用allure-testopsMCP最丰富的信息源见下方验证过的调用清单gh定位 CI 运行与下载产物gh run view run-id、gh run download run-id -n test-results-v2 -D dirnpx playwright show-trace打开 trace 查看失败步骤需在tests_end_to_end/e2e/目录下执行git对比可疑改动与失败测试的代码路径git diff相关提交Allure TestOps MCP 已验证的调用技能文档明确列出了三组经过验证的调用方式查找启动launchlist_launches(projectId: 1, search: run_id or name fragment, sort: [createdDate,DESC]) # 或 search_launches(rql: …)列出测试结果返回每个测试的name、fullName即 spec 路径 行号例如datasets/dataset-crud-smoke.spec.ts:8:7、status、TestOps 计算出的flaky标志、muted/known标记、tags、jobRun.url对应的 GitHub Actions 运行链接以及结果id。可用search参数过滤出失败的测试。list_test_results(launchId)查看测试历史这是判断 flake 的核心信号——查看某个测试在最近多次启动中的通过/失败时间线get_test_result_history(id)jobRun.url能直接给出 run id随后即可用gh下载 trace 产物。四、五步诊断循环技能定义了标准化的五步循环用一张有向图概括digraph debugging_e2e { rankdirTB; 1. Resolve entry point [shapebox]; 2. Gather evidence [shapebox]; 3. Classify [shapebox]; 4. Diagnose [shapebox]; 5. Report propose (no edits) [shapebox]; 1. Resolve entry point - 2. Gather evidence; 2. Gather evidence - 3. Classify; 3. Classify - 4. Diagnose; 4. Diagnose - 5. Report propose (no edits); }下面逐步展开。Step 1 —— 解析入口点Resolve the entry point无论最初从哪里看到失败都把它规约成一个失败的测试 它的证据在哪里输入来源操作变红的 CI 检查 / Actions 运行取 run idgh run view run-id找到失败 job用list_launches(projectId: 1, search: run-id)找到对应 launchtrace 在test-results-v2产物中用gh run download下载TestOps launch直接查询list_test_results(launchId)过滤出失败结果测试名称在最近的 launch 中用list_test_results配合search找到结果id再拉取其历史本地失败直接用本地test-results/的 trace 和allure-results/未提交的本地运行在 TestOps 中可能没有对应记录这没问题Step 2 —— 收集证据Gather evidence需要收集的证据包括失败的断言与错误信息来自 trace、报告或 TestOps 结果trace 本身对保留/下载的.zip执行npx playwright show-trace trace.zip读取失败步骤、当时的 DOM 快照以及附近的 console/network 信息截图/视频如果存在only-on-failure/retain-on-failure策略下失败时生成测试历史通过get_test_result_history(id)获取并结合 TestOps 结果上的flaky标志。当 TestOps 不可达时优雅降级例如纯本地运行退回trace diff推理。Step 3 —— 分类定性Classify在三种结论间做出判断真实回归real regression、偶发不稳定flake、环境/选择器漂移environment / selector drift。判据有二历史时间线某相关改动之后一段干净的全绿记录突然中断 → 偏向回归无相关改动却间歇性通过/失败或 TestOps 标记flaky: true→ 偏向 flakeDiff 相关性最近的改动是否触及失败断言所覆盖的代码路径页面/组件、POM 方法、fixture触及 → 回归可能性大未触及 → 更可能是 flake 或环境问题。默认原则当历史间歇且无相关 diff 时默认判为flake / 不确定——没有证据就不要过度断言回归。Step 4 —— 诊断根因Diagnose根因必须基于引用的证据具体的 trace 步骤、错误、历史模式而非猜测。技能为 Opik 套件总结了四类特有的诊断透镜透镜一先验证测试渲染再指责后端X 没出现这类失败往往是DOM 竞态loading spinner 还没结束、最终一致性的写入尚未落库而不是后端回归。检查失败步骤处的 trace DOM 快照即可分辨。这一点与套件的超时设计呼应actionTimeout: 15_000的注释明确说明未显式传timeout:的locator.waitFor()会继承测试级超时timeout: 90_000见 playwright.config.ts所以 POM 中需要更长时间的调用如 trace panel 冷加载 30 秒、异步轮询 90–120 秒都会自带显式timeout:覆盖默认值。透镜二选择器漂移Selector drift前端改动了一个 accessible name 或删除了某个data-testid导致 locator 无法解析。这是 FE 改动引发 E2E 失败的最常见形式之一。透镜三最终一致性状态Eventually-consistent state异步的评分/摄取需要轮询poll而不是固定等待fixed wait。Opik 的 trace 摄取与在线评估本身是异步管线测试断言若在数据落库前执行就会出现间歇性失败。透镜四Fixture 种子形状错配Seed-shape mismatch页面渲染出空/部分状态是因为 seed 与断言期望不匹配。Opik 套件中大量测试依赖精心设计的种子数据例如 dataset-item-count.spec.ts 的注释详细说明了种子形状的选择逻辑EMPTY_SIZE为 0 且从不插入数据无版本只能走遗留回退分支、其余两个数据集通过Dataset.insert()走items_total分支、MULTI_SIZE 2500则刻意超过 SDK 的 1000 条批处理上限——这样一个列表响应就覆盖了后端计数的两条分支。种子形状与断言期望一旦错位页面就会渲染出测试预料之外的状态。Step 5 —— 报告 提议不修改最终产出三部分判定Verdict分类结论回归 / flake / 环境或选择器 置信度证据Evidencetrace 步骤、错误、历史模式、关联的改动如有逐条引用修复提议Proposed fix必须具体——回归则指出要改的代码/选择器/轮询flake 则建议用轮询替代固定等待、隔离quarantine或明确无需代码修复——已知偶发重试即可。不修改任何东西。如果开发者要应用修复移交给writing-e2e-tests技能。五、理解测试所在的套件环境为了让诊断更有效理解套件自身的运行环境是必要的部署模式套件通过OPIK_DEPLOYMENT区分cloud/oss/self-hosted默认oss默认指向本地http://localhost:5173cloud/self-hosted 必须提供OPIK_BASE_URL且 trailing/api会被归一化去掉见 env.config.ts认证双路径cloud/self-hosted 下CI 标准路径是OPIK_TEST_USER_EMAIL OPIK_TEST_USER_PASSWORD让 global-setup 登录一次并持久化.auth/user.json本地调试路径则可用OPIK_API_KEY加预捕获的.auth/user.json跳过登录命名空间隔离每个测试创建的实体统一命名cuj-{runId}-w{worker}-{slug}runId YYYYMMDD-HHMMSS-mmmUTCglobal-teardown 会清扫整轮运行创建的实体见 base.fixture.ts 的testNamespacefixture 与 README.md本地启动套件npm ci npx playwright install chromium OPIK_DEPLOYMENTcloud \ OPIK_BASE_URLhttps://staging.dev.comet.com/opik/api \ OPIK_API_KEYyour key \ OPIK_WORKSPACEyour workspace \ npm run test掌握这些上下文后当 trace 中看到命名空间不匹配或认证类错误时就能快速判断是环境配置问题还是代码回归。六、技能边界与最佳实践总结边界说明只读不修改测试不因调查而重跑套件四入口兼容CI / TestOps / 测试名 / 本地运行均可作为起点优雅降级无 TestOps 时纯本地失败用 trace diff 完成诊断与写作区分writing-e2e-tests负责新建测试本技能负责解释一个变红的测试实践要点回顾先找 launchlist_launches再过滤失败结果list_test_results再拉历史get_test_result_history——这条链路覆盖了 80% 的 flake 判定用npx playwright show-trace看失败瞬间的 DOM 快照优先排查 DOM 竞态与选择器漂移再怀疑后端把间歇性 无相关 diff默认归为 flake不要凭直觉上报回归提议修复时务必具体指出改哪个 locator、哪个固定等待该换成轮询还是直接隔离。这套方法论不只在 Opik 仓库内有效——证据驱动的 flake 判定 trace 微观取证 历史时间线的组合同样可以迁移到任何基于 Playwright 的大型 E2E 套件排障中。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Opik E2E 测试失败排查指南：基于 debugging-e2e-tests 技能的证据驱动调试方法论
Opik E2E 测试失败排查指南基于 debugging-e2e-tests 技能的证据驱动调试方法论【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm导读本文基于 Opik 开源仓库中debugging-e2e-tests技能文档SKILL.md展开系统讲解当 Opik E2E 测试套件tests_end_to_end/e2e/出现红测时如何从 CI 检查、TestOps 启动、测试名或本地运行四个入口出发收集证据、区分真实回归与偶发 flake并给出可落地的修复建议。读完本文你将掌握一套完整的、只读的诊断流程——包括 Playwright trace 的查看、Allure TestOps 的调用、历史结果的时间线分析以及 Opik 测试套件特有的四类失败透镜DOM 竞态、选择器漂移、最终一致性、fixture 种子错配能够独立回答这个 E2E 测试为什么挂了。一、这个技能解决什么问题debugging-e2e-tests是 Opik 仓库中面向 Agent 与开发者的一套技能skill专门用于调查Opik E2E 测试套件tests_end_to_end/e2e/中的失败用例。它接受来自任意渠道的失败信号——一个变红的 CI 检查、一次 TestOps 启动launch、一个测试名称、或一次本地运行——然后收集证据trace、错误信息、历史记录分类定性判断是真实回归regression还是偶发不稳定flake提出修复建议给出具体的代码/选择器/轮询修改方向。它的边界非常明确这个技能是只读的——只诊断和提议绝不直接修改测试也不在调查过程中重跑整个套件。若开发者决定采纳修复需要交给配套的writing-e2e-tests技能见 .agents/skills/writing-e2e-tests/去执行改到变绿为止的循环。这与 AGENTIC.md 中描述的分工一致写测试与调试测试是两套独立流程。使用该技能时应首先声明Im using the debugging-e2e-tests skill to investigate X.我正在使用 debugging-e2e-tests 技能调查 X。二、证据在哪里本地、CI 与 TestOps 的三层证据体系诊断的前提是知道失败证据存放在哪里。Opik E2E 套件的证据分布在三个层面1. 本地运行证据Playwright trace位于tests_end_to_end/e2e/test-results/失败时被保留配置见下Allure 结果位于allure-results/目录。2. CI 运行证据7 天保留期每次 CI 运行会上传三个产物artifact均保留 7 天产物名内容用途test-results-v2Playwright traces videos查看失败步骤的 DOM 快照与网络/控制台信息playwright-report-v2HTML 报告整体浏览套件结果allure-results-v2Allure 结果与 TestOps 关联的结构化数据下载命令gh run download run-id -n test-results-v2 -D dir3. Allure TestOps 实时证据套件在 CI 期间会把结果实时流式上报到 Allure TestOpscomet.testops.cloud项目 id 为1。启动launch的命名规则为Opik v2 … tier - run_id其中末尾数字是 GitHub Actions 的 run id中间的 tier 段会变化——可以是E2E、Post-Merge、Local、staging、production。根据 package.json 中的脚本test:t1、test:t2、test:t3可以看到套件按标签分档运行t1-smoke、t2-cuj、t3-nightly这些 tier 与 TestOps 启动名中的层级段相互对应。证据保留的实现细节trace、截图与视频的保留策略由 playwright.config.ts 统一定义trace: retain-on-failure—— 失败时保留 tracescreenshot: only-on-failure—— 仅在失败时截图video: retain-on-failure—— 失败时保留视频actionTimeout: 15_000—— 每个 Playwright 动作的默认超时上限为 15 秒防止某个缺失的data-testid把整个测试预算烧在一个 locator 上。此外failure-artifacts.fixture.ts 实现了自定义的失败产物收集器测试通过时静默返回失败时则遍历注册的ArtifactSource把每个来源以failure.name为附件名附加到测试结果中并生成一份failure-manifestJSON包含名称、contentType、大小、附件名若某个来源本身抛出异常还会额外附加.error附件记录错误堆栈。这正是失败即留痕理念的代码级实现。三、核心工具链工具用途关键调用allure-testopsMCP最丰富的信息源见下方验证过的调用清单gh定位 CI 运行与下载产物gh run view run-id、gh run download run-id -n test-results-v2 -D dirnpx playwright show-trace打开 trace 查看失败步骤需在tests_end_to_end/e2e/目录下执行git对比可疑改动与失败测试的代码路径git diff相关提交Allure TestOps MCP 已验证的调用技能文档明确列出了三组经过验证的调用方式查找启动launchlist_launches(projectId: 1, search: run_id or name fragment, sort: [createdDate,DESC]) # 或 search_launches(rql: …)列出测试结果返回每个测试的name、fullName即 spec 路径 行号例如datasets/dataset-crud-smoke.spec.ts:8:7、status、TestOps 计算出的flaky标志、muted/known标记、tags、jobRun.url对应的 GitHub Actions 运行链接以及结果id。可用search参数过滤出失败的测试。list_test_results(launchId)查看测试历史这是判断 flake 的核心信号——查看某个测试在最近多次启动中的通过/失败时间线get_test_result_history(id)jobRun.url能直接给出 run id随后即可用gh下载 trace 产物。四、五步诊断循环技能定义了标准化的五步循环用一张有向图概括digraph debugging_e2e { rankdirTB; 1. Resolve entry point [shapebox]; 2. Gather evidence [shapebox]; 3. Classify [shapebox]; 4. Diagnose [shapebox]; 5. Report propose (no edits) [shapebox]; 1. Resolve entry point - 2. Gather evidence; 2. Gather evidence - 3. Classify; 3. Classify - 4. Diagnose; 4. Diagnose - 5. Report propose (no edits); }下面逐步展开。Step 1 —— 解析入口点Resolve the entry point无论最初从哪里看到失败都把它规约成一个失败的测试 它的证据在哪里输入来源操作变红的 CI 检查 / Actions 运行取 run idgh run view run-id找到失败 job用list_launches(projectId: 1, search: run-id)找到对应 launchtrace 在test-results-v2产物中用gh run download下载TestOps launch直接查询list_test_results(launchId)过滤出失败结果测试名称在最近的 launch 中用list_test_results配合search找到结果id再拉取其历史本地失败直接用本地test-results/的 trace 和allure-results/未提交的本地运行在 TestOps 中可能没有对应记录这没问题Step 2 —— 收集证据Gather evidence需要收集的证据包括失败的断言与错误信息来自 trace、报告或 TestOps 结果trace 本身对保留/下载的.zip执行npx playwright show-trace trace.zip读取失败步骤、当时的 DOM 快照以及附近的 console/network 信息截图/视频如果存在only-on-failure/retain-on-failure策略下失败时生成测试历史通过get_test_result_history(id)获取并结合 TestOps 结果上的flaky标志。当 TestOps 不可达时优雅降级例如纯本地运行退回trace diff推理。Step 3 —— 分类定性Classify在三种结论间做出判断真实回归real regression、偶发不稳定flake、环境/选择器漂移environment / selector drift。判据有二历史时间线某相关改动之后一段干净的全绿记录突然中断 → 偏向回归无相关改动却间歇性通过/失败或 TestOps 标记flaky: true→ 偏向 flakeDiff 相关性最近的改动是否触及失败断言所覆盖的代码路径页面/组件、POM 方法、fixture触及 → 回归可能性大未触及 → 更可能是 flake 或环境问题。默认原则当历史间歇且无相关 diff 时默认判为flake / 不确定——没有证据就不要过度断言回归。Step 4 —— 诊断根因Diagnose根因必须基于引用的证据具体的 trace 步骤、错误、历史模式而非猜测。技能为 Opik 套件总结了四类特有的诊断透镜透镜一先验证测试渲染再指责后端X 没出现这类失败往往是DOM 竞态loading spinner 还没结束、最终一致性的写入尚未落库而不是后端回归。检查失败步骤处的 trace DOM 快照即可分辨。这一点与套件的超时设计呼应actionTimeout: 15_000的注释明确说明未显式传timeout:的locator.waitFor()会继承测试级超时timeout: 90_000见 playwright.config.ts所以 POM 中需要更长时间的调用如 trace panel 冷加载 30 秒、异步轮询 90–120 秒都会自带显式timeout:覆盖默认值。透镜二选择器漂移Selector drift前端改动了一个 accessible name 或删除了某个data-testid导致 locator 无法解析。这是 FE 改动引发 E2E 失败的最常见形式之一。透镜三最终一致性状态Eventually-consistent state异步的评分/摄取需要轮询poll而不是固定等待fixed wait。Opik 的 trace 摄取与在线评估本身是异步管线测试断言若在数据落库前执行就会出现间歇性失败。透镜四Fixture 种子形状错配Seed-shape mismatch页面渲染出空/部分状态是因为 seed 与断言期望不匹配。Opik 套件中大量测试依赖精心设计的种子数据例如 dataset-item-count.spec.ts 的注释详细说明了种子形状的选择逻辑EMPTY_SIZE为 0 且从不插入数据无版本只能走遗留回退分支、其余两个数据集通过Dataset.insert()走items_total分支、MULTI_SIZE 2500则刻意超过 SDK 的 1000 条批处理上限——这样一个列表响应就覆盖了后端计数的两条分支。种子形状与断言期望一旦错位页面就会渲染出测试预料之外的状态。Step 5 —— 报告 提议不修改最终产出三部分判定Verdict分类结论回归 / flake / 环境或选择器 置信度证据Evidencetrace 步骤、错误、历史模式、关联的改动如有逐条引用修复提议Proposed fix必须具体——回归则指出要改的代码/选择器/轮询flake 则建议用轮询替代固定等待、隔离quarantine或明确无需代码修复——已知偶发重试即可。不修改任何东西。如果开发者要应用修复移交给writing-e2e-tests技能。五、理解测试所在的套件环境为了让诊断更有效理解套件自身的运行环境是必要的部署模式套件通过OPIK_DEPLOYMENT区分cloud/oss/self-hosted默认oss默认指向本地http://localhost:5173cloud/self-hosted 必须提供OPIK_BASE_URL且 trailing/api会被归一化去掉见 env.config.ts认证双路径cloud/self-hosted 下CI 标准路径是OPIK_TEST_USER_EMAIL OPIK_TEST_USER_PASSWORD让 global-setup 登录一次并持久化.auth/user.json本地调试路径则可用OPIK_API_KEY加预捕获的.auth/user.json跳过登录命名空间隔离每个测试创建的实体统一命名cuj-{runId}-w{worker}-{slug}runId YYYYMMDD-HHMMSS-mmmUTCglobal-teardown 会清扫整轮运行创建的实体见 base.fixture.ts 的testNamespacefixture 与 README.md本地启动套件npm ci npx playwright install chromium OPIK_DEPLOYMENTcloud \ OPIK_BASE_URLhttps://staging.dev.comet.com/opik/api \ OPIK_API_KEYyour key \ OPIK_WORKSPACEyour workspace \ npm run test掌握这些上下文后当 trace 中看到命名空间不匹配或认证类错误时就能快速判断是环境配置问题还是代码回归。六、技能边界与最佳实践总结边界说明只读不修改测试不因调查而重跑套件四入口兼容CI / TestOps / 测试名 / 本地运行均可作为起点优雅降级无 TestOps 时纯本地失败用 trace diff 完成诊断与写作区分writing-e2e-tests负责新建测试本技能负责解释一个变红的测试实践要点回顾先找 launchlist_launches再过滤失败结果list_test_results再拉历史get_test_result_history——这条链路覆盖了 80% 的 flake 判定用npx playwright show-trace看失败瞬间的 DOM 快照优先排查 DOM 竞态与选择器漂移再怀疑后端把间歇性 无相关 diff默认归为 flake不要凭直觉上报回归提议修复时务必具体指出改哪个 locator、哪个固定等待该换成轮询还是直接隔离。这套方法论不只在 Opik 仓库内有效——证据驱动的 flake 判定 trace 微观取证 历史时间线的组合同样可以迁移到任何基于 Playwright 的大型 E2E 套件排障中。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考