Kibana Flaky 测试调查指南从 CI 失败到根因诊断的完整方法论【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana本文基于 Kibana 仓库中的 Agent 技能文档 .agents/skills/flaky-test-investigator/SKILL.md 整理系统讲解如何调查 Scout 与 FTR 功能测试中的不稳定flaky失败从获取一个failed-test标签的 GitHub issue 出发依次经过测试环境分析、失败产物截图/DOM/日志/trace取证、失败范围界定、最佳实践对照、修复护栏guardrails约束直至输出一份结构化调查报告。读完本文你可以掌握 Kibana 官方的 flaky 测试分诊流程能够区分测试自身缺陷、产品缺陷、环境/基础设施问题三类根因并给出经得起复发的长期修复建议。一、技能定位诊断优先而非快速止血该技能flaky-test-investigator明确定义了调查的目标与合法结论产出要求结论应是一个准确的诊断和稳健的长期修复而不是治标不治本的快速修复quick fix合法结论包括以下三种之一这是真实的产品缺陷应升级escalate给负责团队这是环境性问题很可能自行恢复现有数据不足以得出有信心的结论。最后一条尤为重要Kibana 官方把承认不知道视为一种有效且值得报告的结论而不是需要掩饰的失败。必需输入failed-test issue调查的入口是一个带failed-test标签的 GitHub issue 链接如果没有提供应先索取再开始。技能文档强调两点该 issue 上可能已有自动化流程automation发布的历史根因分析或修复建议要参考但必须独立做研究、独立下结论——历史分析可能基于更少的数据或基于过时的排障指南issue 中的其他评论包括kibanamachine的失败通知评论和事件时间线timeline都是重要上下文应一并纳入观察。该技能的配置见 .agents/skills/flaky-test-investigator/agents/openai.yaml其中allow_implicit_invocation: false表明该 Agent 不允许被隐式调用必须由用户/流程显式触发——这与其高风险诊断的定位一致。二、理解测试环境先定位失败发生在哪里在深入任何根因假设之前必须先回答这次失败发生在什么环境。技能文档列出了四个关键问题并解释了每个问题为什么重要。2.1 本地管道还是 Cloud 管道失败发生在kibana-on-merge本地管道、Cloud 管道还是两者都有为什么重要这告诉你该测试与 Elastic Cloud 是否兼容以及失败更可能是环境问题Cloud 上更常见还是测试自身缺陷两者都失败时更常见。关于本地与 Cloud 管道的完整说明仓库中有一份专用参考文档 .agents/skills/flaky-test-investigator/references/pipelines.md要点如下维度本地管道Kibana CIElastic Cloud 管道典型管道名kibana-on-merge、kibana-pull-request、kibana-flaky-test-suite-runner任何非 Cloud 管道都算本地slug 形如appex-qa-{serverless\|stateful}-kibana-{ftr\|scout}-tests覆盖测试类型Scoutlocal-*标签与 FTR仅 Scout 与 FTRScout 只跑cloud-*标签测试服务器在 agent 本机启动无外部依赖环境更稳定每次运行通过内部 QAF 工具调用 Elastic Cloud API 在 QA 环境创建真实的 Cloud 项目/部署配置覆盖允许自定义 server 配置不允许任何 server 配置覆盖——项目和部署按客户实际形态开通不能覆盖 YAML 设置或传自定义 Kibana/Elasticsearch 参数频率高频因昂贵每天只跑 3 次两条推论直接影响诊断本地通过、Cloud 失败考虑 Cloud 特有的高延迟尤其 MKI、瞬时网络错误、安全模型差异启用 UIAM 时 API key 相关特性行为不同以及 serverless 测试在本地只是 Docker 模拟而非真实 Cloud 环境。FTR 测试若在 FTR config 中依赖了自定义 flag/参数这些参数在 Cloud 项目/部署上不会生效——这类只在本地成立的假设是 flaky 的常见来源。除上述两类外还有两类特殊管道需注意kibana-elasticsearch-snapshot-verify用每日 Elasticsearch 快照而非稳定版从源码构建 Kibanakibana-es-forward-compatibility-testing-branch验证 ES 先于 Kibana 升主版本的滚动升级场景。在这些管道上出现的失败环境因素权重更高。2.2 是否伴随大量无关失败该 Buildkite 构建里是否有大量其他无关测试同时失败为什么重要跨无关测试的广泛失败指向环境或基础设施问题而不是这个测试本身的问题。2.3 测试的 server 配置是默认还是自定义弄清楚Scout 测试用的是默认还是自定义测试服务器配置FTR 测试所属的 test config 是否定义了自定义 server 参数而这些参数在例如 Elastic Cloud 上并不被支持为什么重要自定义 server 配置是 flaky 的常见来源——它们偏离了大多数测试套件使用的配置只影响它们的问题不会在别处暴露而且这些配置往往维护更少。2.4 Scout 场景哪条 lane、哪些邻居共享服务器这是文档中信息密度最高的一条Scout 的 Playwright同一 lane 内的多个 config 共享同一组 Kibana/Elasticsearch 测试服务器状态会在 config 之间泄漏。要把 job 的step_key如scout_test_lane_4映射到它对应的 config 列表方法是从构建的Scout Test Run Builderjobstep_key: build_scout_tests下载.scout/test_lane_loads.json。同一个step_key会按arch/server-config分开调度用 job 的name如 Scout Lane #4 - stateful-classic / default区分物理 lane。并行配置parallel.playwright.config.ts、workers 1下多个 worker 会竞争同一组服务器可能表现为负载下的瞬时超时。为什么重要如果失败的构建中反复出现相同的邻居 config 组合和 arch/server-config 组合应怀疑lane 污染lane pollution而非测试 bug。同时文档特别提醒并行配置下的资源压力看起来像某个测试的特有问题但它本身不是把workers降为 1 的理由。作为对照参考文档还说明了测试分布机制Scout 在本地按 lane 划分跨 config 可能污染在 Cloud 上每个 Playwright config 分配一个全新项目/部署无共享FTR 在本地按组划分、每个 config 启动一套全新服务器跨 config 污染可能性低在 Cloud 上同样是每 config 一个全新项目。三、检查失败产物先取证再立假设文档对这一步的告诫非常直白在深入范围分析或根因假设之前先看 CI 产出的产物。对 UI 测试而言失败时刻的截图往往一分钟内就能解决诊断问题——跳过这一步正是很多调查最终选错修复层级tier of fix的常见原因。对每一次失败应尽量获取以下四类产物失败时刻的截图页面上实际是什么被等待的元素在但选择器不对loading 指示器还在出现错误 toast 或意外弹窗页面空白应用崩溃还是路由不对失败时刻的 DOM/HTML 快照确认测试要找的元素到底在不在 DOM 里区分选择器问题 vs 渲染问题 vs 产品根本没渲染该元素。服务器日志把失败时间戳与服务器错误对照——出现 500 或意外 warning 是产品缺陷而非测试缺陷的强证据。注意日志位置取决于运行器见下文 3.2且日志只记录INFO 级别及以上没有 debug/trace。完整会话 trace框架支持时即 Scout/Playwright可以逐帧回放每个步骤、locator 查询、网络请求和 DOM 快照。3.1 立假设之前必须在产物中确认的四个问题期望的元素渲染出来了吗渲染了但选择器没匹配到 → 不稳定的选择器属于Tier 2 修复范畴。没渲染则要区分not yet测试侧缺少等待与never被等待的状态根本不可达例如组件在异步数据到达时不重新渲染去读渲染该元素的组件源码或在 trace 里找它后来出现的证据。测试缺等待本身并不能证明元素最终会渲染出来。UI 上有可见错误吗toast、banner、HTML 报告里的 console 错误有 → 产品侧问题不是测试侧。页面处于意外状态吗不同 URL、不同用户的数据、不同 space→ 清理或隔离问题往往指向afterEach/afterAll。截图时间戳与失败时间戳一致吗来自先前步骤的过期产物会误导判断。如果产物不可用已过期、未上传、没有read_artifactstoken要在报告中如实说明而不是编造假设——截图本可解决此问题但不可用是报告中一个合法的未决问题。3.2 Kibana 与 Elasticsearch 日志在哪里不同运行器下日志位置不同且都只有 INFO 及以上级别测试类型Kibana 日志Elasticsearch 日志FTR在测试 stdout 中target/test_failures/*.logproc [kibana]行无Scout stateful.scout/server.log.scout/server.log中仅启动阶段的行Scout serverless.scout/server.log无跑在 Docker 里3.3 用 Buildkite CLI 列出并下载失败产物文档给出了可直接复制的命令并解释了每个参数的坑# 列出失败 job 上传的全部产物 bk artifacts list build -p pipeline --job-uuid jobId --json--job-uuid jobId必须传失败那一次 attempt的 job UUID不传的话bk只返回最新一次 attempt会把重试前的失败隐藏掉。如果构建重试后变绿失败产物只存在于失败 job 的 listing 里——在把范围限定到正确的 job UUID 之前不要得出没有截图的结论。# 下载指定产物先 cd 到目标目录download 没有目标路径参数写入当前目录并加 -y 跳过确认 cd dest-dir bk artifacts download artifact-id --build build -p pipeline -y下载策略只下载你真正要读的产物——失败截图、DOM/HTML 快照、相关的target/test_failures/*.log——而不是整个 listing。对大日志用grep/sed定位失败时间戳附近的内容不要从头读到尾。文档还建议直接照用上述命令不要每次重新摸索语法只有当命令不按文档描述工作时才退回bk ... --help。四、理解失败范围scope十问清单文档要求逐一回答以下问题来界定失败范围每个问题都附带为什么重要这个测试失败有多频繁是否存在失败最集中的时间窗口把测试放到一年失败两次到每次 CI 都失败的光谱上定位。为什么集中的失败指向与该窗口绑定的特定原因一次坏提交、基础设施事故、依赖变更。最近一次失败是什么时候为什么如果上次失败在两三周前且failed-testissue 上没有新评论flakiness 可能已经自行解决——无论是有意的还是不相关变更的副作用。测试是否还存在于正在失败的分支上测试可能在main上被删除或迁移如 FTR → Scout但仍在 release 分支上运行。要确定最近一次失败所在的分支并在那个分支上查看文件而不是在main上。为什么如果文件已从main消失失败是分支局部的——修复如有应落在 release 分支基于main代码的推理是错的。同时提醒不要为已不存在的测试浪费时间CI 构建可能没拿到最新分支变更确认删除后就继续。同一套件或同一 config 里的其他测试是否以相同或相似错误失败为什么共享的失败模式指向共享的构件page object、fixture、setup通常需要结构性修改而非逐测试打补丁。它是否只在某个版本分支上失败为什么如果main上不失败比较两个分支找出差异。通过的分支告诉你main缺了什么或多做了什么。也许是测试已在main修复但工程师忘了 backport 到旧版本分支。它第一次失败是什么时候最后一次通过是什么时候为什么把范围收窄到可能引入 flakiness 的 Kibana 提交或 PR。这个 issue 或相关问题是否曾被关闭后又重开为什么重开是上次诊断不成立的最强单一信号——不要重复上次的推理路径。这个测试或测试文件上是否存在一连串修复尝试查找最近 12 个月里标题提到该测试或该区域的多个 PR如 address flaky X、fix flaky X、another attempt at X。为什么相当比例的修复 PR在数月之后又迎来同一区域的下一个修复 PR。如果你正要做第三、第四次尝试前几个方案几乎肯定形态就是错的——不要重复它们。上一次的修复改了什么它声称解决了什么为什么如果上次只动了测试代码且测试又复发这次应更重视产品侧如果上次动了产品代码仍然复发真实 bug 很可能比上次的 diff 更深处。五、对照最佳实践检查测试是否写得稳文档要求把测试与一组最佳实践对照并强调flaky 测试最常违反的条目发现违规是一条值得追查的线索而不是根因的证明。这些实践对应的完整文档都在 docs/extend/testing/scout-best-practices.md 与 docs/extend/testing/ui-best-practices.md 中。选对测试类型见 Pick the right test typeUI 测试天生比组件、API、Jest 单测/集成测试更容易 flaky——如果行为不打开浏览器也能验证就在更低的层级验证。用 API 做 setup/teardown见 Prefer APIs for setup and teardown驱动 UI 做 setup/teardown 更慢也更 flaky。动作后等待 UI 更新见 Wait for UI updates确认动作产生了预期结果、UI 已渲染后再继续。等待复杂 UI 渲染完成见 Wait for complex UI to finish rendering。不用手动重试循环见 Dont use manual retry loops如果一次点击/输入只是有时生效不要重试它——那会掩盖真实用户会遇到的可操作性actionabilitybug。应修复交互本身或等待一个稳定的就绪信号参见下文修复护栏。预期一个共享的测试环境见 Expect a shared test environment测试不能假设干净的部署——其他套件会留下对象Cloud 项目自带预装内容Fleet 仪表盘、预置检测规则、预配置连接器。对列表的断言必须容忍测试自己没创建的条目把查询收窄到测试自己的数据、按身份而非位置定位对象、断言包含而非全集、永远不要断言集群范围内没有某数据空态提示、no data 重定向都依赖全集群无匹配任何清理都无法保证它。不向下一个套件泄漏状态见 Dont leak state into the next suite同一组服务器上你创建/修改的东西对后续套件依然存在。资源名按运行命名空间化、为固定时间戳数据使用套件唯一的时间窗口、拆掉底层资源本身而不只是记录它的 saved object、还原改变行为的 statesettings、feature flag、index template。此外Scout 与 FTR 测试还应遵循 docs/extend/testing/api-best-practices.md 中的 API 最佳实践。六、修复护栏Fix Guardrails什么算修复什么算掩盖任何建议的修复都必须落在共享修复护栏之内.github/workflows/shared/flaky-test-fix-guardrails.md 是修复反模式的单一事实来源single source of truth与自动化修复/验证 workflow 共享。写修复建议之前先读这个文件。其核心规则摘录如下6.1 适用于所有测试的红线绝不用重试或错误容忍来修 flakiness——任何代码都不行。这适用于测试代码、helper、page object、fixture、共享服务、框架包和应用代码问题在于模式本身而非位置不要给断言套retry()/retry.tryForTime不要把click、setValue/输入、goto/导航放进重试里让没点中的交互在下次尝试补上。真实用户不会反复点/输同一个东西重试交互会掩盖真实的 actionability bug元素在视口外、目标了错误的子元素、不稳定的重渲染而且重跑动作会重放它们的副作用把重试叫做等待不改变它的性质用retry.tryForTime包一个查找/读取等 X 渲染出来仍是重试。合法的等待针对具体的可观察信号元素、属性、请求完成走有界的等待 API它不通过反复重跑失败代码直到通过来实现不要对瞬时错误重试 HTTP/认证/API 调用也不要吞掉错误让 flaky 步骤通过。容忍补丁在 flaky-runner 验证时恰好通过正是因为它掩盖了失败其爆炸半径随被补丁代码的共享程度放大——在框架包kbn-test*、kbn-ftr-*、Scout 框架包里最糟因为每个套件都会继承这种掩盖正确做法诊断具体是什么失败了然后修它——让元素先稳定可操作再动作、目标正确的元素、等待显式的就绪信号、或直接修复不可靠的操作本身。若根因在本仓库修不了的基础设施里把诊断移交给负责团队而不是糊上去唯一不属于掩盖的形态让 teardown 幂等例如容忍删除可能不存在的资源时的 404是正确性修复仍然合法。调大超时是最后手段它让测试通过却不解释哪里慢会掩盖真实回归。要先确认慢操作是产品固有的如 index 创建、SLO 计算而不是上游缺了waitForResponse/waitForSelector其他解释都排除后才考虑调超时。Jest 的慢渲染是唯一的例外见 6.3。有产品侧竞态证据时绝不只加测试侧异步钩子await、waitFor、waitUntil这是最常见看起来像修复其实不是的模式——它让测试等更久却没有修掉竞态。不要弱化断言为让测试通过而放宽断言是掩盖回归不是捕获回归。但当断言本身是 bug 时改断言就是修复它期望了产品从未承诺的东西固定顺序、精确计数把错误期望换成正确期望不算弱化。不要削减覆盖面不要 skip/exclude 测试来消灭失败——对功能测试意味着剥掉 tag 让它不在某些环境如 Cloud或项目类型如 serverless Security跑对单测意味着describe.skip/it.skip。它在那儿 flaky不是理由它在那儿不该跑才是。只用框架文档化的公共 API不要为启用一个修复而扩大框架包的公共面例如导出内部 tag 计算 helper而不是用文档化的tags常量。文档化 API 表达不了这个修复那是给框架负责团队提 feature request 的事不该混进修复 PR。不要从邻近代码抄遗留模式邻居测试或同文件 sibling helper 里现成的 retry 包裹代码是待修的遗留不是要对齐的模式。6.2 功能测试Scout、FTR、Cypress的要点等待流程的终端就绪信号——即失败断言真正读取的那个——而不是前面的某一步。等待型修复静默失败的最常见方式就是守错了步骤给点击加 wait 或{ force: true }、关掉一个 toast、等一个中间渲染而断言实际读取的元素/值仍在竞态。要识别哪一步产生了报告的错误然后等那一步。默认信号是展示该数据的已渲染元素——web-first 断言expect(locator).toBeVisible()会自动等待它永远不要等代理信号spinner 消失、无关的渲染。若测试需要的状态没有元素可等首选的小型应用侧修复是在 DOM 中暴露一个data-test-subj、data-loaded属性、状态标记不同于网络等待它反映的是已提交的渲染、能扛住端点/缓存/传输层变更、也不需要动作前布防的时序。若 flake 来自数据到达而非渲染优先让 gate 变得确定mock 端点、API 预置数据而不是等它。最后手段——完全没有 UI 的 gate后台写入、setup 前置条件——才退回网络等待page.waitForResponse(...)且必须在触发动作之前布防。即便如此它仍脆弱响应解决不代表 DOM 已更新、测试被耦合到端点且应用对同一端点发多个请求时如仪表盘加载多个面板可能匹配错。轮询读取是合法等待重跑动作或抛错的代码块不是。有界地求值一个值/条件并在匹配时收敛的轮询——web-first 断言、expect.poll/toPass、对布尔条件的retry.waitForWithTimeout——是上面通过有界等待 API 观察信号所允许的形式因为它从不循环一个抛出的错误。循环内部要重新查询一次性捕获的 handle、或只重查一次都会过期。仍然禁止重发click/输入/goto或任务/HTTP 调用以及重跑抛错的查找/断言直到不抛retry.tryForTime/retry.try包existOrFail或断言——那是重跑失败代码不是轮询值。优先消除竞态而不是等过竞态。让 gate 确定化——mock 掉 gate 端点或在 setup 中通过 API 注入流程需要的 fixture——让数据在流程开始前就位。写后读旧/读空是传播propagation问题——先诊断归谁再叫它环境问题。就绪信号满足但后续读取返回旧值或空值config 轮询、缓存、ES refresh、entity store 或集群同步、多节点延迟时加大超时只是掩盖。先判定三选一存在收敛信号而测试没用→ 等那个信号refreshwait_for的 index、轮询读取不存在这样的信号→ 这是应用层的可观察性缺口建议暴露一个事件、状态字段、端点而不是在测试里循环产品本应 read-your-writes 一致却返回旧值或报错写后缓存未失效、瞬时 unknown index 暴露给用户→ 这是测试正确抓住的应用 bug修产品。 把test-environment留给共享环境干扰、ci-environment留给有实证支撑的 CI/基础设施原因——不要用来装产品自身的收敛行为那属于 (1)(2)(3) 之一。同测试、不同步骤的复发是新 flake不是你的等待错了的证明。当修复针对的失败签名消失了、测试改在另一步骤竞态原修复是成立的把新步骤当作独立 flake套用同样的就绪规则处理。若测试不断在后续步骤冒出新的竞态说明它通过 UI 驱动的东西太多——优先收敛流程用 API 建立状态或拆分测试而不是把等待一个接一个堆上去。若测试在并行负载下确实慢调超时也没用把 spec 从并行运行移到顺序运行。遵循 docs/extend/testing/ 中的测试最佳实践scout-best-practices.md、ui-best-practices.md、api-best-practices.md即使周围的测试文件早于这些实践。6.3 Jest 与 React Testing Libraryflaky 通常是成本问题而非等待问题文档单独指出Jest/RTL 的 flake 大多是成本问题。适用于测试超时或 React 警告 update 未包在act里CI 会隐藏该警告只有本地跑时才看得到的失败。断言写错、数据不确定、产品 bug 是另一类问题另案处理。背景这类测试默认有 5 秒预算文件/插件可上调单个waitFor/findBy*就能花掉其中 4.5 秒CI 并行负载下的慢渲染就会超时。站得住的修复是让测试更便宜或修掉原因删掉异步步骤让无可等待——RTL 把fireEvent包在act里同步状态更新在返回时已应用下一行即可getBy…读取。只有当更新真的等待 promise 或定时器时才保留findBy*/waitFor——目标是删掉异步步骤而不是隔着它断言直接以想检查的状态渲染组件而不是点过去测更小的单元一个组件、一个 hook、一个纯函数而不是整页mock 掉所有不断言的重型子组件mock 一部分通常省得不够有底层缺陷就修漏await、真正晚到的值其断言应放进waitFor、不确定数据、产品 bug。站不住的做法留着慢渲染只换等待方式——换个更轻的 provider 但同样挂载该组件、或重调userEvent/act/waitFor如delay: null只有当渲染本身已经便宜时它们才有用。提高 Jest 超时是唯一的合法超时上调当渲染本身就是慢点、且没有任何更早的信号可等在减成本但不能少掉测试要检查的东西之后上调超时是真修复而非掩盖。按测试it(…, ms)、文件jest.setTimeout(ms)或插件jest.config.js的testTimeout上调并留出远大于实测最慢运行的余量——上调 1 秒只是挪了边界。上调的是 Jest 超时永远不是waitFor/findBy*的超时对慢渲染等更久毫无收益。七、调查陷阱清单Investigation Pitfalls文档列出了八条最容易把调查带偏的陷阱每条都值得内化忽视大局在下结论前先为测试环境和相关失败同测试文件、同 test config、或其他地方建立扎实的数据基线。单独信任 flaky-test-runner全绿运行不证明修复站住了。runner 隔离地跑测试而实际情况未必隔离Scout 测试运行中多个 test config 共享同一组测试服务器它也是本地管道无法复刻真实 Elastic Cloud 环境——对 Cloud 管道上发生的失败flaky-runner 全绿几乎不能说明修复在 Cloud 上也成立。默认修测试别修产品先问产品是否也有责任。只改测试的修复耐久性显著低于改动生产代码的修复。从抛错的栈帧读责任等待侧超时永远从等待方FTR/Playwright 服务代码抛出栈帧告诉你谁抛的不告诉你谁的责任——它不是产品无责的证据。不比对失败签名就归咎于之前的修复在下结论说早先修复没守住之前先确认这次复发带着该修复所针对的同一错误签名同一元素/断言/调用点。修复可以是正确的而测试在另一个步骤仍然 flaky——那是一个新的独立 flake不是失败的修复应独立诊断。若测试不断在后续步骤冒出新竞态考虑减少 UI 交互API 驱动的 setup/teardown或拆分测试而不是堆等待。把修复前的 Cloud 构建计入复发Cloud 镜像滞后于main修复刚合并后报告的失败可能跑的是修复之前的 checkout。应解析该运行的Build hash用 GitHub compare API 确认构建包含修复后再当作复发——否则那是传播延迟不是修复失败。参考文档给出的做法在 Buildkite 日志中找Build hash:serverless 项目在Project information下、stateful 部署在Deployment information下日志组分别以Create {security|observability|...} project与Create deployment开头然后gh api repos/elastic/kibana/compare/fix-merge-sha...build-hash --jq .statusahead或identical→ 构建包含修复失败计入behind或diverged→ 构建早于修复跑的是修复前代码这是预期的传播延迟而非复发归类为ci-environment不要把修复当作已回归。 等价判断构建包含修复当且仅当.merge_base_commit.sha等于修复的 merge commit。该方式一次 API 调用即可无需本地git fetch——完整拉取 Kibana 很慢。报告虚假的确定性我不知道这是两个合理假设以及能区分它们需要什么证据比一个自信的错答案对负责团队更有用。八、修复值得做吗先考虑替代方案有了诊断之后正确的下一步不总是改代码。文档要求在推荐代码修复前权衡以下替代删掉这个测试其他测试是否已经覆盖了它验证的东西重构或降级测试类型参考 Pick the right test type——一个功能测试常常可以变成 API、组件或 Jest 单测/集成测试。更新 tag测试的 tag 是否仍然合适它该在 Cloud 上跑吗该不该从某些 serverless solution 类型如 Security中排除升级给负责团队若这是惯犯或你怀疑产品 bug最有用的结论可能就是交给 owner 的一份问题陈述而不是一次修复尝试。九、报告模板结论要包含的八个部分调查的最终产出是一份结构化报告必须包含测试做什么一段话什么失败了、何时失败最近一次失败 随时间的失败次数在哪里跑的Cloud、本地管道或两者根因假设几句话描述调查结论支持该假设的证据以及反对它的证据如果考虑过替代假设把它们连同各自的置信度一并列出失败截图描述你在失败截图里观察到了什么建议的下一步不总是代码修改若推荐代码修复附一句关于预期耐久性的诚实评估未决问题调查未能解决的问题。十、方法论总结这条工作流背后的三条原则通读 SKILL.md 及其引用文档references/pipelines.md、flaky-test-fix-guardrails.md、scout-best-practices.md、ui-best-practices.md可以提炼出 Kibana flaky 测试治理的三条主线环境先于代码本地/Cloud 差异、lane 共享、自定义 server 配置、Cloud 镜像滞后于main——这些结构性事实决定了失败签名的解读方式必须在任何根因假设之前建立证据先于结论截图、DOM 快照、INFO 级以上的服务器日志、完整 trace 是取证的四级火箭产物缺失就如实报告绝不编造假设两个合理假设 区分它们需要什么优于自信的错答案修复必须可耐久验证重试与错误容忍在任何代码层都是掩盖、等待必须锚定断言真正读取的终端就绪信号、超时上调仅限 Jest 慢渲染这一种情形——护栏文件是自动化修复与验证 workflow 共享的单一事实来源人工与 Agent 的修复建议都必须服从同一约束这正是flaky-runner 全绿才叫修复站住的前提。【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Kibana Flaky 测试调查指南：从 CI 失败到根因诊断的完整方法论
Kibana Flaky 测试调查指南从 CI 失败到根因诊断的完整方法论【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana本文基于 Kibana 仓库中的 Agent 技能文档 .agents/skills/flaky-test-investigator/SKILL.md 整理系统讲解如何调查 Scout 与 FTR 功能测试中的不稳定flaky失败从获取一个failed-test标签的 GitHub issue 出发依次经过测试环境分析、失败产物截图/DOM/日志/trace取证、失败范围界定、最佳实践对照、修复护栏guardrails约束直至输出一份结构化调查报告。读完本文你可以掌握 Kibana 官方的 flaky 测试分诊流程能够区分测试自身缺陷、产品缺陷、环境/基础设施问题三类根因并给出经得起复发的长期修复建议。一、技能定位诊断优先而非快速止血该技能flaky-test-investigator明确定义了调查的目标与合法结论产出要求结论应是一个准确的诊断和稳健的长期修复而不是治标不治本的快速修复quick fix合法结论包括以下三种之一这是真实的产品缺陷应升级escalate给负责团队这是环境性问题很可能自行恢复现有数据不足以得出有信心的结论。最后一条尤为重要Kibana 官方把承认不知道视为一种有效且值得报告的结论而不是需要掩饰的失败。必需输入failed-test issue调查的入口是一个带failed-test标签的 GitHub issue 链接如果没有提供应先索取再开始。技能文档强调两点该 issue 上可能已有自动化流程automation发布的历史根因分析或修复建议要参考但必须独立做研究、独立下结论——历史分析可能基于更少的数据或基于过时的排障指南issue 中的其他评论包括kibanamachine的失败通知评论和事件时间线timeline都是重要上下文应一并纳入观察。该技能的配置见 .agents/skills/flaky-test-investigator/agents/openai.yaml其中allow_implicit_invocation: false表明该 Agent 不允许被隐式调用必须由用户/流程显式触发——这与其高风险诊断的定位一致。二、理解测试环境先定位失败发生在哪里在深入任何根因假设之前必须先回答这次失败发生在什么环境。技能文档列出了四个关键问题并解释了每个问题为什么重要。2.1 本地管道还是 Cloud 管道失败发生在kibana-on-merge本地管道、Cloud 管道还是两者都有为什么重要这告诉你该测试与 Elastic Cloud 是否兼容以及失败更可能是环境问题Cloud 上更常见还是测试自身缺陷两者都失败时更常见。关于本地与 Cloud 管道的完整说明仓库中有一份专用参考文档 .agents/skills/flaky-test-investigator/references/pipelines.md要点如下维度本地管道Kibana CIElastic Cloud 管道典型管道名kibana-on-merge、kibana-pull-request、kibana-flaky-test-suite-runner任何非 Cloud 管道都算本地slug 形如appex-qa-{serverless\|stateful}-kibana-{ftr\|scout}-tests覆盖测试类型Scoutlocal-*标签与 FTR仅 Scout 与 FTRScout 只跑cloud-*标签测试服务器在 agent 本机启动无外部依赖环境更稳定每次运行通过内部 QAF 工具调用 Elastic Cloud API 在 QA 环境创建真实的 Cloud 项目/部署配置覆盖允许自定义 server 配置不允许任何 server 配置覆盖——项目和部署按客户实际形态开通不能覆盖 YAML 设置或传自定义 Kibana/Elasticsearch 参数频率高频因昂贵每天只跑 3 次两条推论直接影响诊断本地通过、Cloud 失败考虑 Cloud 特有的高延迟尤其 MKI、瞬时网络错误、安全模型差异启用 UIAM 时 API key 相关特性行为不同以及 serverless 测试在本地只是 Docker 模拟而非真实 Cloud 环境。FTR 测试若在 FTR config 中依赖了自定义 flag/参数这些参数在 Cloud 项目/部署上不会生效——这类只在本地成立的假设是 flaky 的常见来源。除上述两类外还有两类特殊管道需注意kibana-elasticsearch-snapshot-verify用每日 Elasticsearch 快照而非稳定版从源码构建 Kibanakibana-es-forward-compatibility-testing-branch验证 ES 先于 Kibana 升主版本的滚动升级场景。在这些管道上出现的失败环境因素权重更高。2.2 是否伴随大量无关失败该 Buildkite 构建里是否有大量其他无关测试同时失败为什么重要跨无关测试的广泛失败指向环境或基础设施问题而不是这个测试本身的问题。2.3 测试的 server 配置是默认还是自定义弄清楚Scout 测试用的是默认还是自定义测试服务器配置FTR 测试所属的 test config 是否定义了自定义 server 参数而这些参数在例如 Elastic Cloud 上并不被支持为什么重要自定义 server 配置是 flaky 的常见来源——它们偏离了大多数测试套件使用的配置只影响它们的问题不会在别处暴露而且这些配置往往维护更少。2.4 Scout 场景哪条 lane、哪些邻居共享服务器这是文档中信息密度最高的一条Scout 的 Playwright同一 lane 内的多个 config 共享同一组 Kibana/Elasticsearch 测试服务器状态会在 config 之间泄漏。要把 job 的step_key如scout_test_lane_4映射到它对应的 config 列表方法是从构建的Scout Test Run Builderjobstep_key: build_scout_tests下载.scout/test_lane_loads.json。同一个step_key会按arch/server-config分开调度用 job 的name如 Scout Lane #4 - stateful-classic / default区分物理 lane。并行配置parallel.playwright.config.ts、workers 1下多个 worker 会竞争同一组服务器可能表现为负载下的瞬时超时。为什么重要如果失败的构建中反复出现相同的邻居 config 组合和 arch/server-config 组合应怀疑lane 污染lane pollution而非测试 bug。同时文档特别提醒并行配置下的资源压力看起来像某个测试的特有问题但它本身不是把workers降为 1 的理由。作为对照参考文档还说明了测试分布机制Scout 在本地按 lane 划分跨 config 可能污染在 Cloud 上每个 Playwright config 分配一个全新项目/部署无共享FTR 在本地按组划分、每个 config 启动一套全新服务器跨 config 污染可能性低在 Cloud 上同样是每 config 一个全新项目。三、检查失败产物先取证再立假设文档对这一步的告诫非常直白在深入范围分析或根因假设之前先看 CI 产出的产物。对 UI 测试而言失败时刻的截图往往一分钟内就能解决诊断问题——跳过这一步正是很多调查最终选错修复层级tier of fix的常见原因。对每一次失败应尽量获取以下四类产物失败时刻的截图页面上实际是什么被等待的元素在但选择器不对loading 指示器还在出现错误 toast 或意外弹窗页面空白应用崩溃还是路由不对失败时刻的 DOM/HTML 快照确认测试要找的元素到底在不在 DOM 里区分选择器问题 vs 渲染问题 vs 产品根本没渲染该元素。服务器日志把失败时间戳与服务器错误对照——出现 500 或意外 warning 是产品缺陷而非测试缺陷的强证据。注意日志位置取决于运行器见下文 3.2且日志只记录INFO 级别及以上没有 debug/trace。完整会话 trace框架支持时即 Scout/Playwright可以逐帧回放每个步骤、locator 查询、网络请求和 DOM 快照。3.1 立假设之前必须在产物中确认的四个问题期望的元素渲染出来了吗渲染了但选择器没匹配到 → 不稳定的选择器属于Tier 2 修复范畴。没渲染则要区分not yet测试侧缺少等待与never被等待的状态根本不可达例如组件在异步数据到达时不重新渲染去读渲染该元素的组件源码或在 trace 里找它后来出现的证据。测试缺等待本身并不能证明元素最终会渲染出来。UI 上有可见错误吗toast、banner、HTML 报告里的 console 错误有 → 产品侧问题不是测试侧。页面处于意外状态吗不同 URL、不同用户的数据、不同 space→ 清理或隔离问题往往指向afterEach/afterAll。截图时间戳与失败时间戳一致吗来自先前步骤的过期产物会误导判断。如果产物不可用已过期、未上传、没有read_artifactstoken要在报告中如实说明而不是编造假设——截图本可解决此问题但不可用是报告中一个合法的未决问题。3.2 Kibana 与 Elasticsearch 日志在哪里不同运行器下日志位置不同且都只有 INFO 及以上级别测试类型Kibana 日志Elasticsearch 日志FTR在测试 stdout 中target/test_failures/*.logproc [kibana]行无Scout stateful.scout/server.log.scout/server.log中仅启动阶段的行Scout serverless.scout/server.log无跑在 Docker 里3.3 用 Buildkite CLI 列出并下载失败产物文档给出了可直接复制的命令并解释了每个参数的坑# 列出失败 job 上传的全部产物 bk artifacts list build -p pipeline --job-uuid jobId --json--job-uuid jobId必须传失败那一次 attempt的 job UUID不传的话bk只返回最新一次 attempt会把重试前的失败隐藏掉。如果构建重试后变绿失败产物只存在于失败 job 的 listing 里——在把范围限定到正确的 job UUID 之前不要得出没有截图的结论。# 下载指定产物先 cd 到目标目录download 没有目标路径参数写入当前目录并加 -y 跳过确认 cd dest-dir bk artifacts download artifact-id --build build -p pipeline -y下载策略只下载你真正要读的产物——失败截图、DOM/HTML 快照、相关的target/test_failures/*.log——而不是整个 listing。对大日志用grep/sed定位失败时间戳附近的内容不要从头读到尾。文档还建议直接照用上述命令不要每次重新摸索语法只有当命令不按文档描述工作时才退回bk ... --help。四、理解失败范围scope十问清单文档要求逐一回答以下问题来界定失败范围每个问题都附带为什么重要这个测试失败有多频繁是否存在失败最集中的时间窗口把测试放到一年失败两次到每次 CI 都失败的光谱上定位。为什么集中的失败指向与该窗口绑定的特定原因一次坏提交、基础设施事故、依赖变更。最近一次失败是什么时候为什么如果上次失败在两三周前且failed-testissue 上没有新评论flakiness 可能已经自行解决——无论是有意的还是不相关变更的副作用。测试是否还存在于正在失败的分支上测试可能在main上被删除或迁移如 FTR → Scout但仍在 release 分支上运行。要确定最近一次失败所在的分支并在那个分支上查看文件而不是在main上。为什么如果文件已从main消失失败是分支局部的——修复如有应落在 release 分支基于main代码的推理是错的。同时提醒不要为已不存在的测试浪费时间CI 构建可能没拿到最新分支变更确认删除后就继续。同一套件或同一 config 里的其他测试是否以相同或相似错误失败为什么共享的失败模式指向共享的构件page object、fixture、setup通常需要结构性修改而非逐测试打补丁。它是否只在某个版本分支上失败为什么如果main上不失败比较两个分支找出差异。通过的分支告诉你main缺了什么或多做了什么。也许是测试已在main修复但工程师忘了 backport 到旧版本分支。它第一次失败是什么时候最后一次通过是什么时候为什么把范围收窄到可能引入 flakiness 的 Kibana 提交或 PR。这个 issue 或相关问题是否曾被关闭后又重开为什么重开是上次诊断不成立的最强单一信号——不要重复上次的推理路径。这个测试或测试文件上是否存在一连串修复尝试查找最近 12 个月里标题提到该测试或该区域的多个 PR如 address flaky X、fix flaky X、another attempt at X。为什么相当比例的修复 PR在数月之后又迎来同一区域的下一个修复 PR。如果你正要做第三、第四次尝试前几个方案几乎肯定形态就是错的——不要重复它们。上一次的修复改了什么它声称解决了什么为什么如果上次只动了测试代码且测试又复发这次应更重视产品侧如果上次动了产品代码仍然复发真实 bug 很可能比上次的 diff 更深处。五、对照最佳实践检查测试是否写得稳文档要求把测试与一组最佳实践对照并强调flaky 测试最常违反的条目发现违规是一条值得追查的线索而不是根因的证明。这些实践对应的完整文档都在 docs/extend/testing/scout-best-practices.md 与 docs/extend/testing/ui-best-practices.md 中。选对测试类型见 Pick the right test typeUI 测试天生比组件、API、Jest 单测/集成测试更容易 flaky——如果行为不打开浏览器也能验证就在更低的层级验证。用 API 做 setup/teardown见 Prefer APIs for setup and teardown驱动 UI 做 setup/teardown 更慢也更 flaky。动作后等待 UI 更新见 Wait for UI updates确认动作产生了预期结果、UI 已渲染后再继续。等待复杂 UI 渲染完成见 Wait for complex UI to finish rendering。不用手动重试循环见 Dont use manual retry loops如果一次点击/输入只是有时生效不要重试它——那会掩盖真实用户会遇到的可操作性actionabilitybug。应修复交互本身或等待一个稳定的就绪信号参见下文修复护栏。预期一个共享的测试环境见 Expect a shared test environment测试不能假设干净的部署——其他套件会留下对象Cloud 项目自带预装内容Fleet 仪表盘、预置检测规则、预配置连接器。对列表的断言必须容忍测试自己没创建的条目把查询收窄到测试自己的数据、按身份而非位置定位对象、断言包含而非全集、永远不要断言集群范围内没有某数据空态提示、no data 重定向都依赖全集群无匹配任何清理都无法保证它。不向下一个套件泄漏状态见 Dont leak state into the next suite同一组服务器上你创建/修改的东西对后续套件依然存在。资源名按运行命名空间化、为固定时间戳数据使用套件唯一的时间窗口、拆掉底层资源本身而不只是记录它的 saved object、还原改变行为的 statesettings、feature flag、index template。此外Scout 与 FTR 测试还应遵循 docs/extend/testing/api-best-practices.md 中的 API 最佳实践。六、修复护栏Fix Guardrails什么算修复什么算掩盖任何建议的修复都必须落在共享修复护栏之内.github/workflows/shared/flaky-test-fix-guardrails.md 是修复反模式的单一事实来源single source of truth与自动化修复/验证 workflow 共享。写修复建议之前先读这个文件。其核心规则摘录如下6.1 适用于所有测试的红线绝不用重试或错误容忍来修 flakiness——任何代码都不行。这适用于测试代码、helper、page object、fixture、共享服务、框架包和应用代码问题在于模式本身而非位置不要给断言套retry()/retry.tryForTime不要把click、setValue/输入、goto/导航放进重试里让没点中的交互在下次尝试补上。真实用户不会反复点/输同一个东西重试交互会掩盖真实的 actionability bug元素在视口外、目标了错误的子元素、不稳定的重渲染而且重跑动作会重放它们的副作用把重试叫做等待不改变它的性质用retry.tryForTime包一个查找/读取等 X 渲染出来仍是重试。合法的等待针对具体的可观察信号元素、属性、请求完成走有界的等待 API它不通过反复重跑失败代码直到通过来实现不要对瞬时错误重试 HTTP/认证/API 调用也不要吞掉错误让 flaky 步骤通过。容忍补丁在 flaky-runner 验证时恰好通过正是因为它掩盖了失败其爆炸半径随被补丁代码的共享程度放大——在框架包kbn-test*、kbn-ftr-*、Scout 框架包里最糟因为每个套件都会继承这种掩盖正确做法诊断具体是什么失败了然后修它——让元素先稳定可操作再动作、目标正确的元素、等待显式的就绪信号、或直接修复不可靠的操作本身。若根因在本仓库修不了的基础设施里把诊断移交给负责团队而不是糊上去唯一不属于掩盖的形态让 teardown 幂等例如容忍删除可能不存在的资源时的 404是正确性修复仍然合法。调大超时是最后手段它让测试通过却不解释哪里慢会掩盖真实回归。要先确认慢操作是产品固有的如 index 创建、SLO 计算而不是上游缺了waitForResponse/waitForSelector其他解释都排除后才考虑调超时。Jest 的慢渲染是唯一的例外见 6.3。有产品侧竞态证据时绝不只加测试侧异步钩子await、waitFor、waitUntil这是最常见看起来像修复其实不是的模式——它让测试等更久却没有修掉竞态。不要弱化断言为让测试通过而放宽断言是掩盖回归不是捕获回归。但当断言本身是 bug 时改断言就是修复它期望了产品从未承诺的东西固定顺序、精确计数把错误期望换成正确期望不算弱化。不要削减覆盖面不要 skip/exclude 测试来消灭失败——对功能测试意味着剥掉 tag 让它不在某些环境如 Cloud或项目类型如 serverless Security跑对单测意味着describe.skip/it.skip。它在那儿 flaky不是理由它在那儿不该跑才是。只用框架文档化的公共 API不要为启用一个修复而扩大框架包的公共面例如导出内部 tag 计算 helper而不是用文档化的tags常量。文档化 API 表达不了这个修复那是给框架负责团队提 feature request 的事不该混进修复 PR。不要从邻近代码抄遗留模式邻居测试或同文件 sibling helper 里现成的 retry 包裹代码是待修的遗留不是要对齐的模式。6.2 功能测试Scout、FTR、Cypress的要点等待流程的终端就绪信号——即失败断言真正读取的那个——而不是前面的某一步。等待型修复静默失败的最常见方式就是守错了步骤给点击加 wait 或{ force: true }、关掉一个 toast、等一个中间渲染而断言实际读取的元素/值仍在竞态。要识别哪一步产生了报告的错误然后等那一步。默认信号是展示该数据的已渲染元素——web-first 断言expect(locator).toBeVisible()会自动等待它永远不要等代理信号spinner 消失、无关的渲染。若测试需要的状态没有元素可等首选的小型应用侧修复是在 DOM 中暴露一个data-test-subj、data-loaded属性、状态标记不同于网络等待它反映的是已提交的渲染、能扛住端点/缓存/传输层变更、也不需要动作前布防的时序。若 flake 来自数据到达而非渲染优先让 gate 变得确定mock 端点、API 预置数据而不是等它。最后手段——完全没有 UI 的 gate后台写入、setup 前置条件——才退回网络等待page.waitForResponse(...)且必须在触发动作之前布防。即便如此它仍脆弱响应解决不代表 DOM 已更新、测试被耦合到端点且应用对同一端点发多个请求时如仪表盘加载多个面板可能匹配错。轮询读取是合法等待重跑动作或抛错的代码块不是。有界地求值一个值/条件并在匹配时收敛的轮询——web-first 断言、expect.poll/toPass、对布尔条件的retry.waitForWithTimeout——是上面通过有界等待 API 观察信号所允许的形式因为它从不循环一个抛出的错误。循环内部要重新查询一次性捕获的 handle、或只重查一次都会过期。仍然禁止重发click/输入/goto或任务/HTTP 调用以及重跑抛错的查找/断言直到不抛retry.tryForTime/retry.try包existOrFail或断言——那是重跑失败代码不是轮询值。优先消除竞态而不是等过竞态。让 gate 确定化——mock 掉 gate 端点或在 setup 中通过 API 注入流程需要的 fixture——让数据在流程开始前就位。写后读旧/读空是传播propagation问题——先诊断归谁再叫它环境问题。就绪信号满足但后续读取返回旧值或空值config 轮询、缓存、ES refresh、entity store 或集群同步、多节点延迟时加大超时只是掩盖。先判定三选一存在收敛信号而测试没用→ 等那个信号refreshwait_for的 index、轮询读取不存在这样的信号→ 这是应用层的可观察性缺口建议暴露一个事件、状态字段、端点而不是在测试里循环产品本应 read-your-writes 一致却返回旧值或报错写后缓存未失效、瞬时 unknown index 暴露给用户→ 这是测试正确抓住的应用 bug修产品。 把test-environment留给共享环境干扰、ci-environment留给有实证支撑的 CI/基础设施原因——不要用来装产品自身的收敛行为那属于 (1)(2)(3) 之一。同测试、不同步骤的复发是新 flake不是你的等待错了的证明。当修复针对的失败签名消失了、测试改在另一步骤竞态原修复是成立的把新步骤当作独立 flake套用同样的就绪规则处理。若测试不断在后续步骤冒出新的竞态说明它通过 UI 驱动的东西太多——优先收敛流程用 API 建立状态或拆分测试而不是把等待一个接一个堆上去。若测试在并行负载下确实慢调超时也没用把 spec 从并行运行移到顺序运行。遵循 docs/extend/testing/ 中的测试最佳实践scout-best-practices.md、ui-best-practices.md、api-best-practices.md即使周围的测试文件早于这些实践。6.3 Jest 与 React Testing Libraryflaky 通常是成本问题而非等待问题文档单独指出Jest/RTL 的 flake 大多是成本问题。适用于测试超时或 React 警告 update 未包在act里CI 会隐藏该警告只有本地跑时才看得到的失败。断言写错、数据不确定、产品 bug 是另一类问题另案处理。背景这类测试默认有 5 秒预算文件/插件可上调单个waitFor/findBy*就能花掉其中 4.5 秒CI 并行负载下的慢渲染就会超时。站得住的修复是让测试更便宜或修掉原因删掉异步步骤让无可等待——RTL 把fireEvent包在act里同步状态更新在返回时已应用下一行即可getBy…读取。只有当更新真的等待 promise 或定时器时才保留findBy*/waitFor——目标是删掉异步步骤而不是隔着它断言直接以想检查的状态渲染组件而不是点过去测更小的单元一个组件、一个 hook、一个纯函数而不是整页mock 掉所有不断言的重型子组件mock 一部分通常省得不够有底层缺陷就修漏await、真正晚到的值其断言应放进waitFor、不确定数据、产品 bug。站不住的做法留着慢渲染只换等待方式——换个更轻的 provider 但同样挂载该组件、或重调userEvent/act/waitFor如delay: null只有当渲染本身已经便宜时它们才有用。提高 Jest 超时是唯一的合法超时上调当渲染本身就是慢点、且没有任何更早的信号可等在减成本但不能少掉测试要检查的东西之后上调超时是真修复而非掩盖。按测试it(…, ms)、文件jest.setTimeout(ms)或插件jest.config.js的testTimeout上调并留出远大于实测最慢运行的余量——上调 1 秒只是挪了边界。上调的是 Jest 超时永远不是waitFor/findBy*的超时对慢渲染等更久毫无收益。七、调查陷阱清单Investigation Pitfalls文档列出了八条最容易把调查带偏的陷阱每条都值得内化忽视大局在下结论前先为测试环境和相关失败同测试文件、同 test config、或其他地方建立扎实的数据基线。单独信任 flaky-test-runner全绿运行不证明修复站住了。runner 隔离地跑测试而实际情况未必隔离Scout 测试运行中多个 test config 共享同一组测试服务器它也是本地管道无法复刻真实 Elastic Cloud 环境——对 Cloud 管道上发生的失败flaky-runner 全绿几乎不能说明修复在 Cloud 上也成立。默认修测试别修产品先问产品是否也有责任。只改测试的修复耐久性显著低于改动生产代码的修复。从抛错的栈帧读责任等待侧超时永远从等待方FTR/Playwright 服务代码抛出栈帧告诉你谁抛的不告诉你谁的责任——它不是产品无责的证据。不比对失败签名就归咎于之前的修复在下结论说早先修复没守住之前先确认这次复发带着该修复所针对的同一错误签名同一元素/断言/调用点。修复可以是正确的而测试在另一个步骤仍然 flaky——那是一个新的独立 flake不是失败的修复应独立诊断。若测试不断在后续步骤冒出新竞态考虑减少 UI 交互API 驱动的 setup/teardown或拆分测试而不是堆等待。把修复前的 Cloud 构建计入复发Cloud 镜像滞后于main修复刚合并后报告的失败可能跑的是修复之前的 checkout。应解析该运行的Build hash用 GitHub compare API 确认构建包含修复后再当作复发——否则那是传播延迟不是修复失败。参考文档给出的做法在 Buildkite 日志中找Build hash:serverless 项目在Project information下、stateful 部署在Deployment information下日志组分别以Create {security|observability|...} project与Create deployment开头然后gh api repos/elastic/kibana/compare/fix-merge-sha...build-hash --jq .statusahead或identical→ 构建包含修复失败计入behind或diverged→ 构建早于修复跑的是修复前代码这是预期的传播延迟而非复发归类为ci-environment不要把修复当作已回归。 等价判断构建包含修复当且仅当.merge_base_commit.sha等于修复的 merge commit。该方式一次 API 调用即可无需本地git fetch——完整拉取 Kibana 很慢。报告虚假的确定性我不知道这是两个合理假设以及能区分它们需要什么证据比一个自信的错答案对负责团队更有用。八、修复值得做吗先考虑替代方案有了诊断之后正确的下一步不总是改代码。文档要求在推荐代码修复前权衡以下替代删掉这个测试其他测试是否已经覆盖了它验证的东西重构或降级测试类型参考 Pick the right test type——一个功能测试常常可以变成 API、组件或 Jest 单测/集成测试。更新 tag测试的 tag 是否仍然合适它该在 Cloud 上跑吗该不该从某些 serverless solution 类型如 Security中排除升级给负责团队若这是惯犯或你怀疑产品 bug最有用的结论可能就是交给 owner 的一份问题陈述而不是一次修复尝试。九、报告模板结论要包含的八个部分调查的最终产出是一份结构化报告必须包含测试做什么一段话什么失败了、何时失败最近一次失败 随时间的失败次数在哪里跑的Cloud、本地管道或两者根因假设几句话描述调查结论支持该假设的证据以及反对它的证据如果考虑过替代假设把它们连同各自的置信度一并列出失败截图描述你在失败截图里观察到了什么建议的下一步不总是代码修改若推荐代码修复附一句关于预期耐久性的诚实评估未决问题调查未能解决的问题。十、方法论总结这条工作流背后的三条原则通读 SKILL.md 及其引用文档references/pipelines.md、flaky-test-fix-guardrails.md、scout-best-practices.md、ui-best-practices.md可以提炼出 Kibana flaky 测试治理的三条主线环境先于代码本地/Cloud 差异、lane 共享、自定义 server 配置、Cloud 镜像滞后于main——这些结构性事实决定了失败签名的解读方式必须在任何根因假设之前建立证据先于结论截图、DOM 快照、INFO 级以上的服务器日志、完整 trace 是取证的四级火箭产物缺失就如实报告绝不编造假设两个合理假设 区分它们需要什么优于自信的错答案修复必须可耐久验证重试与错误容忍在任何代码层都是掩盖、等待必须锚定断言真正读取的终端就绪信号、超时上调仅限 Jest 慢渲染这一种情形——护栏文件是自动化修复与验证 workflow 共享的单一事实来源人工与 Agent 的修复建议都必须服从同一约束这正是flaky-runner 全绿才叫修复站住的前提。【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考