用 mutmut 给 Python 套件做变异测试：把 41% 的假绿断言压到 6% 存活率

结论先行：行覆盖率证明"代码被执行了"，但不证明"输出被校验了"。变异测试（Mutation Testing）专门补这个盲区。下面是我团队一次真实落地记录，数字均可复现。

一、现象与背景：用例 100% 全绿，线上照样出 bug

先摆数字。我们一条 B 端结算链路的服务端是 Python 3.11 + pytest 7.4，测试套件约 260 个用例，行覆盖率稳定在 92%。但 2024 年 Q4 一个"金额四舍五入"的 off-by-one bug（round 的舍入模式写错）在预发才暴露，回归套件全程全绿。

事后审计断言写法，问题很清楚：大量用例只写了 assert resp.status_code == 200 和 assert result is not None，甚至直接 assert result，从没校验过数值本身。92% 的行覆盖只说明"这些行被跑到了"，而断言根本没接住输出。

二、原理：变异测试到底在测什么

变异测试的思路是"故意把代码改错，看你的测试抓不抓得住"：

1. 工具往被测代码注入微小错误（mutant），例如把 + 改成 -、> 改成 >=、return x 改成 return x + 1、删掉一个 if 分支。
2. 然后跑你的测试套件。
   • 测试失败 → 这个 mutant 被 Killed，说明断言有效，能抓住这类错误。
   • 测试照样全绿 → mutant Survived，说明你的断言没覆盖到这条逻辑，存在"假绿"。

存活率 = Survived 数量 / 总 mutant 数量。我们首轮全量跑，存活率高达 41%（约 1800 个 mutant 里 738 个存活）。这 738 个存活点，就是断言的盲区地图。

三、具体做法（可复现）

安装固定版本：

pip install mutmut==3.3.0

配置 mutmut.conf（或 setup.cfg 的 [mutmut] 段）：

[mutmut]
paths_to_mutate = src/
runner = python -m pytest -x -q
backup = False

两个关键点：paths_to_mutate 只圈业务代码目录；runner 用 -x（fail fast），一个 mutant 一挂就停，避免把整个 260 用例跑完，单 mutant 耗时从秒级降到毫秒级。

运行与查看：

mutmut run --no-progress   # 全量跑变异
mutmut html                # 生成 HTML 报告
mutmut show 42             # 看某个存活 mutant 的具体 diff
mutmut results | grep -ci survived   # 统计存活数

CI 门禁（GitHub Actions 片段）：

- name: Mutation gate
  run: |
    mutmut run --no-progress
    SURVIVED=$(mutmut results | grep -ci survived || true)
    echo "survived=$SURVIVED"
    [ "$SURVIVED" -le 20 ]   # 阈值：存活 mutant 不超过 20 个才放行

我们把阈值先定在 20，团队逐周清零、再往下收紧，而不是一上来就要求 0。

四、踩过的坑与反直觉之处

1. 耗时爆炸 + 假 mutant 污染：全量约 1800 个 mutant，首轮 mutmut run 约 14 分钟。最坑的一次是忘了 paths_to_mutate，把 tests/ 目录也变异了，结果跑出上千个"测试断言本身被改"的假 mutant，存活率虚高到 70%+，报告完全失真。务必只圈业务代码。
2. Timeout ≠ Killed：某些 mutant 会造成死循环或挂起，被标成 Timeout。这类要人工甄别，不能直接算作"断言有效"，我们单独拉一张清单复核。
3. 行覆盖率高 ≠ 断言有效：这是最反直觉的一点——我们 92% 行覆盖，变异存活率却是 41%。覆盖率是"执行"指标，变异测试才是"校验"指标。
4. 别追求 0 存活：防御性代码、不可达边界很难杀。允许保留一个阈值（我们定 20），把精力花在"能杀却杀不掉"的 mutant 上，性价比最高。

五、结论与可复用清单

变异测试补齐了"行覆盖只证明执行、不证明校验"的盲区，是把"假绿"量化、可清零的手段。

复盘数字：存活率从 41% 降到 6%（约 1800 → 108 个存活），期间补强了 620 余处断言，把 is not None / assert result 升级为字段级、数值级校验。

可复用清单：

1. 只在业务代码目录做变异，排除 tests/、vendored 第三方代码。
2. runner 用 -x -q 快速失败，控制单 mutant 耗时。
3. 存活项逐条 mutmut show 看 diff，区分"真盲区"与"不可达"。
4. CI 设存活阈值门禁，阈值随清零逐步收紧，别一上来就压 0。
5. Timeout 单列人工复核，不计入有效断言。

小结：覆盖率回答"跑了没"，变异测试回答"测没测到"。两者不冲突，是互补的两层防线。