博客

让 AI agent 测行为,不要测实现

审计了 5,087 个测试,34% 至少断言了一处实现细节。这篇给出让 AI 编程 agent 写行为测试的三条规则、浏览器测试写法,以及审计自己测试套件的方法。

本页目录 · 10 节
  1. 什么算行为
  2. 规则一:写清楚一个测试可以断言什么
  3. 规则二:验收条件描述结果,不描述代码
  4. 规则三:一次性的等价检查放进 PR,不进测试
  5. 浏览器和端到端测试的规则
  6. agent 为什么偏向写实现测试
  7. 审计查到了什么
  8. 怎么审计你自己的仓库
  9. 让测试套件更快(Cloudflare Workers 和 Vitest)
  10. 相关

如果你的测试大多是 AI agent 写的,里面很多可能在测「代码怎么写的」,而不是「用户看到什么」。我们仓库全部 5,087 个测试里,有 34% 至少夹带了一条这样的断言(很多同时也测了可见行为,所以这是「至少有一条实现断言」,不是「34% 是坏测试」,更严口径见后文)。而这些测试又在决定什么能合并。这篇写给正处在这个局面的团队:给出我们用来让 agent 写行为测试的三条规则、浏览器测试具体怎么写,以及一套半小时就能审计自己测试套件的方法。还会讲我们怎么把 CI 里的测试步骤从 4 分 26 秒压到 1 分 39 秒(Cloudflare Workers):主要靠调大 worker 数,下面那处 setup 改动是小头。

我是 Larry 🍀 Orbi,Orbi 的创始人。Orbi 是一个交付引擎:它接一个 GitHub issue,让一个 agent 写代码和测试,另一个 agent 评审这次改动,然后合并、发版,默认全程没有人把关。我们的托管产品 Orbi Cloud 是一个代码库,大部分由 Orbi 自己建。11 月 18 日,我们把这个代码库全部 5,087 个测试分了类:其中 1,739 个,34%,至少断言了一处实现细节。下面的规则是之后改的;审计在后面,作为证据。

什么算行为

行为测试断言的是用户或调用方能观察到的东西:一个 HTTP 状态码加页面上的文字、渲染出来的页面让你看到和点到什么、代码发出的邮件或 GitHub 评论的内容、库里记录一条业务事实的行、脚本的退出码和输出。

实现测试断言的是代码碰巧怎么写的。审计里我们把它分成六类,这份清单也当评审的判据用:

  • A:读源码文本(在文件里搜字符串、数规则条数、断言「只有一处实现」)。
  • B:断言内部函数的参数、调用次数或调用顺序。跨越真实边界的调用(发邮件、调 GitHub 或 Stripe)并断言发出去的内容,算行为。
  • C:断言 SQL 文本、表名或索引名。
  • D:断言内部形状:数组长度、对象的键、常量值、用户看不到的 CSS 类名或元素 ID、页面脚本文本、CSS 文本、整段 HTML 字符串。
  • E:钉住内部结构而非可见输出的快照。
  • F:调用一个内部辅助函数、断言它的中间返回值。如果这个辅助函数本身就是一条业务规则(比如「试用期什么时候结束」),那算行为。

判断一个测试,问两句。第一句:用户看到的东西没变,它会不会变红?会,就是钉在实现上了。第二句:它声称要覆盖的那个行为坏掉了,它还会不会是绿的?会,就说明它断言错了对象,要么改断言,要么补覆盖。(一个只断言标题文字的测试,在按钮坏掉时仍然绿,这不是在测实现,只是它从没覆盖那个按钮。)

规则一:写清楚一个测试可以断言什么

agent 照仓库里的指令文件办事。我们原来关于测试只有一句:别给 UI 结构或样式写单元测试。这句话对读源码、断言 SQL、数内部调用次数只字未提,所以这些都不算越界。现在 AGENTS.md 的测试一节是这条规则:

测试只断言用户或调用方看得到的结果:接口返回、页面上的文字和链接、发出去的邮件和 GitHub 评论、库里代表业务事实的记录、脚本的退出码和输出。下面这些不要写,哪怕票里要求了(真要求了,就在 PR 里写明你改成断言了哪个可见结果):读源码文本(搜字符串、数规则条数、断言只有一处实现);页面脚本或 SQL 语句怎么写的;内部函数的参数和调用次数(发到外部的内容除外);内部数组长度、常量值、元素 ID;整页哈希快照。

这条规则里关键的是两处。清单列的是具体形态,而不是「避免实现细节」这种话,因为 agent 会照着清单一条条抠,却会把原则用得很松。而「哪怕票里要求了」这句,是因为我们有些票确实就是这么要求的(下一条规则)。

规则二:验收条件描述结果,不描述代码

有段时间我自己写票的规则是:当两处代码必须共用同一个判断时,验收条件应该写成「只有一个渲染函数」。交付 agent 就照这句字面做了:它写了一个永久测试,扫描源码,一旦出现第二处实现就让测试失败。审计里好几个读源码的测试都能追到这样写的票。

所以现在的验收条件写的是:规则一旦坏掉,用户会注意到什么。「只有一个函数决定标题」改成了「同样的输入,首次渲染和实时更新显示的标题一致」。agent 要满足它,只能把两处都渲染出来、比较一个人会读到的内容,而且这个测试能扛过任何保持标题正确的重构。

我们的评审 agent 拿 diff 对照验收条件看。一条描述源码结构的验收条件,会把写测试的 agent 和评审的 agent 都往「检查结构」而不是「检查结果」上引,所以验收条件怎么写,测试就会断言什么。

规则三:一次性的等价检查放进 PR,不进测试

「这次重构什么都没改」这句话只在重构当天成立。证明它,靠的是把前后输出贴进 PR,而不是加一个永久测试。

这个教训我们吃了两次。开源引擎上,CLI 输出的一份 golden 快照(存下来逐字比对的基准输出)记下了整行 orbi 0.7.15,于是 v0.7.16 的发版提交让 main 上的测试任务红了:每次版本号一升,那一行就被重写。修复(orbi c5e0f0db)把 --version 单独放一个测试、对着包版本号断言,golden 快照里不再留版本行,这样发版升号照样绿,而 help 文案真变了还是会红。Orbi Cloud 上,状态页按卡片类型拆成一个文件一类时,agent 加了个测试,渲染 18 种卡片状态、把每页的 SHA-256 和存下来的值比。那之后页面上任何一处改动都得更新存下来的哈希:在这个测试被删掉前的九天里,一共有 35 个非合并提交动过那个夹具文件,不全是为了快照,但其中大约五个提交的说明写的就是「这次只是重新生成快照」。这个测试后来换成了断言每张卡显示什么。

浏览器和端到端测试的规则

浏览器测试里,这些规则变得很具体:

  • 让页面像在浏览器里那样跑自己的脚本。测试要用假网络或假定时器,就在页面加载前装好。我们大约 50 个浏览器测试文件原本是这么干的:

    const source = [...rendered.querySelectorAll("script")]
      .map((script) => script.textContent ?? "")
      .find((text) => text.includes("delivery-progress-data"));
    expect(source).toBeTruthy();
    

    它们把页面的脚本剥下来、装上桩,再去执行那个靠搜字符串找出来的脚本。改一下那段脚本里一个数据块的名字,就会让一堆本来正确断言了可见文字的测试一起红。

  • 断言一个人会看到或做到什么:标题文字、哪个按钮可点、假服务器应答后页面显示什么、页面发出的请求。类名、节点身份和 outerHTML 都不要碰。

  • 比较两次渲染,比的是它们显示什么。「实时更新显示的标题和首次渲染一致」能扛过重新设计样式;「这一行的 outerHTML 等于服务器返回的」扛不过。

  • 布局用几何量检查,别用字符串。数行数或「包含某字符串」这种检查,布局烂成什么样都能过。浏览器测试可以断言算出来的尺寸和位置:我们有一个就检查某个按钮在标题下方、占满整行、至少 44 像素高。那些没人想到要编码进去的,我们就在桌面和手机两种宽度、中英两种语言下截 staging 站的图,用眼睛看。

曾经有个 PR 零严重问题通过了评审,而它票里列的 14 处设计差异还有 10 处在那里,包括一个标题渲染成了每行一个字。每个测试都在断言字符串,而且全过了。

agent 为什么偏向写实现测试

很容易说 AI agent 就爱测实现。我们的证据指向的是 agent 周围的那套设置:

  • 票。 有些验收条件描述的是代码(「只有一个渲染函数」),agent 照字面做了(规则二)。
  • 仓库规则的漏洞。 指令没明令禁止的,都是允许的(规则一)。
  • 从红到绿最省力的测试,钉的就是这次 diff。 一个要关票的 agent 需要一个「改动前失败、改动后通过」的测试。最省力的那个,就断言新加的字符串、类名或函数调用现在存在了。而行为测试需要一个夹具、一个渲染出来的页面或一个跑起来的脚本。这是我们对这个模式的解读,不是量出来的数。

这些都不是 AI 独有的。Kent C. Dodds 在 Testing Implementation Details 里描述过人写的 React 测试一样的毛病:重构时会红、应用坏了反而绿。Google 的测试博客 2013 年就说过:测行为,不测实现。agent 会写得更多,也更照字面:一张票暗示要写的每个测试它都会写,每张同样写法的票它都照做。

测试在把关合并时,这事更要紧。Orbi 在评审和 CI 都过了之后就合并,默认没有人在中间看。一个实现测试在无害的改名上变红,就挡住一次合并、烧掉一轮评审。一个在页面坏掉时还绿的测试,会让这个故障蒙混过关。

审计查到了什么

仓库有三个测试套件。计数按测试用例算,参数化用例展开,取 commit 4619a9fc 时的状态。

套件 测试用例 至少一处实现断言 占比
主套件(Workers 单元和集成测试) 3,999 1,046 26%
浏览器(真实浏览器里渲染页面) 639 466 73%
主机脚本(开通、部署、定时器) 449 227 51%
合计 5,087 1,739 34%

一个既断言了可见结果、又断言了实现细节的测试,算作实现,所以这些数字包含了混合测试。466 个浏览器测试里有 244 个确实检查了可见行为,只是因为用搜文本的办法找页面脚本(上面那个模式)才被算进去。从 1,739 里减掉这 244,仍有 1,495 个测试(29%)至少有一处实现断言。

按类别看,跨三个套件:约 490 个测试读源码文本,约 100 个断言内部调用的参数或次数,35 个断言 SQL 文本,最大的一类是内部形状,光主套件就有 939 个。再给两个例子,用测试自己的话:

  • 页面「刷新」是因为它的源码里含 location.reload()。 一个测「刷新建议」按钮的测试,检查渲染出来的 HTML 里含有 fetch("/api/suggestions/rerun"、{ repo: repository }、const repository = "acme/demo"; 和 location.reload()。改一个局部变量名就让它红。而把按钮改坏、只要这些字符串还在,它照样绿。
  • 一个价格模板只准出现在两个文件里。 一个测试 glob 了所有源码文件,断言手写价格句的那个模式只在价格构造器里匹配到。用户真正在意的是每个页面显示同一个价格,而这个可以靠渲染那些页面、比较它们来测。

按 git blame 看,约 87% 的测试定义行(那些 it(...) 行)最后由 Orbi 的交付 agent 改动。主套件里,它最后改的行被判为实现的比例是 27.5%;最后由我的账号改的行(含本地 agent 会话)是 12.7%。这个差距不是干净的「人对 AI」比较:「我的账号」底下也多半是 agent 会话,两批票本身也不一样。但它和「问题主要出在照票写出来的代码里」这个判断是相符的。

规则 11 月 18 日落地。针对现有测试的七张清理票,从浏览器脚本那个模式和哈希快照开始,在 11 月 19 到 20 日之间合并。我们会对新测试重跑同一套审计,报告这条规则有没有守住。

怎么审计你自己的仓库

真正值得照搬的是这套方法。我们花了大约半小时的实际时间。

  1. 把上面六类写下来, 加上你自己的例外:哪些边界算对外,哪些辅助函数是业务规则。
  2. 把测试目录拆给几个互相独立、只读的 agent 会话。 我们并行跑了三个 Codex 会话,一个套件一个。只读很关键:评审方不能「改」一个测试去让它符合某一类。
  3. 让计数靠脚本,不靠一句话。 每个评审方维护一份 文件:行号 → 类别 的台账,总数靠跑一条命令得出:这条命令枚举测试注册、展开 it.each、检查每条台账指向的是一个真实的测试行、再求和。命令和它的原始输出都放进报告。之前有一次让 agent 数一张 20 行的表,它报了 21;靠文字描述报出来的计数不值得写进报告。
  4. 自己核一遍分类。 我读了五个被标记的测试,四个明显是实现,一个有争议:它数每个已连接仓库对应的断开表单的 action 属性个数,来检查「一个仓库一个断开表单」,这勉强算在数用户会点的控件。我们还另找一个 agent,只给它判据,对随机抽的 60 个主套件测试盲分类。它标了 3 个「不确定」,在其余 57 个里有 46 个(81%)和审计一致。11 处分歧里有 10 处方向一样:盲评方把审计判为行为的测试判成了实现。所以主套件那个数,更可能偏低而不是偏高。盲评方自己的汇总也把它的表数错了,这正是第 3 步存在的理由。
  5. 看类别,不只看总数。 一个被反复用的辅助函数、或一个快照文件,就能占掉几百个测试,而那是一处修复。
  6. 先改产生新测试的东西,再清理旧的: 指令文件和票的措辞。否则下周 agent 又照写一遍。

这是一次静态分类。我们没跑变异测试,那是研究界判断测试能不能抓到缺陷的标准工具。变异测试问的是「这套测试会不会注意到一个 bug」;我们问的是「用户看到的东西没变时,这个测试会不会红」,而读一眼断言就能直接回答后者。

让测试套件更快(Cloudflare Workers 和 Vitest)

这一节只适用于一种技术栈:用 Vitest 加 @cloudflare/vitest-plugin 测的 Cloudflare Workers。每条末尾给出通用的教训。

找出每个文件的开销。 11 月 18 日 CI 在 npm test 上花了 4 分 26 秒。Vitest 的累计列显示 setup 304.60s 对 tests 105.35s:每个文件的 setup 比测试本身还重。这个池给每个测试文件各一个 Workers 运行时,所以 setup 文件每个文件跑一次,大约 160 次。我们的 setup 用 cloudflare:test 的 applyD1Migrations 跑数据库迁移。光导入那个模块每个文件就要 1.78 秒;不用它、直接跑 86 条迁移约 0.06 秒。这个函数做四件事(建迁移表、读已应用的名字、跳过它们、把每条迁移和它的台账行放一个 batch 里跑),于是我们对着 env.DB 把它内联了:

import { env } from "cloudflare:workers";

const T = `"d1_migrations"`;
await env.DB.prepare(`CREATE TABLE IF NOT EXISTS ${T} (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT UNIQUE,
  applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL);`).run();
const applied = new Set(
  (await env.DB.prepare(`SELECT name FROM ${T};`).all<{ name: string }>())
    .results.map((row) => row.name));
const record = env.DB.prepare(`INSERT INTO ${T} (name) VALUES (?);`);
for (const m of env.TEST_MIGRATIONS) {
  if (applied.has(m.name)) continue;
  await env.DB.batch([...m.queries.map((q) => env.DB.prepare(q)), record.bind(m.name)]);
}

通用教训:setup 文件里的任何东西,都要乘以测试文件的数量。

量实际耗时(墙钟时间);Vitest 的累计列会骗人。 本地(32 核、开覆盖率、两个 worker),这次改动把整轮从 199 秒降到 156 秒,累计 setup 从 214 秒降到 8 秒。CI 上效果小些:npm test 步骤从 4:26 到 3:41,Vitest 自己的 duration 从 260 秒到 216 秒,约 17%。累计 setup 从 305 秒降到 22 秒,但 import 列从 11 秒涨到 115 秒、tests 从 105 秒涨到 205 秒。那些列是把并行 worker 的时间加起来,一部分开销只是从一列挪到了另一列。说「setup 降了 93%」没错,但会误导。单看这处 setup 改动,CI 上就是那 17%(4:26 到 3:41);真正降到 1:39 的大头,来自下面那处 worker 数的调整,所以别把那段内联迁移代码当成主要杠杆。

删掉断言耗时的测试。 更大的提升在并行度:CI 原本在一台 32 核机器上只跑两个 worker,因为这个设置是按我们 3 核的交付沙箱调的。本地上,八个 worker 加上 setup 那处修复,把套件压到了 69 秒。但到八个 worker 时,有个测试连红两次:expected 2216 to be less than 2000。它断言一次结账跳转在两秒内返回,用来证明跳转没有等一次分析写入。这个测试本来就把那次写入挡在一道闸后面、只在响应到达之后才打开,所以要是响应真等了写入,这个测试根本拿不到响应。那个两秒断言没带来任何保障,只会在高负载下变 flaky。任何拿实际耗时和阈值比的东西,在忙的机器上都会挂。

按机器设并行度。 配置默认留两个 worker 给沙箱,在那种 3 核机器上跑一整轮要 33 到 54 分钟。CI 设 VITEST_MAX_WORKERS=8。在做这件事的那个 PR 上(已经删掉那个比耗时的断言),npm test 步骤花了 1:39,而前一天是 4:26。

相关

为 Orbi 找 harness,第二部分 量了评审对没见过的 bug 能抓到多少、漏掉多少,AI 代码评审是瓶颈吗? 看合并的 PR 卡在哪。Orbi Cloud 在你的 GitHub 仓库上跑这里讲的这套循环(Issue → agent 开 PR → 另一个 agent 评审 → CI 绿了合并),对比页 把它和其他编程 agent 摆在一起。

Orbi 这周又能多做什么

每周一封:新功能、实测文章,还有我们自己用 Orbi 干活的数据。随时退订。