A test that fails for the wrong reason is worse than no test at all.
It teaches the team to ignore red.
因为错误的原因失败的测试,比没有测试更糟——它会训练整个团队忽略红灯。
0. 先讲一个我自己的事故
在一次 17 个用例的回归跑批里,我的 agent 报了 7 个 FAIL。
这 7 个 FAIL,一条都不成立。
每一个用例的断言都通过了,产品行为完全正确。它们被判 FAIL 的唯一原因是:page.screenshot() 抛了一个错——跑批进行到第 11 条时,浏览器窗口被最小化了。
// 断言行:全部 pass
assert(els.length === 3); // ✅
assert(state.activeTab === 'info'); // ✅
// 证据行:抛错 → 整个用例被判 FAIL
await page.screenshot({ path: 'step11.png' });
// Error: Cannot capture a screenshot while the window is minimized.
我没有犹豫就把 7 个 FAIL 归给了"产品"。是 review 的时候才发现,产品根本没问题。
这就是本文要解决的一件事:
Agent 跑测试,最大的风险不是跑不通,而是它会自信地骗你。
The dangerous failure mode is not a crash. It's false confidence.
1. 问题的形状 / The Shape of the Problem
人工测试时代,"这个 FAIL 是不是产品的问题"由人的经验兜底。测试同学点一下就知道:"这不是 bug,是环境没起来。"
换成 agent 之后,这个判断必须被显式地写进流程,否则 agent 会默认做一个最糟的选择:
我没有观察到预期结果 → 产品有 bug。
这个推理链条里缺了一环:"我没有观察到"和"它不存在"是两件事。
同一天里我连踩三次,加起来 15 条假 FAIL:
| # | 事故 | 假 FAIL 数 | 真正的根因 |
|---|---|---|---|
| 1 | 取证通道失败,被当成断言失败 | 7 | screenshot() 抛错未隔离 |
| 2 | DOM 断言假阳性 | 8 | v-show 节点仍在、选择器跨区域污染 |
| 3 | 把构建默认行为当缺陷 | 连续错判 2 次 | webpack 自动注入 <link rel=prefetch> |
这三件事看起来是三码事,其实是同一个病:判定(verdict)和观测(observation)没有分离。
2. 事故一:证据通道失败,把 15 条结论污染了 7 条
症状 / Symptom
跑批到一半,窗口被最小化。screenshot() 开始抛错。后续每个用例都被整条判 FAIL,尽管断言全通过。
这个设计错误极其常见,因为它写起来最自然:
// ❌ 错误:证据是流程的一部分
async function runCase(page, c) {
const asserts = await check(page, c);
await page.screenshot({ path: `shots/${c.id}.png` }); // 抛错 → 整个 case 挂掉
return asserts.every(Boolean) ? 'PASS' : 'FAIL';
}
本质 / Root cause
断言是主体,证据是辅助。
The assertion is the verdict. The screenshot is a witness, not a judge.
取证是旁路动作(side channel)。旁路出问题,不应该反过来改写主路的结论。
解法 / The fix
把取证封装成永不抛错的函数,双通道降级,都失败就认账并放行判定:
// ✅ 正确:证据永不参与判定
async function capture(page, base) {
try {
await page.screenshot({ path: `${base}.png` });
return { ref: `${base}.png`, mode: 'png' };
} catch (e1) {
try {
// printToPDF 不依赖合成器帧(compositor frame),
// 窗口最小化时仍能出图 —— 这是唯一可靠的降级通道
await page.pdf({ path: `${base}.pdf`, printBackground: true });
return { ref: `${base}.pdf`, mode: 'pdf' };
} catch (e2) {
// 两条通道都失败:登记缺口,判定照旧
return { ref: null, mode: 'none', gap: [e1.message, e2.message] };
}
}
}
async function runCase(page, c) {
const result = await check(page, c); // 判定只来自这里
const shot = await capture(page, `shots/${c.id}`);
return {
...result,
evidence_refs: [shot.ref].filter(Boolean), // null 被过滤掉
shotMode: shot.mode, // png | pdf | none
evidenceGaps: shot.gap || [],
};
}
改完之后同一场景的结果:
| 修复前 | 修复后 | |
|---|---|---|
| 用例结果 | 10/17 + 7 条假 FAIL | 17/17 |
| 证据 | 7 条用例无图 | 25 张图(中途自动切 PDF) |
| 团队反应 | 以为产品大面积故障 | 正常,只是窗口被最小化了 |
一个反直觉的注意点
不要用"视口尺寸"去判断"能不能截图"。
窗口最小化时,视口仍然是非零的——我实测是 995x913。也就是说:
const { viewport } = page.info();
// viewport.width > 0 ✅ ... 但截图照样失败
尺寸探针会静默通过,然后截图炸掉。正确的做法是直接看错误文案:
if (/while the window is minimized/i.test(err.message)) {
// 明确是窗口状态,可自动恢复后重试
}
Probe the error message, not the proxy metric.
探错误文案,不要探代理指标。
3. 事故二:DOM 断言的假阳性(8 条)
这批 FAIL 更好笑——产品确实是对的,是我的选择器在说谎。
陷阱 1:v-show 的节点永远在
Vue 的 v-show 只是切换 display:none,DOM 节点不会移除。
// ❌ 关闭弹窗后,节点还在,断言恒为 true → 永远 PASS(假阴性)
!!document.querySelector('.overlay')
// ✅ 必须读计算样式
getComputedStyle(document.querySelector('.overlay')).display !== 'none'
我第一次写成了反向判断("遮罩残留"),结果弹窗已经正常关闭了,却一直报残留。
陷阱 2:同名 class 跨区域污染
一个弹窗里的 tab 和设置页侧栏的 tab,用了完全相同的 class。全局查询把两处一起数了:
// ❌ 数出 8 个 tab,误判"渲染异常"
document.querySelectorAll('.header-tab .buttons')
// ✅ 必须限定作用域
document.querySelectorAll('.modal .header-tab .buttons')
Every selector needs a scope. UnscopedquerySelectorAllis a false-positive generator.
选择器必须限定作用域,否则它就是个假阳性发生器。
陷阱 3:goto() 会毁掉 SPA 上下文
在单页应用里用 page.goto() 切页,会重建整个文档。之后 page.evaluate() 直接报:
'Runtime.evaluate' wasn't found
正确做法是走路由:
// ❌ 整页重载,Vue 实例被销毁
await page.goto('https://app/#/settings');
// ✅ 只改 hash,保留应用上下文
await page.evaluate(() => { location.hash = '#/settings'; });
陷阱 4:恒真断言
// ❌ 永远不会失败 —— 等于没验
assert(result.text || true);
assert(!!(await page.$('body')));
自检方法:把断言逐条读一遍,问"它有可能为 false 吗?"
如果答不上来,这条断言就是装饰品。
4. 事故三:我把构建机制的默认行为当成了缺陷
这条最值得说,因为它不是技术问题,是思维问题。
场景:一个异步加载的对话框模块被改成了懒加载。我写的断言是:
冷启动时,不应该发起对这个模块的请求。
它一直 FAIL。我连续归因错了两次:
1. 第一次猜:会话复用导致缓存是热的 → 加了隔离,还是 FAIL 2. 第二次猜:CDN/浏览器缓存 → 清缓存,还是 FAIL
第三次我去拉真实数据,才发现真相:
打包工具为每一个异步 chunk 自动注入了 <link rel="prefetch">,这个应用一共 51 条,其中就包含那个模块。所以冷启动必然预取。
这是构建工具的默认行为,跟本次改动毫无关系。 我的断言从一开始就是错的。
正确的判据应该打在改动真正改变了什么上:
| 判据 | 结论 | |
|---|---|---|
| ❌ 错 | 冷启动是否预取该 chunk | 受构建机制支配,改动前后完全一样 |
| ✅ 对 | 代码是否已从主包拆出 | 主包 1.14MB 不含模板 / chunk 92KB 含模板 / 主包以动态 import() 引用 |
元教训 / Meta-lesson
连续两次归因错误,都是因为用推测代替了数据。
Twice in a row, I explained a FAIL with a hypothesis instead of an observation.
正确动作不是"再想想还有别的原因吗",而是把观测数据拉出来:
// 别猜,直接看
performance.getEntriesByType('resource').map(r => r.name)
document.querySelectorAll('link[rel=prefetch]').length
5. 核心解法:把归因显式化(failure_class)
上面三个事故有个共同点:每次都是"我以为"而不是"我验证"。
所以我给每个用例强制加一个字段:failure_class。它必须在报告里出现,不能留空。
九类 / Nine classes
| class | 含义 | 计作"产品未通过" |
|---|---|---|
PRODUCT_BUG | 产品行为与规格不符 | ✅ 是 |
HARNESS | 脚本/选择器/驱动没打通 | ❌ |
TEST_DATA | 前置数据不对 | ❌ |
SPEC_GAP | 需求没写清,无法判断对错 | ❌ |
ENV | 环境、部署、依赖问题 | ❌ |
TOOLING | 工具链或浏览器能力缺陷 | ❌ |
TIMEOUT | 超时(须进一步细分) | ❌ |
FLAKY | 不稳定,需复现确认 | ⚠️ 部分 |
TEST_CASE | 用例本身写错 | ❌ |
两条硬规则 / Two hard rules
规则一:只有 PRODUCT_BUG 才计入"产品未通过"。
其余全部进"阻塞分桶(blocked bucket)"。这个区分让报告从"17 个挂了 7 个"变成:
PASS 10 · PRODUCT_BUG 0 · HARNESS 7
一眼就知道:产品是好的,是我的 harness 有问题。
规则二:元素找不到时,先标 HARNESS,不要直接判产品 bug。
// ❌ 危险的默认值
if (!(await page.$('.submit-btn'))) return fail('PRODUCT_BUG');
// ✅ 先怀疑自己,兜底跑一次
if (!(await page.$('.submit-btn'))) {
const retry = await retryOnce(page, c); // agent 兜底,恰好 1 次
if (retry.ok) return pass();
// 两次都失败,且现象像产品问题,才升级
return fail(candidateLooksLikeProductBug ? 'PRODUCT_BUG' : 'HARNESS');
}
这条规则的价值观是:默认可信的是产品,不是你自己的脚本。
Default to trusting the product, not your selector.
为什么这套东西值得单独拿出来讲
因为它和具体工具无关。不管我用的是 Playwright、Puppeteer、Playwright MCP、还是自研的浏览器驱动,failure_class 这套语义都不用改。
它是测试报告的信任模型(trust model),不是某个 API 的用法。
6. 可以直接抄走的自检清单
断言层
- ☐每条断言都问过一遍:它有可能为 false 吗?(排除恒真断言)
- ☐
v-show控制的元素,读的是getComputedStyle().display,不是节点存在性 - ☐所有
querySelectorAll都限定了父级作用域 - ☐SPA 切页用
location.hash,不用goto() - ☐断言基准用实测值(如
window.innerHeight),不用设计常量
证据层
- ☐
capture()永不抛错,双通道降级(PNG → PDF → 记录缺口) - ☐取证失败不改写 result
- ☐证据缺失登记在独立字段(
evidenceGaps),与其他判定字段分离 - ☐用错误文案判断能力可用性,不用视口尺寸这类代理指标
归因层
- ☐每个 FAIL 都有
failure_class,不允许为空 - ☐元素找不到时默认
HARNESS,兜底一次后才考虑升级 - ☐报告区分"产品未通过"和"阻塞",不合并成一个失败数
- ☐归因前先拉观测数据(resource timing、DOM 快照),不靠推测
元层(最重要)
- ☐同一现象连续两次归因失败时,停下来拉数据,不要继续猜
- ☐设计断言前先问:这个判据受不受构建/框架/环境机制影响?
- ☐断言打在"本次改动真正改变了什么"上,不是"我以为应该怎样"
7. 一句话收尾 / One Line
自动化测试的可信度,不取决于你跑通了多少条,而取决于你能否说清每一条为什么挂。
The credibility of a test suite is not how many cases pass.
It's whether you can explain why each failure failed.
我最初的问题是"怎么让 agent 跑得更多"。真正的问题其实是:
怎么让 agent 的结论可以被相信。
这两件事之间,隔着一整套归因机制。
这些数字(7 条、8 条、连续 2 次)都是真实事故记录,不是构造的例子。 写出来是因为它们比"最佳实践"更有用——最佳实践告诉你怎么做对,事故告诉你错在哪。