EasyInvoicePDF测试实践:用Playwright截图快照测试PDF输出的完整方案

原创2026-10-14 18:02:321,151 阅读

EasyInvoicePDF测试实践:用Playwright截图快照测试PDF输出的完整方案

easy-invoice-pdf 是一个免费的开源发票生成器,用户在浏览器里填写表单即可实时预览并下载 PDF 发票。这类应用的测试难点在于:最终产物是一份动态生成的二进制 PDF——普通的 DOM 断言根本无法校验它的视觉输出。本文以该项目的 e2e 测试套件为例,拆解一套用 Playwright 截图快照测试验证 PDF 输出的完整方案:如何下载 PDF、如何校验文件完整性、如何把它渲染到 canvas 上再与快照基线逐像素比对。

EasyInvoicePDF发票生成器实时PDF预览演示

为什么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",
});

它的内部流程分四步:

  1. 下载 PDF:定位"Download PDF"按钮(按钮文案随语言变化,用正则同时匹配英文和"Download PDF in X"),通过 waitForEvent("download") 捕获下载事件,保存到每个用例独享的临时目录;
  2. 三重完整性校验:检查文件头是否为 %PDF- 魔数、末尾 1KB 内是否包含 %%EOF 标记(说明不是截断的下载)、体积是否大于 1000 字节;
  3. 读取页数:直接从原始 PDF 字节里正则匹配页面树的 /Count N,不渲染也能断言页数;
  4. 渲染 canvas 并快照比对:把 PDF 渲染到 <canvas> 上,用 Playwright 的 toHaveScreenshot(name) 与仓库里保存的基线图逐像素比对。

EasyInvoicePDF一键下载PDF发票流程演示

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测试生成的横向拼接快照基线

截图后还有一道交叉验证:把 pdf.js 解析出的页数,与之前从原始字节读到的 /Count 对比,两边必须一致——防止"页树写的是 3 页、实际只渲染了 2 页"这类隐蔽 bug。

测试覆盖:两种模板×14种语言

easy-invoice-pdf 提供 default 和 Stripe 两种 PDF 模板。测试组织上避免了"复制粘贴两份测试":

EasyInvoicePDF默认模板与Stripe模板界面及PDF预览

Stripe风格发票模板测试快照

本地运行与快照基线维护

本地跑测试只需两条命令(见 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)有两个关键决定:

  1. 固定在 macos-15 上运行:因为快照基线是在 macOS 上生成的,CI 必须在同一 OS 家族上光栅化才能匹配;不用 macos-latest 是因为镜像升级会让基线无声失效且无法追溯;
  2. 跑在真实的预览部署上:工作流由 deployment_status 事件触发,BASE_URL 指向 Vercel preview 环境,测试验证的是用户实际会访问的版本,而不是本地 dev server。测试完成后邮件附上 HTML 测试报告,失败时手动将 workflow 标记为失败。

总结:方案可复用的5个要点

  • 把"PDF 完整性"与"视觉正确性"拆开:文件头/尾/体积校验在所有浏览器上跑,像素比对只固定一个项目,两全其美;
  • canvas 渲染替代直接截图:经 pdf.js 统一光栅化后,比对对象是文档内容而不是浏览器渲染差异;
  • 确定性地消除一切漂移源:固定系统时间(clock API)、固定时区、预置 localStorage、关闭图像平滑;
  • 下载类测试用隔离的临时目录 fixture,用完即删;
  • 把辅助函数沉淀到 utils(expectPdfScreenshot、waitForPdfRegeneration),业务测试只剩"填什么数据、断言什么"两件事,可读性接近纯业务描述。

这套"下载 → 校验 → 渲染 → 快照"的流水线同样适用于任何"浏览器里生成文档"的场景:PDF、图片导出、Excel 报告,都可以照此改造。

登录后查看全文
easy-invoice-pdf