EasyInvoicePDF测试实践:用Playwright截图快照测试PDF输出的完整方案
EasyInvoicePDF测试实践:用Playwright截图快照测试PDF输出的完整方案
easy-invoice-pdf 是一个免费的开源发票生成器,用户在浏览器里填写表单即可实时预览并下载 PDF 发票。这类应用的测试难点在于:最终产物是一份动态生成的二进制 PDF——普通的 DOM 断言根本无法校验它的视觉输出。本文以该项目的 e2e 测试套件为例,拆解一套用 Playwright 截图快照测试验证 PDF 输出的完整方案:如何下载 PDF、如何校验文件完整性、如何把它渲染到 canvas 上再与快照基线逐像素比对。
为什么PDF输出测试格外棘手?
在测试"填表 → 生成 PDF → 下载"这条链路时,普通 Web 测试会遇到四个新麻烦:
- PDF 是二进制文件,无法用 CSS 选择器定位页面里的元素,只能靠肉眼或截图比对;
- 渲染引擎不统一:Chromium 与 WebKit 对字体的光栅化结果存在细微差异,跨浏览器直接比对截图会大量误报;
- 内容随时间漂移:发票号默认是"日期+序号"格式,今天跑和明天跑生成的 PDF 完全不同,快照永远对不上;
- 平台字体差异:macOS、Linux 的默认字体与子像素渲染不同,换台机器基线就失效。
easy-invoice-pdf 的 e2e 套件(位于 e2e/)针对这四点分别给出了对策:用 page.clock.setSystemTime() 固定系统时间、统一时区、只在一个浏览器项目上做视觉比对、CI 固定在同一操作系统上运行。下面逐一展开。
测试矩阵配置:一份配置覆盖6种浏览器场景
整个套件由 playwright.config.ts 驱动,配置了 6 个测试项目(project):
| 项目 | 引擎 | 角色 |
|---|---|---|
| Desktop Chrome | Chromium | 主力:全量测试 + 截图快照比对 |
| Desktop Firefox | Firefox | 仅跑 @firefox-smoke 冒烟测试 |
| Desktop Safari | WebKit | 仅跑 @webkit-desktop-smoke 冒烟测试 |
| Mobile Chrome | Chromium | 移动端(Pixel 5 视口)全量测试 |
| Mobile Safari | WebKit | 移动端(iPhone 13 Pro)全量测试 |
几个值得借鉴的细节:
- 固定时区:
timezoneId: "Europe/Warsaw"保证本地机器和 CI 上的日期处理完全一致; - 预置 localStorage:通过
storageState预先写入umami.disabled、sentry.disabled以及"欢迎弹窗已看过"等键值(playwright.config.ts#L42-L70),避免统计脚本和弹窗干扰测试; - 失败自动留痕:
trace: "retain-on-failure"只保留失败用例的 trace,方便回放排查; - 模拟减少动效:
reducedMotion: "reduce"关闭平滑滚动,避免 Safari 上点击位置漂移导致的偶发失败。
Firefox 和 Safari 桌面项目用 grep 标签只挑选引擎敏感的关键路径(客户端生成 PDF + 下载、localStorage 持久化、共享链接往返),而不是跑全量套件——这既覆盖了三引擎,又控制了 CI 时长。
核心流程:expectPdfScreenshot()的4个步骤
整套方案的核心是 e2e/utils/pdf-download.ts 中的 expectPdfScreenshot() 辅助函数(e2e/utils/pdf-download.ts#L178-L257),它把"下载 PDF 并截图比对"收敛成一次调用。任何测试只需:
await expectPdfScreenshot(page, {
downloadDir,
browserName,
name: "downloads-PDF-in-English.png",
notes: "Test: downloads PDF in English",
});
它的内部流程分四步:
- 下载 PDF:定位"Download PDF"按钮(按钮文案随语言变化,用正则同时匹配英文和"Download PDF in X"),通过
waitForEvent("download")捕获下载事件,保存到每个用例独享的临时目录; - 三重完整性校验:检查文件头是否为
%PDF-魔数、末尾 1KB 内是否包含%%EOF标记(说明不是截断的下载)、体积是否大于 1000 字节; - 读取页数:直接从原始 PDF 字节里正则匹配页面树的
/Count N,不渲染也能断言页数; - 渲染 canvas 并快照比对:把 PDF 渲染到
<canvas>上,用 Playwright 的toHaveScreenshot(name)与仓库里保存的基线图逐像素比对。
downloadDir 这个临时目录来自项目自定义的测试 fixture——e2e/utils/extended-playwright-test.ts 在标准 test 基础上扩展了一个 fixture,每个用例开始前 mkdtempSync 创建唯一临时目录、用完后自动删除,下载的 PDF 不会互相污染。
一个容易忽视的细节是 notes 参数:它会把测试标题写进发票表单的备注字段,从而出现在生成的 PDF 里。这样拿到一张失败的截图基线时,光看图就能知道是哪条测试、哪个浏览器项目产生的。
为什么只有Desktop Chrome参与视觉比对?
canvas 上的像素是浏览器自带的光栅化器画出来的——同一个 PDF 在 WebKit 和 Chromium 下画出来的结果就不完全一样。如果 6 个项目都比对截图,比对的就不是应用本身,而是"浏览器光栅化器的差异"。
因此代码里定义了 DEFAULT_SNAPSHOT_PROJECT = "Desktop Chrome":所有项目都执行"下载 + 完整性校验"(这验证了该浏览器/设备能正确生成并下载 PDF),但只有 Desktop Chrome 做视觉快照比对。移动端专属测试则可以用 snapshotProject: ["Mobile Chrome", "Mobile Safari"] 参数指定自己的基线项目。
从PDF到Canvas:可靠截图的关键
把 PDF 变成可截图的画面,用的是 e2e/utils/render-pdf-on-canvas.ts 里的两个函数。做法很巧妙:page.setContent() 注入一个只包含 <canvas> 的空白页面,页面内加载 pdf.js,把下载到的 PDF 字节直接转成 Uint8Array 传给 getDocument(),再以 2 倍缩放渲染到 canvas 上。
为保证跨环境稳定,渲染参数做了三处"确定性"处理:
ctx.imageSmoothingEnabled = false:关闭图像平滑,消除亚像素抗锯齿差异;disableFontFace: true:不让 pdf.js 注册 Web 字体,避免系统字体介入;- 渲染完成后在
window.__PDF_RENDERED__打标记,测试侧用page.waitForFunction等到渲染真正完成再截图,杜绝"截到一半"的竞态。
多页 PDF 也有专门处理:renderMultiPagePdfOnCanvas() 会把所有页面横向拼在一个 canvas 上(页间留 40px 间隔),这样 toHaveScreenshot 一张图就能覆盖整份文档。例如"大量条目生成分页 PDF"测试的基线:
截图后还有一道交叉验证:把 pdf.js 解析出的页数,与之前从原始字节读到的 /Count 对比,两边必须一致——防止"页树写的是 3 页、实际只渲染了 2 页"这类隐蔽 bug。
测试覆盖:两种模板×14种语言
easy-invoice-pdf 提供 default 和 Stripe 两种 PDF 模板。测试组织上避免了"复制粘贴两份测试":
- e2e/invoice-templates-common/shared-template-features.test.ts:两个模板行为一致的功能(QR 码显示/隐藏、服务周期、邮箱显隐、超大金额换行、多页生成)写成一份测试,通过
for (const template of TEMPLATES)循环在两种模板下各跑一遍,每种模板用自己的条目数据验证各自版式; - e2e/invoice-templates-common/template-languages.test.ts:遍历全部 14 种 PDF 语言,每种语言搭配一种该语言地区常用的货币(如波兰语+PLN、法语+CHF、日语零小数位),语言×货币×模板组合逐一生成 PDF 快照,顺带覆盖了货币符号位置、千位分隔符、数字格式化的本地化;
- e2e/default-invoice-template/default-invoice-template.test.ts 与 e2e/stripe-invoice-template/stripe-invoice-template.test.ts:各模板的专属行为(如切到 Stripe 模板时日期格式自动切换、发票号标签迁移);
- e2e/server-render-pdf/server-render-pdf.test.ts:服务端 PDF 管线。用
spawnSync起子进程调用与/api/generate-invoice相同的服务端渲染函数(因为 Playwright 的 JSX 转换与 @react-pdf 不兼容),拿到原始字节后先验%PDF-头,再复用同一套 canvas 渲染流程做快照;同时覆盖预览 API 的鉴权(无 token 返回 401)与返回的 Content-Type。
本地运行与快照基线维护
本地跑测试只需两条命令(见 package.json 的 scripts):
pnpm e2e:运行全量 e2e(Playwright 以 line reporter 输出);pnpm e2e:update-snapshots:等价于playwright test --update-snapshots,确认新的渲染结果是预期内的改动后,用它批量更新基线图。
配合 page.clock.setSystemTime(new Date("2025-12-17T00:00:00Z")) 固定系统时间,发票号、日期全部锁定,基线图只在"产品真的变了"时才需要更新。
CI 侧(.github/workflows/e2e.yml)有两个关键决定:
- 固定在
macos-15上运行:因为快照基线是在 macOS 上生成的,CI 必须在同一 OS 家族上光栅化才能匹配;不用macos-latest是因为镜像升级会让基线无声失效且无法追溯; - 跑在真实的预览部署上:工作流由
deployment_status事件触发,BASE_URL指向 Vercel preview 环境,测试验证的是用户实际会访问的版本,而不是本地 dev server。测试完成后邮件附上 HTML 测试报告,失败时手动将 workflow 标记为失败。
总结:方案可复用的5个要点
- 把"PDF 完整性"与"视觉正确性"拆开:文件头/尾/体积校验在所有浏览器上跑,像素比对只固定一个项目,两全其美;
- canvas 渲染替代直接截图:经 pdf.js 统一光栅化后,比对对象是文档内容而不是浏览器渲染差异;
- 确定性地消除一切漂移源:固定系统时间(clock API)、固定时区、预置 localStorage、关闭图像平滑;
- 下载类测试用隔离的临时目录 fixture,用完即删;
- 把辅助函数沉淀到 utils(
expectPdfScreenshot、waitForPdfRegeneration),业务测试只剩"填什么数据、断言什么"两件事,可读性接近纯业务描述。
这套"下载 → 校验 → 渲染 → 快照"的流水线同样适用于任何"浏览器里生成文档"的场景:PDF、图片导出、Excel 报告,都可以照此改造。




