返回资讯中心
外部精选
软件工程
#开发者实时流

Test2Doc 新增 maxDiffPixelRatio 选项,跳过未真正变化的截图重写

来源标题:Stop Committing Screenshot Noise

Test2Doc 的 @test2doc/playwright 和 @test2doc/maestro 新增 maxDiffPixelRatio 选项,截图未真正变化时不再重写文件,避免 PR 中出现大量无法审阅的二进制 diff。作者用 Schedulelord 项目的三次提交验证,共 719 张截图被修改,其中四分之三的文件像素差异不超过 1%,部分甚至没有任何像素差异,仅是 PNG 字节不同。

Hacker News 最新speckx2026/11/22 · 今天11 分钟阅读

以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。

每次重新生成文档时,Test2Doc 都会把所有截图重新拍一遍。大多数截图看起来和上次完全一样。但“看起来一样”和“字节完全相同”是两回事,所以下一次提交就会重写数百张 PNG,你的 pull request 也就变成了一堵没人能审阅的二进制 diff 之墙。

@test2doc/playwright 和 @test2doc/maestro 现在都能在截图并未真正变化时跳过重写。这个选项叫 maxDiffPixelRatio。

我有一个排班应用叫 Schedulelord,它的指南由 Test2Doc 生成,每张截图都有固定的文件名。我时不时会全部重新生成并提交结果。我回头翻查了其中三次“重新生成指南”的提交,把每张被修改的截图与上一版逐像素对比。

这三次提交总共修改了 719 张截图:

这些提交中四分之三的文件像素差异不超过 1%。有些文件在 pixelmatch 看来根本没有差异像素,只是 PNG 文件的字节不同。

下面就是其中一张,来自新班次通知指南的通知页面。第一张图是重新生成之前的,第二张是之后的。我就不麻烦你玩找不同了。

我把两张图都跑了一遍 pixelmatch(也就是 Test2Doc 现在用的同一个库),并把差异像素用红色画在截图的淡化副本上:

那个红点只是通知上的时间戳,没有别的。放大来看,上面是旧图,中间是新图,下面是差异:

921,600 个像素中有 210 个不同,占图像的 0.023%。这张截图记录的是班次创建后出现的通知。看指南的人根本不在乎通知是几点出现的,但 git 看到的是一个 140KB 的新二进制文件。

在 reporter 上设置 maxDiffPixelRatio。它是允许存在差异的像素比例,取值 0 到 1,超过这个比例截图才算真正变化:

reporter: [ "@test2doc/playwright", outputDir: "./doc/docs", maxDiffPixelRatio: 0.001, // 0.1% of the pixels

下面是 Test2Doc 即将写入截图时发生的事:

不设这个选项,什么都不会变。任何差异都会替换文件,和以前一样。

同一次重新生成的提交里还有一张周历截图,页面内容确实变了:

那里有 30% 的像素不同,远远超过任何合理的阈值。它被替换了,新截图也出现在 diff 里,这才是它该待的地方。

对我的截图来说,各个阈值会保留旧版本的情况如下:

从低开始。这是个权衡。真实但很小的变化,比如改正一个词或改动一个价格,可能落在阈值以下被忽略,你的文档就会继续显示旧内容。上面的时间戳跳过无所谓,表格里的错误数字可不行。在 1280×720 截图的 0.1% 阈值下,你会跳过约 900 个像素的变化,大致相当于上面那种时间戳的四个数字。1% 的话,大约是 9,000 个像素。

  • takeScreenshot: path: login-screen label: 'Login [test2doc_annotation]:{"filename":"login-screen"}'

test2doc-maestro.config.json "maxDiffPixelRatio": 0.001

当一个流程在多个平台上运行时,平台名会加到文件名里,所以你会得到 login-screen-android.png 和 login-screen-web.png,每个平台都与自己的文件比较。

我不信任用自己编造的截图做的截图测试。手工拼一张图来证明任何我想证明的东西都太容易了,所以 Playwright reporter 的测试会像你的配置一样运行一个真实的 playwright 测试。它在 Chromium 里先拍一张基准截图,然后在一个 10×10 徽章上改个颜色(微小变化)后再拍一张,再改行距让页面重排(大变化)后拍一张。在检查磁盘内容之前,它会先测量有多少像素不同,这样无效或过大的改动就没法让测试以错误的理由通过。

这个检查在 CI 里抓到了我的问题。我的行距改动在 Mac 上移动了 1.08% 的像素,但在 Linux 容器里只有 0.83%,因为字体不同。我设的 1% 阈值正好卡在边缘。现在测试用 0.1%,距离两种变化都有大约八到九倍的余量,字体差异就不影响了。如果你要选阈值,也给它留出这样的余量。

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →