Playwright 截图比对中的 SSIM 陷阱：julia-ssim-trap 夹具如何守护像素级差异判定

一张纯白图片与一张肉眼可辨的浅灰图片，某些基于 SSIM（结构相似度）的算法会判定它们"完全相同"。这个反直觉的现象正是 Playwright 在 tests/image_tools/fixtures/should-fail/julia-ssim-trap/README.md 中用一组名为 julia-ssim-trap 的测试夹具记录下来的"陷阱"（trap）：它用于验证仓库的像素比对管线不会掉进 SSIM 类算法的坑，并作为 must-fail 用例持续守护 toHaveScreenshot 这类截图断言所依赖的差异判定逻辑。阅读本文后，你将理解 Playwright 图像比对的三级判定管线（可感知色差 → 邻域方差 → 结构相似度抗锯齿豁免）、SSIM 的数学盲区，以及 fixtures 测试骨架如何把这类边界用例固化为回归防线。

SSIM 陷阱：白色与灰色被判"相等"的由来

夹具本身长什么样

julia-ssim-trap 夹具只有三个文件：

• 1-actual.png（20×20 纯白）
• 1-expected.png（20×20 近白灰）
• README.md（陷阱说明）

README 原文核心只有三句话：SSIM 是用于图像相似度比较的指标；原始 SSIM 针对亮度通道（灰度）计算，而 Julia 语言生态的 ImageQualityIndexes.jl 实现会把各颜色通道的 SSIM 做加权组合（对应其 ssim.jl 第 39–41 行）；这份样例"一张白图和一张灰图"会被 Julia SSIM 报告为相等，从而一网打尽 dsp.stackexchange 上关于"如何对 RGB 图像施加 SSIM"的各种彩色加权建议。

对夹具 PNG 做像素级解码可以核实内容：1-actual.png 全部像素为 (255, 255, 255, 255)，1-expected.png 全部像素为 (247, 248, 250, 255)。两图结构完全相同（都是无纹理的纯色块），唯一差别是整体亮度有约 5–8 的均匀偏移——这正是 SSIM 这类"结构相似度"指标最不敏感的变化类型。

为什么 SSIM 类算法会"翻车"

标准 SSIM 在一个窗口内由三项乘积构成：亮度项、对比度项与结构项。在 packages/utils/image_tools/stats.ts 中，Playwright 对 SSIM 的实现是：

ssim = (2·μx·μy + C1)·(2·cov + C2) / (μx² + μy² + C1) / (σx² + σy² + C2)

其中 C1 = (0.01 · L)²、C2 = (0.03 · L)²，L = 2^8 − 1 = 255 是 8 位色深下的动态范围（stats.ts#L34），因此 C1 ≈ 6.50、C2 ≈ 58.52。对两张都是常数色的图像，σx² = σy² = cov = 0，SSIM 退化为纯亮度项：

SSIM ≈ (2·μx·μy + C1) / (μx² + μy² + C1)

代入白 (255,255,255) 与灰 (247,248,250) 逐通道计算：R 通道约 0.99949，G 通道约 0.99961，B 通道约 0.99980；若先转成亮度（rgb2gray 为 (77·R+150·G+29·B+128)>>8，见 colorUtils.ts#L21-L25，灰图亮度约 248），亮度通道 SSIM 同样约 0.99961。无论按 Julia 那种各通道加权平均，还是按"先转灰度再算 SSIM"的建议，结果都落在 0.9995 以上，远超常见的 0.99 相似度阈值——于是被误判为"相同"。均匀亮度偏移不改变结构、又在亮度项中被 C1 常数"稀释"，这就是该陷阱的数学根源：只要把 SSIM 值简单地与阈值比较，就会漏报这种肉眼可见的整体色偏。

Playwright 的三级像素判定管线

Playwright 的底层比对实现在 packages/utils/image_tools/compare.ts 的 compare() 函数（compare.ts#L36-L122）。它并非"直接算 SSIM 然后对阈值"，而是按像素逐级过滤，julia-ssim-trap 之所以放在 should-fail 目录，正是因为整条管线根本不会走到 SSIM 那一步就能给出"有差异"的结论。

第一级：完全相同像素的快路径与 CIE94 可感知色差

比对的每一对像素先做快速相等判断，完全相等则跳过（compare.ts#L71-L75）；不相等时，用 CIE94 色差公式计算感知差异：

• CIE94 在 Lab 色彩空间上进行（sRGB → XYZ → Lab，对应 colorUtils.ts 中的 srgb2xyz 与 xyz2lab），代码采用"图形艺术"用途的加权系数 k1=0.045, k2=0.015（colorUtils.ts#L38-L62）；
• 按注释约定（colorUtils.ts#L30-L37），dE94 值以 1.0 为"恰好可察觉差异"（just-noticeable difference）——小于 1.0 人眼不可辨，可忽略；1–2 需凑近观察；2–10 一眼可见。

fixtures 测试调用时传入 maxColorDeltaE94: 1.0（见下文测试骨架）。若 dE94 ≤ 1.0，该像素视为视觉等价，绘制为灰色并跳过。而白 (255,255,255) 对灰 (247,248,250) 的色差超过 1.0（人眼可察觉的整体色偏），于是进入下一级判定。

第二级：3×3 邻域方差——"抗锯齿豁免"的资格预审

抗锯齿像素长什么样？它是前景与背景在边缘处的均匀混合，因此在它周围必然存在结构变化。反过来，如果一个异常像素周围 3×3 邻域里两张图之一完全是"纯色、零方差"，那它绝不可能是抗锯齿像素，只能是真实差异。这就是 compare.ts#L96-L106 的逻辑：以 VARIANCE_WINDOW_RADIUS = 1（即 3×3 窗口，compare.ts#L22）分别统计 actual 与 expected 的 RGB 三通道方差和 var1、var2，只要有一方为 0，直接判定为真实差异——标红、diffCount 自增。

julia-ssim-trap 的白/灰两张图都是无纹理纯色块，任意 3×3 邻域方差恒为 0，因此在第二级就被红色标记并计入差异计数，SSIM 根本没有机会把它们"豁免"掉。

第三级：31×31 窗口 SSIM 抗锯齿判定

只有当像素在 CIE94 层面确有差异、且双方邻域都有纹理（方差都非 0）时，才轮到 SSIM 出场判断"这是不是抗锯齿边缘"。代码取 SSIM_WINDOW_RADIUS = 15（31×31 窗口，compare.ts#L21），对 RGB 三通道分别计算 SSIM 后取平均（compare.ts#L108-L111）：

ssimRGB = (ssim(R) + ssim(G) + ssim(B)) / 3 ≥ 0.99 → 视为抗锯齿（标黄，不计 diff）
否则 → 真实差异（标红，diffCount++）

注意这里的角色与"Julia SSIM 判相似"完全不同：SSIM 只被用作抗锯齿豁免的充分条件，其豁免范围又被前两级（可感知色差 + 邻域有结构）严格约束。一个均匀灰阶整体偏移永远不会满足"邻域有结构"这一前置条件，因而无法被豁免。逐像素的差异计数 diffCount 最终由上层断言判断是否为 0（决定 pass/fail），这也正是 packages/utils/image_tools 这套工具能够同时做到"放过抗锯齿、又不放过色偏"的关键设计。

边界处理的工程细节

• 差异图的三种染色：等价像素画灰（用 rgb2gray 后以 10% 比例混合白色淡化）、真实差异画红、抗锯齿画黄（compare.ts#L55-L62），方便人眼直接审阅差异图；
• 积分图加速：SSIM 需要在每个候选像素上反复求窗口均值/方差/协方差，stats.ts 的 FastStats 在构造时为两幅图预计算 5 张前缀和（通道值、平方值、两图乘积，stats.ts#L47-L88），把任意矩形窗口统计降到 O(1)；
• 越界填充的"双色陷阱"：为了不把边界外当常数区（否则会导致边界被误判为"零方差真实差异"），ImageChannel.intoRGB 在图像四周按奇偶行交替填充洋红 (255,0,255) 与绿 (0,255,0) 作为 padding（compare.ts#L41-L53），统计时再通过 boundXY 裁剪窗口并回填坐标。

fixtures 骨架：把边界用例固化成回归测试

packages/utils/image_tools 的比对函数由 tests/image_tools/fixtures.spec.ts 用图像夹具统一驱动：

1. 目录即契约：遍历 tests/image_tools/fixtures 下所有以 -actual.png 结尾的文件（fixtures.spec.ts#L25-L34），每个夹具自动生成一条用例；should-match/ 下期望 diffCount === 0，should-fail/（julia-ssim-trap 所在地）期望 diffCount ≠ 0（fixtures.spec.ts#L67-L80）；
2. 比对参数固定：所有夹具统一使用 maxColorDeltaE94: 1.0，与上层截图断言保持一致（fixtures.spec.ts#L58-L60）；
3. 过程可见：每个用例把 actual / expected / diff 三张 PNG 通过 testInfo.attach 附加到报告（fixtures.spec.ts#L44-L65），失败时可直观查看红/黄/灰染色；
4. 可扩展：should-match 与 should-fail 都支持并行，并可通过环境变量 IMAGE_TOOLS_FIXTURES 指向自定义夹具目录跑额外验证（fixtures.spec.ts#L83-L92）。

对 julia-ssim-trap 而言，测试期望是：compare() 对"纯白 vs 近白灰"返回非零 diffCount。若未来某次重构把比对退化成"纯 SSIM 阈值法"，这条用例会立刻变红，从而在 CI 上拦截 Julia SSIM 所代表的这类误判。

配套的单元测试还提供了更强的交叉验证手段：tests/image_tools/unit.spec.ts 配合 tests/image_tools/utils.ts 中的工具函数，可生成随机种子图像、把图像降为灰度通道，并与参考实现（如 SSIM.js 的原始公式）对齐校验——其中 grayChannel 特意不包含 alpha，并在注释里注明是为了与原始 SSIM 实现做精确对比（utils.ts#L49-L63），可见仓库对"度量语义一致性"的重视。

从陷阱到设计原则：给截图比对工具的三条启示

1. 结构化指标不能替代感知色差：SSIM 度量的是亮度/对比度/结构的一致性，对均匀色偏天然不敏感；把比较建立在 Lab 色彩空间 + CIE94 这类"以人眼恰好可察觉为 1.0"的指标上，才与视觉断言的目标一致。
2. 豁免必须有前置资格：抗锯齿豁免（SSIM ≥ 0.99）只在"两图邻域都有纹理结构、且像素色差确实可感知"时才授予。julia-ssim-trap 的白/灰色块正是因为没有纹理，永远走不到豁免环节。
3. 用"反例夹具"固化认知边界：README 的存在价值不在篇幅，而在于把"外部算法会踩、我们的实现不能踩"的边界写进测试资产——每个 should-fail 夹具都是比对管线行为契约的一部分。

需要复现或验证时，可在构建产物就绪后运行 tests/image_tools/fixtures.spec.ts（should-fail 分组即包含 julia-ssim-trap），或在本地自定义 should-match / should-fail 目录并通过 IMAGE_TOOLS_FIXTURES 环境变量注入更多边界用例，观察 compare() 返回的差异计数与红/黄/灰差异图是否符合直觉。