跳到正文

把测试用例写成可执行的功能说明书

我希望读测试用例时,能直接看懂一个功能在什么情况下应该怎样表现。比如 Marker 的批注测试,可以从「一张表里已经有一条批注」开始,选中另一格文字,保存,再看两条批注分别高亮了什么。将来有人重写 Markdown 渲染,只要第二条批注又把整张表染亮,这条测试就应该失败。

Marker 是一个用 Electron 做的本地 Markdown 阅读和批注工具。最早发现这个问题时,表格里的第一条批注看起来是对的,第二条却可能选中整张表。这个现象很适合拿来检验测试怎么写。单独测「可以新建批注」,或者只断言「页面出现了第二条批注」,都会漏掉真正出了问题的范围。

把一次操作写成一条可检查的约定

浏览器的 Range 用两个节点和各自的偏移描述选区。选中一个单元格的全部内容时,边界可能落在单元格元素上,这时偏移数的是子节点。边界落在文本节点上时,偏移数的是 UTF-16 码元。两种算法来自 DOM 对节点长度的定义。应用接下来还要把选区映射到去掉批注标记的 Markdown 正文,最后再定位磁盘上带标记的源码。已有的批注会改变源码偏移,表格语法也会改变源码和渲染文本的对应关系。

表格选区经过正文偏移定位到 Markdown 源码,保存后重新渲染并检查高亮

回归用例在 Chromium 里加载一张已有批注的表格,用 Range.selectNodeContents() 选中第二行的「核对🙂原文」,再点击添加和保存。每一步都有可以核对的结果。

  • 交给保存接口的范围,落在去掉批注标记后的正文里,正好覆盖「核对🙂原文」的 6 个 UTF-16 码元。
  • 保存结果重新渲染后,已有高亮仍是「第一处」,新增高亮精确等于「核对🙂原文」。
  • 点击第二条批注,能读到刚刚提交的批注内容。

原来的选区无法定位时,保存应该暂停。如果把范围退回到整个表格,用户就会在别处留下批注。文档刷新时可以用一个反例来测这个约定:删掉作为锚点的原文,再检查保存按钮是否禁用、草稿是否还在,以及重新选择后能否继续保存。写盘失败则是另一个场景。用户仍能看到草稿,可以直接重试,重试成功后才出现已保存的批注。用例名里写清这些可见结果,下次有人改实现,就能从测试知道哪些行为要保留。

在能观察到问题的环境里测试

算错偏移时,直接给映射函数一段带批注的 Markdown 就能复现。高亮画到了哪儿,得看渲染后的文档。Marker 把这两类用例放在 Vitest 的不同环境里,另外用构建后的应用检查 Electron 的进程间通信。

环境 适合检查什么 Marker 的例子
Node.js 数据转换、文件系统语义、协议或 IPC 处理函数 给定正文偏移,检查生成的批注标记。用临时文件验证读写、越权路径和失败处理
Node.js 加 Happy DOM 需要节点、事件或简单组件交互的行为 给阅读区工具函数提供可控的 DOM,检查焦点、事件和状态更新
Vitest Browser Mode 加 Chromium 浏览器实现决定的选区、实际布局、滚动和键盘交互 挂载真实工作台,选中表格单元格,检查重新渲染后的高亮。用替身提供 preload 接口
构建后的 Electron 应用 主进程、preload、渲染器与本机能力能否一起工作 打开临时仓库,等索引线程就绪,保存批注,从页面读回,再核对磁盘上的 Markdown

对 Vite 项目,Vitest 可以继续用 Vite 处理 ?raw 导入和 Vue 单文件组件。Marker 的构建配置分成主进程、preload 和渲染器,浏览器测试显式复用了渲染器的 Vite 插件并启用 CSS。验证滚动时还得读取真正滚动的容器。页面能挂载、目标标题仍在 DOM 里,用户的阅读位置也可能已经回到顶端。浏览器用例通过 Vitest Browser Mode 运行。桌面用例由 Vitest 调用 Playwright 的 实验性 Electron 接口 启动应用。

桌面测试用单独的临时仓库和 userData 目录,应用退出后再清理。这样每次打开的文档、索引和用户偏好都由测试准备,也能走到实际的写盘入口。普通组件事件留在成本更低的环境。只需要模拟 DOM 时,可以按 Happy DOM 和 jsdom 的能力差异 选择。

用同一个坐标进入和退出阅读模式

Marker 的「专注阅读」按钮同时负责进入和退出。进入时工具栏新增了当前章节入口,右对齐的一排按钮变宽,把「专注阅读」向左推。此时用户原地再点一次,可能会点中章节。把章节入口放进可截断的标题区域后,章节标题可以随滚动变化,开关留在原处。

测试先记录按钮的 getBoundingClientRect(),点下去并等章节入口可见,再比较开关的位置和大小,最后在原来记录的屏幕坐标点第二次,确认阅读布局恢复。两次都用按钮选择器点击会重新寻找按钮,即使它中间移走了也能点到。在普通窗口和窄窗口各跑一遍,还能覆盖长标题挤压空间的情况。

Chrome 的 CLS 会排除标为 hadRecentInput 的位移,例如点击后 500 ms 内立即发生的重新布局。即使 CLS 为 0,同一个开关也可能从指针下移走。浏览器回归测试可以直接验证这次点击所依赖的位置。见 web.dev 的 CLS 计算说明。

让测试决定异步操作的完成顺序

用户先搜「旧条件」,马上改搜「新条件」。如果旧请求最后返回,界面应该继续显示新结果。这类测试用固定延时碰运气时,机器稍慢一点,两个请求就可能按另一种顺序完成。测试即使通过,也可能没有走到旧结果覆盖新结果的分支。

先确认旧请求已经发出,新请求返回并显示结果后才放行旧请求,最后继续使用新结果

这个用例用 Promise.withResolvers() 控制旧请求。先确认旧查询确实已经发出,让新查询正常返回,等新结果在页面上出现后,再调用 resolve() 放行旧请求。旧请求返回后,检查迟到的结果没有进入列表,再用方向键和回车打开新结果指向的文档。如果只检查旧标题没出现,列表被错误地清空也会通过。

同样的办法也适用于保存重试和定时刷新。模拟一个写入错误,等错误提示和草稿状态更新,再重试并检查实际提交次数。测试轮询时,可以只控制轮询用到的定时器,让组件更新和异步断言继续按正常时序执行。

测试文件写入时,完成信号尤其重要。Marker 有一处用临时文件写入后再重命名替换目标文件。测试一开始反复读目标文件来等变化,在 Windows 上遇到了读文件与重命名争抢的情况。改为在真实 rename() 完成后记录信号,再读取内容。这样可以在替换提交后核对磁盘上的结果。

看覆盖率时先找缺失的行为

我会同时看覆盖的行数和分支数。例如保存函数已经执行过,行覆盖率看起来不错,失败后是否保留草稿仍可能没测。错误处理写在同一行的条件表达式里时,这种差异尤其容易从行覆盖报告里漏过去。

Marker 用 coverage.include 把 src/ 下维护的 TypeScript 和 Vue 文件纳入统计,排除纯类型声明。这样没有被测试导入的源码也会出现在报告里。比较前后两次结果时,还要核对源文件范围、排除项和源码映射。改了 Vue 转换或采集配置后,报告分母可能跟着变,可以先建立一份同口径的基线。具体匹配规则见 Vitest 覆盖率范围说明。

同一口径下的两轮 Marker 测试 用例数 行覆盖率 分支覆盖率
补齐最后一批场景前 131 82.93%(5,240 / 6,318) 67.65%(2,979 / 4,403)
补齐最后一批场景后 168 90.89%(5,743 / 6,318) 76.97%(3,389 / 4,403)

有可执行行的 112 个源码文件都至少执行过一部分。另有 4 条真实 Electron 用例单独运行,未计入表里的覆盖率。表格取自 Vitest 的覆盖率汇总中的 total 字段。补测时我会继续从分支找具体的行为,例如保存失败后能否继续,迟到的结果会不会回写,以及写入被拒绝时原文件是否完整。

改某一个场景时,我会先运行对应的测试文件,看失败信息能不能指出具体行为。然后用 pnpm check 跑日常检查,用 pnpm test:coverage 核对源码缺口。改动经过 Electron 的启动、IPC 或本机写入时,再用 pnpm test:electron 运行构建后的应用。这些是 Marker 的脚本名,其他项目可以沿用自己的入口。

再遇到表格批注这类问题,我会先把当时的文档状态和用户操作留成一个小样本。给出具体的预期范围、保存后的内容和重新渲染时能看到的结果。以后即使选区映射重写了,维护者也可以直接从这条用例知道,选中第二格意味着什么。