Flaky Test 排查实战:从偶发失败到稳定 CI 的完整思路
自动化测试跑着跑着,某条用例突然红了,你点进去重跑一遍,绿的。再跑一遍,又红了。这种"薛定谔的失败"就是 Flaky Test,中文一般叫"偶发失败"或"不稳定用例"。它比稳定失败的用例更让人头疼,因为稳定失败至少说明代码或环境有确定性问题,而偶发失败像幽灵一样,今天出现明天消失,CI 流水线上飘忽不定,团队里每个人都被它折磨过。我做了七八年自动化测试,踩过的 Flaky 坑少说也有上百个,从最早的 Selenium 时代到现在的 Playwright、Appium、pytest 体系,几乎每种框架都遇到过。这篇文章不讲教科书式的定义,而是把我实际排查 Flaky Test 的完整思路、工具链、常见根因和避坑经验全部摊开来讲,适合正在被偶发失败困扰的测试工程师、DevOps 同学,以及任何维护 CI 流水线的人参考。
1. 先搞清楚 Flaky Test 到底在折腾什么
1.1 偶发失败和稳定失败的本质区别
很多人一看到用例失败就本能地去改代码,这是最容易走弯路的地方。稳定失败(Deterministic Failure)意味着给定相同的输入和环境,用例每次都会失败,根因通常在业务逻辑、断言写错、接口变更这些确定性因素上。而 Flaky Test 的核心特征是非确定性——同样的代码、同样的环境,多次执行结果不一致。这个区别决定了排查方向完全不同:稳定失败靠调试(Debug),偶发失败靠统计和排除法。
我一般会先做一个简单的判定:把失败的用例单独拎出来,连续跑 10 次。如果 10 次全挂,那是稳定失败,走常规调试流程;如果 10 次里挂了 2 到 3 次,那就是典型的 Flaky,需要进入专门的排查通道。这个"10 次重跑法"看起来笨,但它能帮你快速分流,避免在错误的方向上浪费时间。
1.2 为什么 Flaky Test 比想象中更危险
偶发失败最大的危害不是它本身,而是它对团队信任的侵蚀。当一条用例三天两头飘红,大家的反应会从"赶紧看看是不是我改坏了"变成"哦,又是它,重跑一下就行"。这种心态一旦蔓延,真正的回归缺陷就会被淹没在"狼来了"的噪音里。我见过一个团队因为长期忽视 Flaky,导致一个真实的内存泄漏问题被误判为"老毛病"拖了两周才定位,线上出了事故。
从工程角度看,Flaky Test 还会拖慢交付节奏。CI 流水线因为偶发失败频繁中断,开发被迫手动重跑,平均每次浪费 5 到 15 分钟。如果一个团队每天有 20 次这样的重跑,一个月就是几十个小时的纯浪费。所以排查 Flaky 不是"锦上添花",而是保障自动化测试体系可信度的必修课。
1.3 排查前必须建立的三个认知
第一,Flaky 几乎不可能靠"看代码"直接看出来。它的根因往往藏在时序、并发、环境状态这些运行时因素里,静态阅读代码的命中率极低。第二,复现是排查的前提,但复现本身就需要技巧。单次重跑碰运气效率太低,必须用批量重跑加日志聚合的方式提高命中率。第三,不是所有 Flaky 都值得修。有些根因在第三方服务或基础设施层面,修复成本极高,这时候更务实的做法是隔离或标记,而不是死磕。这三个认知能帮你少走很多弯路。
2. 复现是第一步:把"偶发"变成"高频可观测"
2.1 用重跑次数换复现概率的实操方法
排查 Flaky 的第一道坎就是复现。单次执行命中率可能只有 5%,跑 20 次才出现一次,靠手动点击根本不现实。我的做法是写一个批量重跑脚本,把目标用例连续执行 N 次,同时收集每次的完整日志和截图。以 pytest 为例,可以用 pytest-repeat 插件:
--count=50 表示把这条用例跑 50 次。如果 50 次里出现了 3 次失败,你就拿到了 3 份失败现场,这比盲目猜测强太多。对于 Selenium 或 Playwright 这类 UI 测试,我还会加上失败自动截图和视频录制,确保每次失败都有"案发现场"。
提示:重跑次数不是越多越好。一般先跑 30 到 50 次,如果一次都没复现,说明触发条件比较特殊,需要换思路(比如并发执行、调整环境参数),而不是无脑加到 500 次。
2.2 并发执行放大问题:让隐藏的竞态浮出水面
很多 Flaky 在串行执行时几乎不出现,一旦并发就频繁爆发。这是因为并发会放大资源竞争、时序依赖和共享状态问题。所以复现阶段我强烈建议用并发模式跑一遍。pytest 可以用 pytest-xdist:
-n 8 表示 8 个进程并行执行。如果串行 50 次才挂 1 次,并发模式下可能 10 次就挂 3 次。原因很简单:并发让多个用例同时争抢数据库连接、临时文件、端口、缓存等资源,把原本隐蔽的竞态条件直接暴露出来。这一步能极大提升复现效率,是我排查 Flaky 的常规操作。
2.3 日志聚合:把散落的失败现场拼成完整证据链
复现出来只是开始,关键是能不能从日志里读出线索。单次失败的日志往往是碎片化的,你需要把多次失败的日志放在一起对比,找出共同点。我通常会把每次运行的日志按时间戳命名,然后用脚本提取关键字段(如请求耗时、线程 ID、数据库连接状态)做成表格对比。
举个实际例子:我曾经排查一个接口测试的偶发失败,单看一次日志完全正常,但把 5 次失败日志并排一看,发现每次失败前 200 毫秒左右都有一条"连接池等待"的警告。顺着这条线索查下去,果然是连接池配置过小,高并发下拿不到连接导致超时。如果只看单次日志,这个规律根本发现不了。日志聚合的价值就在于把"偶发"变成"有规律"。
3. 六大高频根因:Flaky Test 的案发现场
3.1 等待与同步问题:UI 自动化的头号杀手
UI 自动化里最常见的 Flaky 根因就是等待没写对。很多人用固定 sleep(3) 来等元素出现,这在本地可能没问题,但 CI 机器性能差一点,3 秒不够,用例就挂了。固定等待的本质是"赌",赌页面在固定时间内加载完,而网络和渲染时间是不确定的。
正确的做法是用显式等待(Explicit Wait),等的是"条件"而不是"时间"。以 Playwright 为例:
Selenium 里对应的是 WebDriverWait 配合 expected_conditions。核心思想是:只要条件满足就立即继续,最多等 N 秒。这样既不会因为等太久浪费时间,也不会因为等太短而失败。我踩过的坑是:有些元素虽然可见但还没绑定事件,这时候要等 element_to_be_clickable 而不是 visibility_of_element_located,两者差一个字,效果天差地别。
3.2 测试数据污染:用例之间的隐形依赖
第二个高频根因是测试数据被污染。典型场景是:用例 A 创建了一条订单,用例 B 假设数据库里没有这条订单,结果并发执行时 B 读到了 A 的数据,断言失败。或者用例 A 修改了某个全局配置,用例 B 依赖这个配置的初始值,执行顺序一变就挂。
这类问题的排查方法是隔离执行:把可疑用例单独跑,如果单独跑永远不挂,和其他用例一起跑就挂,那基本可以确定是数据污染。解决方案有三层:一是每个用例用独立的数据命名空间(比如加 UUID 前缀);二是用例执行前做数据清理(setup 阶段删掉可能冲突的数据);三是避免用例间共享可变状态。我个人的经验是,测试数据的设计比测试代码本身更重要,数据隔离做得好,一半的 Flaky 会自动消失。
3.3 时序与竞态条件:并发场景下的经典难题
竞态条件是 Flaky 里最难缠的一类。它的本质是多个操作对共享资源的访问顺序不确定,导致结果依赖执行时序。比如两个线程同时往一个列表里写数据,谁先谁后不确定,断言结果就不稳定。
排查竞态条件的关键是找到共享资源。常见的共享资源包括:数据库连接池、临时文件、全局变量、单例对象、缓存、端口号。找到之后,要么加锁保护,要么改成每个用例独立持有。我遇到过一个典型案例:多个用例共用一个临时目录,A 用例还没清理完,B 用例就开始写,导致文件冲突。解决办法是每个用例用 tempfile.mkdtemp() 生成独立目录,问题立刻消失。
3.4 环境与资源问题:被忽视的基础设施因素
很多时候 Flaky 的根因根本不在测试代码,而在环境。CI 机器的 CPU、内存、磁盘 IO 波动,都会影响用例执行。我见过最离谱的一次是:CI 机器磁盘快满了,写日志变慢,导致某个依赖日志落盘的用例偶发超时。查了半天代码,最后发现是磁盘问题。
常见的环境因素包括:内存不足导致进程被 OOM Killer 干掉、磁盘 IO 慢导致超时、网络抖动导致请求失败、端口被占用导致服务起不来。排查这类问题要看系统层面的监控数据,而不是只盯着测试日志。我一般会在 CI 上挂一个简单的资源监控脚本,记录每次执行时的 CPU、内存、磁盘使用率,失败时对照着看,往往能发现规律。
3.5 第三方依赖不稳定:你控制不了的那部分
如果用例依赖外部接口、第三方服务或公共测试环境,那 Flaky 的概率会大幅上升。外部服务的响应时间、可用性、返回数据都可能变化,你无法控制。这类问题的特征是:失败日志里通常有超时、连接拒绝、返回数据格式异常等明显的外部错误。
处理策略分两种:如果第三方依赖是必须真实调用的(比如支付回调),那就加重试机制和超时配置,并接受一定的不稳定;如果可以用 Mock 替代,那就果断 Mock 掉,把不确定性挡在测试边界之外。我的原则是:能 Mock 的绝不真实调用,必须真实调用的做好重试和降级。这样能把外部因素导致的 Flaky 降到最低。
3.6 断言过于严格:把正常波动当成失败
最后一类根因容易被忽略:断言写得太死。比如断言接口响应时间小于 100 毫秒,但网络抖动时偶尔到 120 毫秒,用例就挂了。或者断言列表顺序固定,但后端返回顺序不保证。这类"失败"其实不是 bug,而是断言不合理。
排查方法是审视断言逻辑:这个断言是否依赖了不确定的因素?响应时间、数据顺序、浮点数精度、时间戳,这些都是常见的"过度严格"重灾区。合理的做法是给响应时间留余量(比如小于 500 毫秒),对顺序不敏感的场景用集合比较而非列表比较,浮点数用近似相等而非精确相等。
| 根因类型 | 典型表现 | 排查切入点 | 修复方向 |
|---|---|---|---|
| 等待同步 | UI 元素找不到、点击无效 | 检查是否用固定 sleep | 改显式等待 |
| 数据污染 | 单独跑正常,一起跑失败 | 隔离执行对比 | 数据隔离与清理 |
| 竞态条件 | 并发时高频失败 | 找共享资源 | 加锁或独立持有 |
| 环境资源 | 无明显代码规律 | 看系统监控 | 扩容或优化资源 |
| 第三方依赖 | 日志有超时/连接错误 | 检查外部调用 | Mock 或加重试 |
| 断言过严 | 边界值偶发失败 | 审视断言逻辑 | 放宽合理范围 |
4. 工具链与排查手法:让证据说话
4.1 失败重试与自动分类:先止损再根治
在根治之前,先用重试机制止损是务实的做法。pytest 有 pytest-rerunfailures 插件,可以配置失败自动重跑:
--reruns 2 表示失败后重跑 2 次,只要有一次通过就算通过。这能显著降低 CI 的误报率。但要注意:重试是止痛药,不是解药。它会掩盖问题,所以必须配合失败记录,把每次重试的用例名和次数统计出来,定期分析哪些用例最"飘",优先根治。
我一般会用一个简单的脚本统计重试数据,生成"Flaky 排行榜",每周 review 一次。排名靠前的用例就是重点整治对象。这个机制能让 Flaky 治理变成持续性的工作,而不是出了问题才临时抱佛脚。
4.2 用 Allure 报告定位失败规律
Allure 是我常用的测试报告工具,它能把每次执行的历史记录、失败截图、日志、耗时都聚合在一起。排查 Flaky 时,我会重点看两个维度:一是失败的时间分布,如果失败集中在某个时间段,可能是环境问题;二是失败的耗时分布,如果失败用例的耗时明显高于成功用例,那大概率是超时或等待问题。
Allure 的 @allure.step 装饰器可以把用例拆成细粒度步骤,失败时能精确定位到哪一步。比如一个下单流程拆成"登录、加购物车、结算、支付"四步,失败时一看就知道卡在哪一步,排查效率翻倍。这个投入非常值得,尤其是用例逻辑复杂的时候。
4.3 日志分级与关键信息埋点
日志是排查 Flaky 的核心证据,但很多团队的日志要么太少(看不出问题),要么太多(淹没重点)。我的做法是分级:INFO 级别记录关键流程节点,DEBUG 级别记录详细数据,失败时自动把 DEBUG 日志也 dump 出来。同时在关键位置埋点,比如请求前后记录时间戳、数据库操作前后记录连接状态。
一个实用技巧是给每次执行加一个唯一的 run_id,所有日志都带上这个 ID。这样即使并发执行,也能把同一次运行的所有日志串起来,不会和其他运行混在一起。这个小小的改动,能让日志排查效率提升好几倍。
4.4 二分法与排除法:缩小问题范围
当根因不明确时,二分法和排除法是最高效的手段。具体做法是:先注释掉一半的用例,看 Flaky 是否还出现;如果消失,说明问题在被注释的那一半里,继续二分;如果还在,说明在另一半。这样用 log2(N) 次就能定位到具体用例。
排除法则是逐个排除变量:换一台机器跑、换一个数据库跑、串行改并发、去掉某个依赖。每排除一个变量,问题范围就缩小一圈。我排查过一个困扰团队两周的 Flaky,最后用排除法发现是某个测试环境的时钟不同步导致的,换环境后问题消失。这个过程虽然笨,但非常有效。
5. 从根上治理:让 Flaky 不再复发
5.1 建立 Flaky 用例的隔离与标记机制
不是所有 Flaky 都能立刻修好,对于那些根因复杂、短期无法解决的用例,隔离是必要的。pytest 可以用 @pytest.mark.flaky 标记,然后在 CI 配置里把这类用例单独跑,不阻塞主流程:
同时要建立台账,记录每个被标记用例的原因、负责人和计划修复时间。隔离不是"眼不见为净",而是"暂时搁置,持续跟踪"。我见过太多团队把 Flaky 用例一标记就忘了,半年后还在那里飘,这就失去了隔离的意义。
5.2 在 CI 中引入 Flaky 检测门禁
治本的关键是让 Flaky 在合并前就被发现。我推荐在 CI 里加一道"稳定性检测"门禁:对新增或修改的用例,自动重跑 5 到 10 次,如果有任何一次失败,就判定为不稳定,阻止合并。这样能把 Flaky 挡在代码库之外,而不是等它进入主干后再来救火。
实现方式可以是一个独立的 CI Job,用 pytest --count=10 跑变更相关的用例,失败则标记 PR。这个门禁会增加一些 CI 时间,但相比 Flaky 带来的长期损耗,这点投入完全值得。我们团队上线这个机制后,新增 Flaky 的数量下降了大概七成。
5.3 测试代码的健壮性设计原则
从源头减少 Flaky,靠的是测试代码本身的健壮性。我总结了几个原则:第一,永远不要用固定 sleep,用条件等待;第二,每个用例独立准备和清理数据,不依赖执行顺序;第三,避免共享可变状态,能用局部变量就不用全局变量;第四,断言要留合理余量,不追求绝对精确;第五,外部依赖尽量 Mock,把不确定性挡在外面。
这些原则看起来简单,但真正落实到每一条用例上需要纪律。我的做法是在 Code Review 时专门检查这几点,发现固定 sleep、共享状态、过严断言就打回去改。坚持一段时间后,团队的测试代码质量会有明显提升,Flaky 自然就少了。
5.4 定期复盘与 Flaky 治理的长期机制
Flaky 治理不是一次性任务,而是长期工程。我建议团队建立月度复盘机制:统计这个月的 Flaky 发生率、Top 问题用例、根因分布,然后制定下个月的治理目标。复盘时要区分"新增 Flaky"和"存量 Flaky",前者靠门禁拦截,后者靠排期修复。
复盘的数据来源就是前面提到的重试统计和 Allure 报告。把这些数据可视化,做成趋势图,能直观看到治理效果。当团队看到 Flaky 率从 8% 降到 2%,那种成就感是很实在的。更重要的是,这个过程会逐渐培养团队对测试稳定性的重视,形成良性循环。
6. 几个真实案例的排查全过程
6.1 案例一:连接池耗尽导致的接口偶发超时
这个案例我在前面提过,这里展开讲完整链路。现象是接口自动化用例偶发超时,失败率大概 5%。第一步,用 --count=50 重跑,复现了 3 次。第二步,把 3 次失败日志并排对比,发现失败前都有"等待连接"的警告。第三步,查看连接池配置,发现最大连接数是 10,而并发用例数是 20。第四步,确认根因:并发时连接不够用,部分请求排队超时。
修复方案是把连接池调大到 30,同时给获取连接设置合理的超时时间。修复后重跑 100 次,零失败。这个案例的教训是:并发测试前一定要检查资源池配置,连接池、线程池、文件句柄都是重灾区。
6.2 案例二:时区差异引发的日期断言失败
这个案例比较隐蔽。现象是某个涉及日期的用例在本地永远通过,在 CI 上偶发失败。排查时先怀疑是数据问题,查了半天没头绪。后来对比本地和 CI 的环境变量,发现 CI 机器的时区是 UTC,本地是东八区。用例里有个"今天"的断言,跨零点时两边算出来的日期不一样,导致失败。
修复方案是在测试代码里显式指定时区,不依赖系统默认值。这个坑提醒我:环境差异是 Flaky 的重要来源,时区、编码、换行符、路径分隔符这些细节都可能出问题。现在我写测试代码时,凡是涉及这些的都会显式指定,不留给环境去猜。
6.3 案例三:UI 动画未结束导致的点击失效
UI 自动化里很常见的一个坑:元素已经可见,但还在做动画(比如淡入、滑动),这时候点击可能点不中或者点到旧位置。现象是点击后断言失败,但截图看元素明明在那里。排查时录了视频,慢放才发现点击瞬间元素还在移动。
修复方案是等动画结束再操作。Playwright 可以用 page.wait_for_timeout 配合元素的 stable 状态,或者直接等某个动画结束的标志。Selenium 里可以等元素的 location 连续两次不变再点击。这个坑的教训是:"可见"不等于"可交互",UI 测试要等元素真正稳定下来。
6.4 案例四:随机数据碰撞导致的唯一约束冲突
这个案例是数据污染的一种。用例会生成随机用户名注册,理论上不会重复,但随机数种子相同或者随机范围太小时,偶尔会撞车,导致唯一约束冲突。现象是注册用例偶发失败,报"用户名已存在"。
排查时统计了失败用例的用户名,发现确实有重复。根因是随机数生成用了固定种子,导致每次运行生成的序列一样。修复方案是改用 UUID 或者加上时间戳,保证全局唯一。这个坑提醒我:测试数据要保证唯一性,别用可能碰撞的随机方案,UUID 是最省心的选择。
7. 一些踩坑之后的个人体会
排查 Flaky Test 这些年,我最大的体会是:耐心和证据比聪明更重要。很多人一上来就想靠"灵光一闪"找到根因,结果往往是猜错方向白忙一场。真正有效的方法是老老实实复现、收集证据、对比分析、逐步排除。这个过程不酷,但管用。
另一个体会是:大部分 Flaky 都是自己挖的坑。固定 sleep、共享状态、过严断言、不隔离数据,这些坏习惯在写测试代码时埋下隐患,运行时才爆发。所以与其等 Flaky 出现再排查,不如在写代码时就遵守健壮性原则。我现在写测试用例,会下意识地问自己:这条用例并发跑会不会挂?换个环境会不会挂?数据会不会冲突?提前想清楚,能省掉后面大量的排查时间。
最后分享一个实用小技巧:给团队的 Flaky 用例建一个共享文档,记录每个用例的现象、根因、修复方案。这个文档会逐渐变成团队的"避坑手册",新人遇到类似问题一查就知道怎么处理。我们团队的这份文档已经积累了上百条记录,成了最有价值的内部资产之一。Flaky 治理没有终点,但每修好一个,自动化测试的可信度就高一分,这份积累是值得的。