屏幕尺寸不匹配致截图对比失败的排查与解决问询

问题描述 #

我需要对约100个页面做截图验证，更新基线后对比时，约60%的页面因尺寸不匹配失败，报错示例：

Expected an image 1366px by 783px, received 1349 by 783px. 3242 pixels (ratio 0.01 of all image pixels) are different

不同页面的预期与实际尺寸差异各不相同。

我已经尝试在配置及测试中明确设置viewport尺寸，还是存在细微差异；把viewport设为null并移除配置中的设备项，结果依旧。

疑问 #

• 设置大尺寸viewport后，为何部分页面仍失败？
• 如何强制基线截图与测试截图尺寸一致？
• 是否每个页面需单独设置预期尺寸？
• 有头测试中光标位置是否影响结果？

测试代码 #

test('Compare', async({page})=>{
await page.goto(url);
await expect.soft(page).toHaveScreenshot('url.png',{fullPage:true,mask:[page.locator('tbody'),page.getByTitle(/...ResetPassword.../),page.getByLabel('Label1'),page.getByText(/Version[0-9]/)]});
}

解决方案与疑问解答 #

1. 为啥设了大viewport还是失败？ #

大概率是这几个原因：

• 页面存在动态元素：比如自适应侧边栏、加载中的内容、弹窗，渲染时会微调布局，导致实际截图尺寸和预期有偏差；
• 浏览器滚动条差异：不同环境（本地有头/CI无头）的滚动条宽度不一样，会挤占页面宽度；
• 页面加载不完整：page.goto之后直接截图，可能部分异步内容还没渲染完，导致页面高度/宽度计算不准；
• 渲染引擎差异：本地浏览器和CI环境的浏览器版本、渲染参数不一致，也会出现细微布局偏差。

2. 强制基线和测试截图尺寸一致的方法 #

• 统一固定窗口+viewport尺寸：测试前同时设置浏览器窗口和viewport，确保两端完全一致：

  await page.setViewportSize({ width: 1920, height: 1080 });
  await page.setWindowSize({ width: 1920, height: 1080 });
  

  同时在Playwright配置文件里也统一设置：

  use: {
    viewport: { width: 1920, height: 1080 },
    // 禁用默认设备模拟
    device: null,
  }
  

• 隐藏滚动条：通过注入CSS消除滚动条宽度差异：

  await page.addStyleTag({ content: `
    ::-webkit-scrollbar { display: none; }
    html { scrollbar-width: none; }
  ` });
  

• 等待页面完全稳定：截图前等待页面加载完成，比如加await page.waitForLoadState('networkidle')，或者等待关键元素渲染完毕：

  await page.goto(url);
  await page.waitForLoadState('networkidle');
  // 额外等待动态元素加载
  await page.locator('.dynamic-content').waitFor();
  

• 统一截图环境：生成基线和执行测试时，用完全相同的浏览器版本、环境（比如都用无头Chrome），避免渲染差异。

3. 是否需要每个页面单独设置预期尺寸？ #

不需要，除非个别页面有特殊固定布局要求。尽量统一用一个标准尺寸，只要基线和测试的配置、环境完全一致，就能避免尺寸不匹配问题。如果少数页面确实存在自适应异常，再单独给这些页面加专属的viewport设置，减少维护成本。

4. 有头测试中光标位置是否影响结果？ #

会影响！如果光标停留在可交互元素上（比如按钮、输入框），元素会触发hover样式（变色、边框加粗等），导致截图和基线不一致；另外光标本身如果在可视区域内，也会被截进图里。

解决方法：截图前把光标移到页面可视区域外：

await page.mouse.move(-100, -100);

内容的提问来源于stack exchange，提问作者jmaschle