When Your Agent Reports a FAIL, Is It Real?

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取证通道失败,被当成断言失败7screenshot() 抛错未隔离
2DOM 断言假阳性8v-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 条假 FAIL17/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. Unscoped querySelectorAll is 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. 可以直接抄走的自检清单

断言层

证据层

归因层

元层(最重要)


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 次)都是真实事故记录,不是构造的例子。 写出来是因为它们比"最佳实践"更有用——最佳实践告诉你怎么做对,事故告诉你错在哪。