首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >CI 又红了,重跑一次就绿:把 flaky 用例做成一份可复核的隔离清单

CI 又红了,重跑一次就绿:把 flaky 用例做成一份可复核的隔离清单

原创
作者头像
老王说技术
发布于 2026-11-21 11:38:35
发布于 2026-11-21 11:38:35
150
举报

几乎每个跑 CI 的团队都遇到过这种红灯:同一个提交、同一份代码,第一次跑挂了一个用例,点一下「重新运行」就全绿。大家默认「偶发,忽略」,然后这个用例会在后面几周里反复红、反复被重跑,直到某天真的线上缺陷藏在同一片红灯里没人再看。

问题不在于「要不要重跑」,而在于没有任何一份数据能说清楚:到底哪些用例不稳定、不稳定到什么程度、是谁在什么时候把它们隔离掉的。本文不引入新平台、不装新依赖,只做一件事:用 pytest --junitxml 产出的 XML 和 Python 标准库,把重复运行的结果算成一张每行都能追回到原始记录的 flaky 清单,并附上让脏数据混不进报表的自检脚本。文中的用例名、次数、分数都是演示用占位值,用来说明字段结构与计算过程,不代表任何真实项目的测量结果,请替换成自己仓库的 JUnit 文件。

一、先把口径写死,再谈计算

「flaky」这个词很容易被用成「看不顺眼的失败」。要让它可度量,必须先固定三个判断,否则换个人算就是另一份清单:

概念

定义

取值来源

用例标识 test_id

classname + name 拼成的唯一键,跨运行保持不变

JUnit XML <testcase> 属性

一次观测

某次运行里该用例的结局,只取 pass / fail

<failure> / <error> 子元素是否存在

有效运行

必须发生在同一个 commit、同一套环境配置下

采集脚本写入的 run_meta

flaky

有效运行中既出现过 pass 又出现过 fail

计算列

稳定失败 always_fail

全部运行都 fail

计算列,不是 flaky

不稳定度 flip_rate

相邻两次观测结果发生翻转的次数 ÷ (运行次数 - 1)

计算列

三个必须提前写进 README 的判断:

  • 把 always_fail 排除在 flaky 之外。全红的用例是真实缺陷或环境没起来,重跑不会变绿;把它算成 flaky 会掩盖真问题。
  • 用 commit 而不是时间窗圈定有效运行。跨了提交的失败可能是代码改动引入的,混进来会把「改坏了」误判成「不稳定」。
  • skip / xfail 不参与计算。跳过不是通过,也没有观测价值;单独列进 ignored 计数,别悄悄丢掉。

一句话:flaky 描述的是同一份代码在同一环境下的结果不一致,不是「失败率」。失败率高但每次都失败的用例,该修的是代码。

二、四类脏数据,必须在进报表前挡住

重复运行最怕的不是算错,是采集本身不干净。下面四类我在脚本里全部显式处理,任何一类出现都进 anomalies,宁可少报也不误报:

脏数据类型

典型表现

不处理会怎样

处理方式

用例名含参数

test_x[param=1] 与 test_x[param=2] 被当成同一个

把两个不同用例的成败串在一起,凭空造出 flaky

classname + 完整 name 一起做键,不截断 [ 之后的内容

运行中断

某次 XML 只有一半用例(超时/OOM 被杀)

缺失被当成「没跑=没失败」,翻转率算低

每次运行要求用例集合一致,缺任何一个就整次标记 incomplete 并剔除

环境漂移

多次运行来自不同容器镜像或不同 commit

环境差异被算成用例不稳定

采集时写 run_meta.json,比对 commit / image 全一致才纳入

重试污染

CI 自带 retry 把失败那次覆盖成通过

只能看到绿,flaky 完全隐形

采集阶段关闭重试(--reruns 0),一次运行一个 XML

第四类最隐蔽:如果你的 CI 配了自动重试, JUnit 里往往只剩最终结果,再怎么算都看不到不稳定。所以第一步是关掉重试单独采集,而不是先在现有报表上做统计。

三、可复现步骤

3.1 采集:同一提交重复跑 N 次,每次一个独立 XML

代码语言:bash
复制
#!/usr/bin/env bash
# 在同一份代码、同一环境下重复运行,每次输出独立的 JUnit XML
set -euo pipefail
N=10
OUT=./flaky_runs
mkdir -p "$OUT"
COMMIT="$(git rev-parse HEAD)"
IMAGE="${CI_IMAGE:-local}"
printf '{"commit":"%s","image":"%s"}\n' "$COMMIT" "$IMAGE" > "$OUT/run_meta.json"

for i in $(seq 1 "$N"); do
  # 关键:关闭重试,让失败如实留在这次运行的 XML 里
  pytest -q --reruns 0 --junitxml="$OUT/run_${i}.xml" tests/ || true
done
ls -1 "$OUT"/run_*.xml | wc -l

|| true 是故意的:失败的运行本身就是要采集的样本,不能让 set -e 提前中断循环。演示用的 N=10 只是让下面的计算有足够样本,实际取值见第六节。

3.2 归一:把每次运行压成一行一个用例

不需要数据库,先把 XML 读成一张扁平表。下面是中间产物的结构示意(演示值),只依赖 xml.etree.ElementTree:

代码语言:json
复制
{"run": "run_1.xml", "commit": "DEMO_SHA_1", "test_id": "tests.test_billing::test_rounding[param=1]", "status": "pass"}
{"run": "run_2.xml", "commit": "DEMO_SHA_1", "test_id": "tests.test_billing::test_rounding[param=1]", "status": "fail"}

字段固定的好处是:后面任何争议都能追回到「第几次运行的哪个 XML 节点」,而不是对着一个聚合分数互相猜。

3.3 计算:只用标准库,输出 flaky 清单与异常清单

代码语言:python
复制
#!/usr/bin/env python3
"""从多次 JUnit XML 统计不稳定用例。仅用 Python 标准库。
口径:同一 commit 下,既出现过 pass 又出现过 fail 才算 flaky;
      全 fail 记为 always_fail;缺用例的运行整次剔除。"""
import glob
import json
import csv
import xml.etree.ElementTree as ET
from collections import defaultdict

FAIL_TAGS = {"failure", "error"}
SKIP_TAGS = {"skipped"}


def load_meta(path):
    with open(path, encoding="utf-8") as fh:
        return json.load(fh)


def parse_run(path):
    """返回 (test_id -> status),并报告解析是否完整。"""
    root = ET.parse(path).getroot()
    results = {}
    for case in root.iter("testcase"):
        cls = case.get("classname", "")
        name = case.get("name", "")
        if not name:
            continue
        test_id = f"{cls}::{name}"          # 不截断参数化后缀
        tags = {child.tag.split("}")[-1] for child in case}
        if tags & SKIP_TAGS:
            status = "skip"
        elif tags & FAIL_TAGS:
            status = "fail"
        else:
            status = "pass"
        results[test_id] = status
    return results


def flip_rate(seq):
    """相邻观测翻转次数 / (观测数 - 1)。"""
    if len(seq) < 2:
        return 0.0
    flips = sum(1 for a, b in zip(seq, seq[1:]) if a != b)
    return round(flips / (len(seq) - 1), 3)


def main():
    meta = load_meta("flaky_runs/run_meta.json")
    files = sorted(glob.glob("flaky_runs/run_*.xml"))
    runs = [(f, parse_run(f)) for f in files]

    # 以第一次运行为基准,用例集合不一致的运行整次剔除,并记入异常
    baseline = set(runs[0][1]) if runs else set()
    valid, anomalies = [], []
    for f, r in runs:
        if set(r) != baseline:
            anomalies.append({"run": f, "reason": "incomplete",
                              "missing": len(baseline - set(r)),
                              "extra": len(set(r) - baseline)})
            continue
        valid.append((f, r))
    if len(valid) < 2:
        raise SystemExit("有效运行不足 2 次,拒绝出报表:" + json.dumps(anomalies))

    seqs = defaultdict(list)
    for _, r in valid:
        for tid, status in r.items():
            if status != "skip":
                seqs[tid].append(status)

    rows, ignored = [], 0
    for tid, seq in sorted(seqs.items()):
        if len(seq) != len(valid):
            anomalies.append({"test_id": tid, "reason": "missing_observation"})
            continue
        fails, passes = seq.count("fail"), seq.count("pass")
        if fails and passes:
            verdict = "flaky"
        elif fails:
            verdict = "always_fail"
        else:
            verdict = "stable"
        rows.append({
            "test_id": tid, "commit": meta["commit"],
            "runs": len(seq), "pass": passes, "fail": fails,
            "flip_rate": flip_rate(seq), "verdict": verdict,
        })

    with open("flaky_report.csv", "w", newline="", encoding="utf-8") as fh:
        w = csv.DictWriter(fh, fieldnames=list(rows[0]) if rows else
                           ["test_id", "commit", "runs", "pass", "fail", "flip_rate", "verdict"])
        w.writeheader()
        w.writerows(rows)
    with open("flaky_anomalies.json", "w", encoding="utf-8") as fh:
        json.dump(anomalies, fh, ensure_ascii=False, indent=2)

    print(f"有效运行 {len(valid)} 次 / 共 {len(runs)} 次")
    print(f"flaky={sum(r['verdict']=='flaky' for r in rows)} "
          f"always_fail={sum(r['verdict']=='always_fail' for r in rows)} "
          f"stable={sum(r['verdict']=='stable' for r in rows)}")
    print(f"异常 {len(anomalies)} 条,详见 flaky_anomalies.json")


if __name__ == "__main__":
    main()

脚本有两个刻意的设计:异常非空时仍然出报表但不隐藏异常,以及有效运行不足 2 次直接 SystemExit 拒绝出数——宁可没有报表,也不要一份看起来干净却不可信的清单。

3.4 运行

代码语言:bash
复制
python3 flaky_scan.py
column -s, -t < flaky_report.csv | head -20

产出的 flaky_report.csv 每行带 commit、pass / fail 次数、flip_rate 和 verdict,可以直接贴进 issue 或作为隔离清单的输入;flaky_anomalies.json 单独留存,用来回答「为什么这次只有 8 次有效运行」。

四、自检:让脏数据挡在报表之外

检查

落点

不通过时的动作

所有运行 commit / image 一致

采集 run_meta.json

拒绝出报表,重新采集

每次运行的 testcase 集合完全一致

parse_run 后比对 baseline

整次标记 incomplete 并剔除

用例名保留参数化后缀

classname::name 不截断

复核 test_id 是否唯一

skip / xfail 单独计数

ignored 分支

不进入 seqs,不算通过

always_fail 与 flaky 分开

verdict 三分支

全红用例转缺陷单,不进隔离清单

有效运行数 ≥ 2

main 前置判断

SystemExit,不产出 CSV

异常清单必须为空才纳入周报

flaky_anomalies.json

先修采集,再谈结论

其中「用例集合完全一致」这一条容易被嫌麻烦,但它挡掉的是最常见的一类假 flaky:某次运行跑到一半被 OOM 杀掉,后半段用例全部缺失,若按「没出现=没失败」处理,就会把一串用例算成忽好忽坏。

五、结果怎么读,别急着下结论

现象

可能的解释

别急下的结论

flip_rate 高、fail 少

共享状态 / 时间依赖 / 并发竞态

「偶发,忽略」——高翻转恰恰说明有真实不确定性

flip_rate 低、fail 约一半

可能依赖外部服务或随机种子

「不稳定度低所以安全」——看绝对失败次数,不是看翻转率

always_fail 集中在一两个文件

fixture 没起来 / 环境配置错

当成 flaky 隔离掉

全部 stable

样本太少或重试没关干净

「没有 flaky」——先核对采集阶段是否真的 --reruns 0

跨团队清单差异大

用例粒度、并发度、数据量不同

横向排名,数字不可比

尤其注意第一条:flip_rate 只是「结果跳动的频率」,不是危害程度。一个每 10 次挂 1 次、但一挂就阻塞发布的用例,比每 10 次挂 5 次却无关紧要的用例更该先处理。清单要按「影响 × 失败次数」排优先级,不要只按分数排序。

六、隔离不是终点:给清单加过期时间

识别出来之后,最常见的坏结局是「隔离清单只增不减」,半年后没人敢删。我用一份带 expires_at 与 owner 的清单约束它:

代码语言:yaml
复制
# quarantine.yaml —— 演示用占位值,请替换成真实用例与负责人
version: 1
commit: DEMO_SHA_1
policy:
  max_quarantine_days: 14
  require_repro_command: true
  quarantine_never_blocks_release: true
entries:
  - test_id: tests.test_billing::test_rounding[param=1]
    owner: DEMO_OWNER
    reason: "依赖共享时间源,疑似用例内未固定时钟"
    repro: "pytest tests/test_billing.py -k rounding --count 20"
    first_seen: "2026-11-21"
    expires_at: "2026-12-05"

三条约束对应三个真实问题:expires_at 防止永久隔离,repro 保证隔离时留下可复现命令而不是一句「偶发」,quarantine_never_blocks_release 明确隔离用例不阻塞发布但必须在到期前回到主集合或被删除。到期未处理的条目,让 CI 定时任务直接失败——用流程逼出一次决策,而不是让它静静躺着。

七、落地节奏与常见误区

阶段

只做这一件事

能立刻挡住的问题

第 1 周

关重试采集 10 次,跑通脚本,让异常清单为空

采集不干净、用例名被截断

第 2 周

固定 commit 与镜像,把脚本接进每日定时任务

环境漂移被算成 flaky

第 3 周

按「影响 × 失败次数」排优先级,逐条要么修要么带过期隔离

只按分数排序、清单只增不减

误区

为什么错

开着 CI retry 直接统计现有报表

失败那次已被覆盖,flaky 完全隐形

把全红用例算进 flaky

真实缺陷被「隔离」掉

用时间窗而不是 commit 圈定样本

跨提交的改动被误判成不稳定

直接删掉异常运行

问题被藏起来,下周换个形式再出现

隔离清单不设过期

半年后没人敢删,测试集合名存实亡

跨团队比 flaky 数量排名

用例粒度、并发度、数据量都不同,数字不可比

八、两条边界

第一,这套方法只判「结果是否一致」,不判「用例是否正确」。一个稳定通过的用例也可能断言写错,那属于测试质量问题,不在本文口径内。第二,计算结果的可信度取决于采集的可信度:如果 run_meta.json 里的 commit 是人工填的、或者采集时重试没关,再严谨的脚本也只产出一份精致的假数据。所以落地顺序永远是「先修采集,再谈统计」。

九、上线前自测清单

  • 故意写一条不带时区的时间串,确认脚本能报出解析异常;
  • 造一个 run_1.xml 缺两个 testcase,确认该次被标记 incomplete 且有效运行数减一;
  • 加一个全红的用例,确认它进 always_fail 而不是 flaky;
  • 加一个带 [param=...] 的参数化用例,确认 test_id 没有被合并;
  • 把 run_meta.json 的 commit 改掉,确认拒绝出报表;
  • 确认 flaky_anomalies.json 为空,才把 flaky_report.csv 贴进周报;
  • 用 git rev-list 手工核对一次 commit 与 CI 记录一致。

结语

「重跑一次就绿」不是可以忽略的噪音,而是一条没有被记录下来的观测。把它落成 commit 可追、flip_rate 可算、异常可见的一张表,团队才能从「凭感觉说偶发」变成「拿数据决定修还是隔离」。这套做法不买平台、不加埋点,代价只是每次多跑几遍用例;真正的成本在于愿不愿意把口径先写死,并且让脏数据在进报表之前就被挡住。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、先把口径写死,再谈计算
  • 二、四类脏数据,必须在进报表前挡住
  • 三、可复现步骤
    • 3.1 采集:同一提交重复跑 N 次,每次一个独立 XML
    • 3.2 归一:把每次运行压成一行一个用例
    • 3.3 计算:只用标准库,输出 flaky 清单与异常清单
    • 3.4 运行
  • 四、自检:让脏数据挡在报表之外
  • 五、结果怎么读,别急着下结论
  • 六、隔离不是终点:给清单加过期时间
  • 七、落地节奏与常见误区
  • 八、两条边界
  • 九、上线前自测清单
  • 结语
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档