AI补丁跳过测试的正确姿势：用冻结记录拦住隐藏回归

AI 代理生成的代码补丁越来越常见，但它们带来一个老问题的新变体：当某个测试失败时，是真的有缺陷，还是只是一个偶发的"flaky"抖动？模型作者倾向于直接跳过（quarantine）这个红色测试让 CI 变绿——而这恰恰可能把一个真实的回归悄悄藏起来。

本文介绍的"冻结记录"（freeze record）机制，核心思想只有一句话：跳过一个测试必须附带可被独立复核的证据，且这套检查默认失败（fail closed）。只要缺字段、两次运行结果一致、或者判定依据被同一个补丁改动过，跳过请求就会被拒绝。

冻结记录机制示意

需要说明的是：原文明确指出其中的命令、检查器脚本和示例属性文件均未实际执行，文中的哈希值都是占位符，并非真实测量结果。本文据此转述，不作为运行报告。

冻结记录必须存储什么

一条合格的冻结记录有六个强制字段，缺一不可。附带的 notes 可以存在，但永远不能用来填补空缺。

字段	存储内容	拒绝跳过的条件
test_id	单个 pytest 节点 id	收集到零个或多个测试
fixture_path	快照 fixture 文件路径	磁盘上路径不存在
fixture_sha256	该文件精确字节的 SHA-256	两次运行间摘要发生变化
disagreement	两个 passed 标志相反的运行对象	两次都通过或都失败
oracle_path	属性（property）文件路径	该路径在 HEAD^ 处缺失
oracle_blob	该文件在 HEAD^ 的 git blob id	blob 不同，或路径出现在补丁中

按提交次数计算的过期策略可以放在这些字段旁边，但它本身并不构成授权跳过的理由。审查者仍然需要看到"分歧"和父提交 blob。

记录对象应存放在 .freeze/record.json，让 CI 和审查者打开的是同一个文件。不要把这些字段埋进 Pull Request 评论里——评论不是检查器的输入。

SHA-256 是一种密码学哈希函数，对任意长度的输入生成固定的 256 位摘要。其核心属性是"抗碰撞性"：在计算上无法找到两个不同输入产生相同摘要的情况。冻结记录用它来"钉死"fixture 文件的精确字节状态——只要文件有一个字节发生变化，摘要就会完全不同。git blob id 本质上也是 SHA-1/SHA-256 哈希，git 用它唯一标识仓库中存储的每一个文件版本。git rev-parse 'HEAD^:path/to/file' 返回的就是父提交中该路径对应的 blob id，它与文件内容一一对应。这两个哈希机制共同构成了"篡改即可见"的基础：无论是 fixture 字节还是 oracle 属性文件，任何修改都会导致摘要失配，从而触发检查器拒绝。

为什么"两次结果一致"是错误的证据

这是整套机制中最反直觉、也最关键的一点。很多人会想：既然测试偶尔失败，那就重跑几次，看到绿了就跳过。但原文明确反对这种做法。

两次通过只能证明测试在这个快照上"能够"通过，并不能证明之前那次失败是非确定性的。两次失败则说明这是一个稳定的破坏——那是产品缺陷或 fixture 坏了，根本不是冻结候选。

只有"分歧"（disagreement）才是最小的有效观察：在 fixture 字节完全没变的前提下，结果却发生了变化。这是一个很弱的信号——一个三十次里才失败一次的 bug，往往会连续产生两个相同结果，于是永远不会满足条件。

这种偏向是刻意设计的。门禁宁可让一个罕见的 flaky 测试继续红着，也不愿意在一次"幸运重跑"后把一个稳定的 bug 隔离掉。换句话说，冻结记录应被当作一次简短的、有证人的例外，而不是一个概率估计。

还有一个硬约束：快照必须是测试"只读"的文件。如果测试会重写 fixture，第二次哈希就会不同，记录随即失效。调用网络、时钟或共享服务的测试完全不在适用范围内——因为文件哈希无法解释它们为何产生分歧。

Flaky 测试指在代码未发生变化的情况下，测试结果呈现非确定性——时而通过、时而失败。常见来源包括：依赖系统时钟或随机数种子、测试间共享可变状态、异步竞态条件、网络超时，以及测试执行顺序敏感性。Flaky 测试是 CI 系统中一个长期存在的工程治理难题：误报会消耗工程师排查时间，而将其简单隔离则可能掩盖真实回归。冻结记录机制的设计思路是：不去估计一个测试"有多 flaky"，而是要求提供一个最小但可核查的证据——在受控的 fixture 快照下，确实观察到了结果翻转。这有意将门槛设得很高，使得低频 flaky 测试（如千分之一失败率）几乎无法满足条件，从而避免将稳定的 bug 误判为 flaky 而隐藏起来。

五步编号流程

整套操作被拆成严格有序的五步，遇到第一个拒绝就停止，在第 5 步打印"接受"之前不得添加任何跳过标记。

在任何测试进程启动前，把 fixture 复制进 .freeze/ 并记录其 SHA-256。
在测试进程之外，对单个 test id 运行两次，分别保存退出状态。
解析属性文件在 HEAD^ 的 blob，并确认该路径不在本次提交 diff 中。
用父提交的属性文件对复制后的 fixture 跑一遍，属性失败则阻止冻结。
写入 record.json 并运行检查器，只有退出码 0 才能保留跳过标记。

固定字节与捕获两次运行

第一步先"钉死"字节：先对原文件做 sha256sum，再 cp 一份副本，并在启动 pytest 前对副本再哈希一次做比对。两个摘要若不同，立即停止——不能用一个无法复现的快照继续。

第二步在进程外跑两次同一个节点 id，绝不在测试内部重试。原文特别强调：进程内重试会"藏起"这条记录本就要捕获的分歧。退出码 0 映射为通过，其余（过滤掉状态 5 之后）映射为失败。状态 5 意味着没有收集到测试，应被视为选择错误，而非失败断言，更不是 flaky。

钉住父提交上的 oracle

第三步是整套机制的"防作弊"核心：属性文件必须已经存在于父提交上，代理补丁不得编辑它。

git rev-parse 'HEAD^:tests/properties/test_order_props.py' | tee .freeze/oracle.blob
git diff --name-only HEAD^ HEAD -- tests/properties/test_order_props.py

这个拆分阻止了一种典型的"模型自证"：用同一个改动既修改生产代码、又重写判定它的"证人"。diff 列表必须为空；非空就拒绝冻结，哪怕属性运行结果是绿的。补丁新增的属性文件同样不合格，因为对 HEAD^ 做 git rev-parse 会失败——让这个失败如实暴露，不要捕获后继续。

原文还提醒：交互式 rebase 期间 HEAD^ 可能指向错误的父提交，blob 钉定会认证错文件，务必在 HEAD 已指向补丁提交后再运行检查器。

基于属性的测试（Property-Based Testing） 是一种测试范式，区别于传统的"给定具体输入、断言具体输出"的示例测试。它要求开发者描述函数应满足的不变量（invariant）——即对一类输入普遍成立的关系，例如"排序后的列表长度等于原列表长度"或"序列化后再反序列化等于原始值"。测试框架（如 Python 的 Hypothesis）会自动生成大量随机输入来试图证伪这些不变量。在冻结记录机制中，oracle 属性文件扮演的正是"独立证人"角色：它描述的是一个与具体补丁无关的结构性约束，因此必须在补丁之前就存在。如果补丁改写了 oracle，相当于被告人同时充当了法庭上的证人——这正是 blob 钉定要阻止的情形。

父 oracle 的起草：模型只是辅助

编写不变量（invariant）才是整个流程中最慢的一步。有人必须陈述一个 fixture 能够支撑的关系，然后把这个文件落到一个代理补丁不会触碰的提交里。

原文披露本文系 MonkeyCode 产品外联的一部分，其免费模型访问在这里的定位仅限于"起草父文件的辅助工具"：根据函数签名和 fixture schema 请求一个候选属性，然后在提交前逐条审查每个 assert。

关键在于使用边界：模型草稿应附在审查线程里，oracle 要单独成一个提交，以便审查者把草稿与父 blob 做 diff。后续的措辞修改也必须有自己的提交——一旦落进代理补丁，blob 钉定就会断裂，检查器拒绝冻结。而这个拒绝正是正确结果。模型服务不被当作 fixture 字节的存储，字节始终留在 git 工作树里、紧挨着冻结记录。

已知局限与不适用场景

这套机制有清晰的边界，原文没有回避。

两个样本无法估计 flaky 率，它们只检测到两个结果曾经不同过一次。如果需要概率，请用更长的测试活动，并且不要把这条记录描述成那样的活动。父 blob 规则也不评估断言强度——一个早先提交的属性可能几乎是同义反复（tautology），因此在依赖它之前必须亲自读一遍父文件。此外，建议的检查器不运行 pytest --collect-only，格式错误的 test_id 可能蒙混过检查；深度为 1 的浅克隆没有 HEAD^ blob 可解析，需要先 fetch 父提交，否则任务会失败关闭——这正是预期的默认行为。

明确不该使用这个门禁的场景包括：

没有父 oracle、也不打算单独提交一个的情况；每次运行都重写的快照套件没有东西可供 oracle_blob 钉定。
支付、认证、数据丢失相关的补丁——即便分歧是真实的，冻结记录也是错误路径，应当让测试保持红色并修改产品代码。
测试在 worker 之间泄漏状态时，共享污染可能在 fixture 哈希不变的情况下翻转结果，使分歧成为"假证人"。
审查者根本不会打开 record.json 时——未被阅读的冻结文件只是一个带了额外字段的跳过评论。

最终把关的仍是人。检查器只强制"形状"（shape），而不变量是否真正匹配 fixture，由审查者在复核时判断。审查者需要重新计算 fixture 摘要并与两条 disagreement 条目比对，确认 oracle_path 不在 diff 中，并打开父属性文件确认其断言陈述的是一个"不读生产 diff 也能解释清楚"的关系。两项都成立，才隔离那一个 test id，并立刻排一个后续任务删除冻结。

这套设计的价值不在于某个具体脚本，而在于它把一个工程治理原则落成了可执行的检查：让 AI 补丁无法通过重写证据来给自己放行。