Python 测试偶发失败速查：非确定性六大根源与种子固化法

更新时间：2026-10-24。FAQ 速查页，面向「测试本地全绿、CI 上随机红，重跑一次又好了」的同学。Python 测试偶发失败（flaky test）是测试体系里最毒的一类故障：它不常出现，出现时重跑就消失，于是没人修，越攒越多，最后整个团队对 CI 红灯麻木——真回归被淹没在假报警里。偶发失败的本质只有一句话：测试的结果依赖了某个你没控制的变量。这个变量可能是进程级的 hash 随机化、字典/集合的遍历顺序、random 的种子、机器的当前时区与当前时间、上一个测试留下的全局状态、线程调度的时序、外部网络服务的抖动。本篇给六大根源的识别与固化口径，目标是把「有时候红」变成「要么永远红、要么永远绿」。

本文要回答的问题

• 为什么同一个测试，本地跑一百次全过，CI 上偶尔炸？
• 为什么测试单独跑过、放套件里一起跑就挂？
• PYTHONHASHSEED 是什么，它怎么让字典遍历顺序每轮都不一样？
• 用了 random 的测试怎么固化种子？
• 依赖「现在几点」的断言怎么写才不炸？

一、报错原文与典型现象

偶发失败的典型现场（工程路径以 /proj/demo 占位）：

$ python3 -m pytest /proj/demo/tests/ -q
............................
28 passed in 3.42s
$ python3 -m pytest /proj/demo/tests/ -q    # 同一命令再跑
......F.....................
FAILED tests/test_user.py::test_export - assert ['name', 'id'] == ['id', 'name']
# 断言一个列表的顺序，而这列表来自集合遍历——每轮顺序由 hash 种子决定

$ python3 -m pytest /proj/demo/tests/test_order.py -q
1 passed in 0.11s                          # 单独跑，过
$ python3 -m pytest /proj/demo/tests/ -q
FAILED tests/test_order.py::test_balance - assert 100 == 85
# 套件里跑就挂——前一个测试改了全局账户余额没还原

FAILED tests/test_report.py::test_month_label - assert '2026-09' == '2026-10'
# 跨零点/跨月跑的瞬间断言翻转——测试依赖了「现在」

认清机制一句话：偶发失败不是「测试不稳定」，是「测试偷偷依赖了一个会变的输入」。修法不是重跑，而是把那个输入找出来钉死。

二、病因处置速查表

报错现象 / 场景	可能原因	快速验证	处置
断言顺序有时对有时不对	遍历了 dict/set 当有序用	PYTHONHASHSEED=0 反复跑	断言前排序，或改用有序结构
用 random 的用例偶尔红	没固化随机种子	每轮打印种子复现	random.seed(固定值) 或注入种子
跨零点/跨月才炸	断言依赖当前时间	改系统时间重跑	注入时钟，freeze 时间
单独过、套件里挂	测试间共享了全局状态	调整执行顺序复现	fixture 隔离，setup/teardown 还原
加并发后才偶发	线程时序/竞态	加大并发压测复现	用同步原语，禁用 sleep 等待
CI 上偶发、本地从不	外部服务/网络抖动	mock 后必绿	单测禁真网络，契约测试分层

三、排查决策图

这张图是偶发失败的标准动线：红是诡异现象与定罪根因，蓝是排查动作，绿是验证通过，橙是修复动作，紫是防复发沉淀。

读这张图抓住主线：偶发失败排查的第一步不是修，是制造确定性复现——固定 hash 种子连跑 50 轮，要么稳定红（变成普通 bug，好修）、要么稳定绿（说明变量在别处，继续二分）。复现不了的 flaky 不要猜着修，猜修的结局是「看起来好了，两周后又红」。

四、逐条排查展开

第一根源：字典/集合遍历顺序当有序用。 Python 3.7+ 字典保插入序，但集合 set 不保序，且字符串 hash 受 PYTHONHASHSEED 随机化影响——每个进程的种子不同，{"id", "name"} 的遍历序这轮是 id, name，下轮可能反过来。断言里写 assert list(my_set) == [...] 就是埋雷。复现与处置：

$ for i in 1 2 3 4 5; do PYTHONHASHSEED=$i python3 -m pytest tests/test_user.py -q; done
# 换种子跑，稳定复现 = 顺序依赖实锤

处置：断言前排序（assert sorted(result) == sorted(expected)），或改用保序结构；任何把 set/frozenset 转列表后断言顺序的代码一律视为 bug。

第二根源：随机数没固化种子。 测试里直接用 random.random()、random.choice()、numpy 的 np.random，断言期望一个「大概率成立」的结果，小概率就红。处置两级：测试内 random.seed(42) 固化；更好的做法是把随机源当依赖注入——函数接收一个 rng 参数，测试传固定种子的实例。numpy 同理用 np.random.default_rng(42)，不要用全局 np.random.seed。

第三根源：时区与当前时间。 断言里出现 datetime.now()、date.today()、time.time() 就是定时炸弹：跨零点、跨月、跨夏令时边界跑的瞬间断言翻转；CI 容器时区是 UTC、开发机是东八区，同一断言两地结果不同。处置：生产代码不直接调 now，而是注入时钟（传 now 参数或 clock 对象）；测试用 freezegun 冻结时间：

$ pip install freezegun
# @freeze_time("2026-10-24 12:00:00") 装饰测试，时间被钉死

第四根源：测试间共享状态。 最经典：某个测试改了全局单例、环境变量、数据库行、临时目录，没还原；它之后跑的测试读到脏数据。特征就是「单独跑过、套件里挂」。复现：用 pytest -x --lf（last-failed）或手动调执行顺序定位「谁污染了谁」。处置：每个测试用 fixture 做 setup/teardown 还原；环境变量改动用 pytest 的 monkeypatch.setenv（自动还原）；数据库用事务回滚或每用例建临时库。

第五根源：并发时序。 多线程/异步代码里用 time.sleep(0.1) 等另一个线程「应该跑完了」——机器快时过得去，CI 负载高时睡不够就红。处置：测试里禁用 sleep 等待，改用同步原语（threading.Event、队列 join、future 的 result 超时）；竞态类 bug 用压力复现（并发数拉大、循环百轮）再修，修完保留压力用例防回归。

第六根源：外部依赖抖动。 单元测试里真发 HTTP 请求、真连数据库、真读远端配置——对端一抖就红。处置是分层纪律：单元测试一律 mock 外部调用（responses、requests-mock 或依赖注入）；需要真后端的用例单独标记 @pytest.mark.integration，跑在独立任务里，挂了不阻塞主线 CI。判断标准一句话：单测失败应该只意味着「我的代码错了」，不能意味着「网坏了」。

五、规范做法与预防

• CI 主动打乱顺序与种子：装 pytest-randomly（每轮随机换种子并打乱用例顺序），让顺序依赖在 CI 上主动暴露，而不是攒到发布夜。
• flaky 用例登记限期修：发现即登记、定负责人与期限；@pytest.mark.flaky 只允许作为「修复中」的临时标记，禁止当永久豁免。
• 时间与随机源注入化：code review 红线——业务代码里直接调 datetime.now()/random.random() 一律打回，改注入。
• 断言顺序前排序：凡对集合、keys()、os.listdir() 这类不保序来源的断言，先 sorted。
• 重复跑当准入门禁：新用例合入前本地 -m pytest --count 连跑 20 轮（或 shell 循环），全绿才准合。

这一篇在知识体系里的位置

本篇是 Python 排错速查簇的测试稳定性篇，与「改了不生效」「装错环境」同属行为对不上代码一族：缓存陈旧看 pycache 与 pip 缓存陈旧速查；同名遮蔽看 Python 模块重名遮蔽标准库速查；配置读错看 Python 配置文件解析失败速查；超时类问题看 Python 超时与卡死速查；段错误看 Python 段错误速查。「找出未控变量并钉死」这条心法对 JS/Go/Java 的 flaky test 同样成立。

一句话总结

偶发失败的本质是测试偷偷依赖了未受控变量——遍历顺序、随机种子、当前时间、共享状态、并发时序、外部服务六选其一；排查第一步是固定 PYTHONHASHSEED 连跑制造确定性复现，复现后六因处置——顺序断言先排序、随机源注入并固化种子、时钟注入加 freezegun 冻结、fixture 隔离与 monkeypatch 还原状态、并发禁用 sleep 改用同步原语、单测 mock 外部依赖；防复发主线是 CI 上 pytest-randomly 主动打乱、flaky 登记限期修、新用例连跑 20 轮全绿才准入，目标永远是一句话：要么永远红，要么永远绿。