把验收做到「人只拍板」:三层验收方案(中) | 杨元超的世界

这篇写给谁

约 13 分钟读完;需要你会写 JavaScript、看过别人写测试;不知道什么是「可播种随机」也能跟——第四节会从零解释。

上一篇讲了三层怎么分工,下篇讲同一套分层搬到多人联网时的差异。这一篇只讲第一层怎么落地。读完你能带走四件可直接照搬的事:一份用例归档判据、一套失败分类规则、一个入口与索引的对账脚本、一个二十行的可播种随机源。下文的「E2E」指端到端测试,即从界面入口一路跑到结果的全链路自动化测试。

下面这张表按角色说明你能带走什么、从哪一节读起:

读者 带走什么 拿它做什么 从哪节开始读
测试越写越多的团队 四道「可删 / 可归档」判据 照「用例的生命周期」一节清理自己的用例库 3
每天看失败报告的人 按失败块类型分层的归因法 抄「失败要说清原因」一节的分类函数 4
维护十几个脚本的人 统一入口 + 双向索引对账 按「一个入口、一张索引」一节收成一个入口 5
排查「时好时坏」的人 可播种随机源与验证方法 用「让随机可复现」一节的 32 次前缀比对证明可复现 6

不适合谁:想要一个现成测试框架的人——这篇给的是判据和脚本骨架,不是框架选型。

环境准备

# 装浏览器自动化(本项目用 Playwright 1.x 驱动本机 Chrome)
# 只需要装一次,之后复用本机 Chrome
npm install -D playwright

后面每节的示例都是单文件脚本,放在 test/e2e/ 下用 node <文件名> 直接运行,不需要额外依赖。

全文概要

先把这篇的位置说清。三层验收是:第一层逻辑与接口测试、第二层无头代打、第三层渲染抽检加人拍板。第一层最便宜、跑得最早,它的结论是后面两层的输入。

但第一层有一个隐藏前提:「跑测试的这套东西」本身得可信。如果用例越攒越多、失败说不清原因、入口有十几个、同样的输入每次结果不同,那第一层全绿也只是噪音——你只是更快地得出「不知道」。

这篇就是修这个前提,四个支撑缺一不可:

支撑 治什么 一句话判据
用例生命周期 用例只增不减,一半从来没跑过 归档后活跃用例数下降,且旧端口引用为 0
失败归因 失败一半落在「其他」,说不清原因 无法归类的失败数为 0
统一入口与索引 十几个脚本,索引和代码对不上 代码里有的方法索引都有,反之亦然
可播种随机 同一问题复现不了 同种子重复 32 次,前 32 个随机值逐值相等

这四个支撑做在测试系统上,受益最大的是第一层,但第二层和第三层复用同一套运行器与证据格式——地基修好了,上面的两层才有意义。需要说明:下面引用的数据来自自动化运行器(浏览器 E2E 场景),因为四个缺口都是在那套运行器上暴露的;第一层的纯函数与接口测试复用同一份用例清单、同一个运行器和同一种失败证据格式,所以修地基的收益对三层共用。

支撑一:用例的生命周期

先说现象。一个跑了两年的项目,自动化用例通常长这样:场景数量一路上涨,但真正每天在跑的只有一部分;其余的要么是当初排查某个问题临时写的,要么是某个功能下线后忘了删。

一次盘点结果:

指标 数量
场景总数 112 个
运行记录里出现过的 51 个
从未跑过的 61 个(54%)

一半以上的用例从来没被执行过。它们不是「备份」,是「没人敢删所以留着」的负担——每次跑全量都在为它们付出成本,而它们从不产出信号。

原来的做法:看到没跑的就想删。但直接按「没跑过」筛,会删掉真正需要保留的东西。

现在的做法:四道判据,按顺序判,任何一道不过就不删:

顺序 判据 为什么
1 从未跑过 + 30 天未改 + 零引用 30 天约等于两个迭代周期;三个条件同时满足才算僵尸
2 跑过但从未通过 → 先分类 可能是故意失败的用例,不能当垃圾
3 指向已经不用的端口 端口死了,用例必然连不上
4 时长超预算只拦新增 存量先不追,避免为了达标乱删

第 1 条最有意思:只按「从未跑过 + 30 天未改」筛,会得到 41 个候选;再加上「零引用」这个条件,只剩 1 个真正可删。大部分看起来没用的用例,其实是别处还在引用的证据。这正是不该图省事的原因。

下面这段脚本做的是「找到可归档候选」,跑完打印候选清单,退出码 0 表示没有违规引用:

// scan-scenarios.cjs:列出从未跑过、30 天未改、且零引用的场景
const fs = require('fs')
const path = require('path')

const RUNS_DIR = 'test/e2e/runs'          // 每次运行的元数据
const SCEN_DIR = 'test/e2e/scenarios'     // 场景 JSON
const TWO_ITERATIONS_DAYS = 30            // 约两个迭代周期

const seen = new Set()
for (const f of fs.readdirSync(RUNS_DIR)) {
  const meta = JSON.parse(fs.readFileSync(path.join(RUNS_DIR, f), 'utf8'))
  if (meta.scenario) seen.add(meta.scenario)
}

const all = fs.readdirSync(SCEN_DIR).map(f => f.replace(/\.json$/, ''))
const referenced = new Set()
for (const s of all) {
  const src = fs.readFileSync(path.join(SCEN_DIR, s + '.json'), 'utf8')
  for (const m of src.matchAll(/"scenario"\s*:\s*"([^"]+)"/g)) referenced.add(m[1])
}

const candidates = all.filter(s => {
  if (seen.has(s)) return false
  const mtime = fs.statSync(path.join(SCEN_DIR, s + '.json')).mtimeMs
  const old = Date.now() - mtime > TWO_ITERATIONS_DAYS * 864e5
  return old && !referenced.has(s)
})
console.log(candidates)
process.exit(candidates.length ? 1 : 0)   // 有候选就返回非零,提醒处理

差别:清理前活跃用例 112 个、盲等 532 块、总时长 7468.5 秒;归档 38 个之后,活跃用例 74 个、盲等 312 块、总时长 4621.3 秒。省下的 2847 秒(约 47 分钟)不是靠「跑得更快」,是靠「少跑不该跑的」。

这一节踩过四个坑,都很常见:

坑是什么 为什么是坑 如何解决 为什么能解决
条件漏字段 误归档了 12 个还在用的新用例 判据写成「全部满足才归档」,并在严格模式下报错 默认不删,误判方向是安全的
用文件修改时间算年龄 一次格式化会刷新时间,老用例看着很新 改用版本库的最后提交时间 提交时间不会因为内容整理而变
把平时不跑的回归用例当僵尸 回归用例本来就很少跑 单列一类,只归档不删除 保留证据,不参与日常运行
归档目录还在扫描面 归档后总数没变 扫描默认排除归档目录 归档即出扫描面

支撑二:失败要说清原因

第二件事:一条用例红了,报告只说「超时」或「其他」。看的人得自己翻日志猜。

一次基线统计:422 次执行,成功率 52.8%,失败率 45.3%,平均一次 85.4 秒。其中 153 次失败,按旧规则归类,有 101 次(约三分之二)落到「其他」——只有 52 次能说清是哪类问题。

原来的做法:只用错误文本匹配关键词,像下面这段:

// 旧:只看错误文本
if (/timeout|Timeout/.test(err.message)) return 'timeout'
if (/assert/i.test(err.message)) return 'assert'
return 'other'   // 大量失败堆在这里

问题在于:错误文本一半是人写的、一半是库写的,格式无穷无尽,你永远补不完关键词。

现在的做法:先看「失败发生在哪个类型的动作块」。块的类型是运行器自己定义的有限枚举(打开页面、执行脚本、截图、等待状态……),不是人写的自由文本,所以它天然可分类。

// classify.mjs:先按块类型分,再用文本兜底,第一个命中即返回
const TYPE_RULES = [
  ['zz-crash',        '故意崩溃测试'],   // 故意失败的用例放最前
  ['wait-state',      '等待状态'],
  ['screenshot',      '截图'],
  ['check-errors',    '页面错误检查'],
  ['evaluate-page',   '页面执行错误'],
]

export function classify(failure) {
  const { blockType = '', message = '' } = failure

  for (const [type, label] of TYPE_RULES) {
    if (blockType.startsWith(type)) return label
  }
  if (/timeout/i.test(message)) return '超时'
  if (/BLOCK_NOT_FOUND/.test(message)) return '动作块缺失'
  if (/assert/i.test(message)) return '断言失败'
  return 'OTHER'   // 归到这里必须为 0,否则说明规则有洞
}

改造后的分布:页面执行错误 102、故意崩溃 39、页面错误检查 7、截图 4、等待状态 1,合计 153——总数对得上,且「其他」为 0。故意失败的 39 次单独成类,不再把失败率虚高四分之一。

这条规则有一个必须守住的性质:分类总数要等于失败总数。旧规则按文本匹配,同一条失败可能同时命中两个关键词,被重复计数,总数会超过失败数。新规则「第一个命中即返回」,从结构上杜绝了重复。

验收是一条自测:准备三组输入——正常失败、恒真断言、恒假断言,前两组走正常路径,后两组必须被分到预期类别。分类函数本身也要能被证伪。

支撑三:一个入口、一张索引

第三件事:脚本多了以后,没人知道该跑哪个。改造前有 13 个测试脚本,散在不同目录;一个一千六百多行的公共逻辑文件里有 44 个方法,而手写的索引只登记了 41 条。第一次合并两处改动时,检查就抓到索引漏了 3 个方法。

原来的做法:谁用谁记,索引靠人手写。

现在的做法:一个入口 + 一张索引 + 一个对账脚本。

入口只做调度,不改任何语义。下面这张表是七个动作,覆盖日常:

动作 作用
list 列出所有场景
run 跑指定场景或全部
verify 只做校验,不跑浏览器
diag 跑诊断型场景
capture 采集截图与状态
inventory 盘点场景与动作块
health 自检运行环境

索引是方法级的。下面这段对账脚本从代码里按结构抽方法名、从文档里抽索引名,双向比对:

// check-index.mjs:双向对账,缺失或过期都返回非零
import fs from 'node:fs'

const code = fs.readFileSync('src/hooks/registry.ts', 'utf8')
const doc = fs.readFileSync('test/e2e/E2E-INDEX.md', 'utf8')

// 只抽「方法定义」这一种结构,不做全文搜索
const inCode = [...code.matchAll(/^export function (\w+)/gm)].map(m => m[1])
const inDoc = [...doc.matchAll(/^\|\s*`?(\w+)`?\s*\|/gm)].map(m => m[1])

const missing = inCode.filter(x => !inDoc.includes(x))  // 代码有、索引没有
const stale = inDoc.filter(x => !inCode.includes(x))    // 索引有、代码没有

console.log({ missing, stale })
process.exit(missing.length === 0 && stale.length === 0 ? 0 : 1)

差别:接入后代码 44 条、索引 44 条,缺失 0、过期 0;而在接入前,同一套检查会报「索引 41、缺 3」。

对账脚本自己也要能被证伪。它的自测有四组:真方法必须被识别、注释里的方法名不算、代码多一个必须报缺失、索引多一个必须报过期。前两组应正常通过,后两组必须失败——只有后两组真的失败,才说明脚本不是永远返回成功。

支撑四:让随机可复现

最后一件事,也是最容易被当成「玄学」的一件:同一个操作,这次暴击、下次不暴击,问题复现不了。

先解释「可播种随机」。普通的随机函数(Math.random())每次调用都从一个不可控的内部状态取值,你无法让两次运行走同一条随机序列。可播种随机则是:你给它一个初始值(种子),它按确定算法生成一串看起来随机的数;同一个种子必然生成同一串数。这样「这次暴击下次不暴击」就变成了「换个种子才会变」,问题可复现。

项目里原有 201 处 Math.random(),分布在 74 个文件。

原来的做法:各函数直接调全局随机。

现在的做法:统一一个随机源,先把「影响判定结果」的调用迁过来,表现层的先不动。

// mulberry32:32 位状态、无依赖、约二十行;只用于游戏逻辑,不做密码学
export function createRng(seed) {
  let s = seed >>> 0
  return function next() {
    s = (s + 0x6D2B79F5) >>> 0
    let t = s
    t = Math.imul(t ^ (t >>> 15), t | 1)
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
  }
}

迁移有顺序,别一上来就全改:

顺序 迁什么 为什么这个顺序
1 暴击、命中、部位 取值点集中,日志里能看到,最容易验证
2 选目标、刷怪位置与间隔 影响整局走向,越早迁越早可复现
3 粒子、屏幕抖动、音效 只影响表现,不影响判定,可以最后迁

验证方法不是「跑两次看像不像」,而是比公共前缀:同一个种子连跑 32 次,记录每次生成的随机数序列,取所有序列的公共前缀长度。实测同种子 32 次的前 32 个值逐值相等(32/32),换种子则一个都不相等(0/32)。

为什么比公共前缀、不比整段数组?因为两次运行消耗的随机数个数可能不同(一个分支多调用了一次),整段比较会假失败;公共前缀比较的是「走到分叉之前是否一致」,这才是可复现的定义。

这一节也有四个坑:诊断脚本只采一帧(第一帧全落在概率入口,看不到下游,至少采两帧相减);页面连到了另一个端口的旧构建(先在产物里搜新函数名确认版本);概率为 0 时看到「全未命中」就以为坏了(要看调用次数,不看命中率);命令行参数没转发到执行器(种子只从场景字段读,不从命令行读)。

验收判据:四个支撑各一条命令判绿

四个支撑都落地后,用一条命令看整体,四条判据分别看单项:

支撑 命令 通过 不通过
生命周期 node test/e2e/scan-scenarios.cjs 候选清单为空、退出码 0,旧端口引用为 0 有候选却无人处理
失败归因 node test/e2e/baseline.cjs 「其他」类为 0,分类总数 = 失败总数 其他类大于 0
入口与索引 node test/e2e/check-index.mjs 缺失 0、过期 0、退出码 0 任一非 0
可播种随机 node test/e2e/seed-proof.cjs 同种子公共前缀 32/32,异种子 0/32 同种子不足 32

整体收口用下面这条命令,任何一项红就返回非零:

# 一条命令跑完四检;任何一项红就退出非零
# health 查环境,baseline 查归因,check-index 查索引,seed-proof 查可复现
node test/e2e/e2e.cjs health && node test/e2e/baseline.cjs && node test/e2e/check-index.mjs && node test/e2e/seed-proof.cjs

注意「一个入口、一张索引」和「让随机可复现」两节的示例脚本是骨架,直接抄要按自己项目的目录名和方法命名调整;「失败要说清原因」一节的分类函数可以直接用,只要把块类型换成你自己的枚举。

总结

这篇讲第一层为什么可信,靠的不是更多断言,而是四个支撑:

四件事合起来的效果,是把「跑完两小时还得人点一遍」变成「跑完 77 分钟、失败能说清、结果可复现、人只处理真正的异常」。第一层的绿,到这一步才算数。

还能怎么改进

当前做法的边界:

下一步可以往三个方向走:把归因规则从「块类型」再细分到「块内阶段」;把生命周期判据和运行记录联动,跑过但长期没失败的用例也进入观察名单;把随机源和代打场景绑定,做到「一个种子 = 一局完整可复现的对局」。

你下一步能做什么

打开你项目的测试目录,数一下「从未跑过的用例」占比。如果超过三成,先别加新用例——照「用例的生命周期」一节给它们定一个归档判据,把库先瘦下来;库瘦不下来,后面三条都做不动。

这些内容来自哪里

这些内容来自一个真实实时项目里同一套自动化测试系统的改造过程,时间跨度数周,前后处理了一百多个场景、四百多次历史运行的归因,以及分布在几十个文件里的随机调用。文中的数字都来自改造前后的实测统计,四道判据、分类规则和种子验证方法则是改造后用可执行脚本固化下来的。

相关文章