自动化测试 / 系统课时
执行视觉回归测试
执行视觉回归测试
本课解决页面样式变化难以及时发现的问题。你将使用 Playwright 的基准截图能力,对当前页面与历史版本进行自动比较,并掌握基准更新、差异检查和减少误报的方法,让布局或样式回归能够被测试及时发现。
学习目标
- 理解视觉回归测试的工作方式及适用范围。
- 掌握
toHaveScreenshot()图片断言的基本写法与验证方法。 - 了解更新基准截图的方法,以及如何减少动态内容造成的误报。
视觉回归测试原理
视觉测试会保存一份基准图片,测试运行时重新截图,并比较两者差异。如果差异超过允许范围,测试会失败。
它适合检查布局、颜色、字体、间距和组件状态变化,但不适合直接比较包含大量随机内容、实时时间或持续变化动画的页面区域。
Playwright 的 toHaveScreenshot() 会等待连续两次截图结果一致,再将当前截图与基准比较。比较时可以设置允许的差异像素数,避免少量无关的像素波动导致失败。

首次执行时,如果基准截图不存在,Playwright 默认会生成基准文件,同时将该测试标记为失败,提示缺少预期快照。再次运行才会与已生成的基准进行正式比较。
基准文件通常保存在测试文件旁的快照目录中,具体名称可能包含浏览器项目和操作系统信息。基准应纳入版本管理,方便检查设计变更。
使用 Playwright 图片断言
在已经安装 @playwright/test 和浏览器运行环境的项目中,创建 tests/visual.spec.ts。下面使用 https://example.com 作为测试页面,并固定视口尺寸,减少响应式布局变化对截图的影响。
import { test, expect } from '@playwright/test';
test('visual regression', async ({ page }) => {
// 固定视口,避免不同窗口尺寸触发不同的响应式布局。
await page.setViewportSize({ width: 1280, height: 720 });
await page.goto('https://example.com');
// 与 home.png 基准比较,允许最多 100 个差异像素。
await expect(page).toHaveScreenshot('home.png', {
maxDiffPixels: 100,
});
});toHaveScreenshot('home.png') 表示使用名为 home.png 的截图基准。maxDiffPixels: 100 允许最多100个像素存在可识别差异,并不表示允许100个像素的位移距离。默认的像素差异判定还受到颜色差异阈值影响。
在项目根目录运行:
npx playwright test tests/visual.spec.ts预期结果(示意,实际运行时间和项目数量可能不同):
首次运行:缺少基准截图,创建快照并报告测试失败。
再次运行:当前截图与基准在允许范围内一致,测试通过。
页面出现超出容差的变化:测试失败,生成差异对比产物。首次运行后,再执行一次同样的命令。如果页面和运行环境保持一致,截图断言应当通过。可在测试报告或失败产物中查看预期截图、实际截图和差异图,确认变化发生的位置。
更新基准截图
当页面经过确认的设计变更后,可以重新生成截图基准。比如设计人员将首页标题字体从16px调整为20px,原有基准可能不再符合新的界面要求。
在更新之前,应先查看差异图,确认变化确实符合设计要求,而不是 CSS 错误、资源加载失败或浏览器环境异常造成的。
npx playwright test tests/visual.spec.ts --update-snapshots预期结果:
执行视觉测试并更新与当前页面不匹配的基准截图。
更新后的截图保存到对应快照目录。更新完成后,不带更新参数再次运行:
npx playwright test tests/visual.spec.ts预期结果:
当前截图与新基准匹配,视觉测试通过。检查版本控制中的基准图片变更,确认只有预期的视觉区域发生改变,再将更新后的截图与测试代码一起提交。不要在每次测试失败时自动执行更新命令,否则真实的样式回归可能被直接写入新基准。
减少误报与检查边界
同一页面在不同操作系统、浏览器版本、字体环境或设备缩放设置下,可能产生不同的渲染结果。基准截图最好在与持续集成环境一致的浏览器和操作系统中生成,并固定视口、测试数据与字体资源。
对于动态时间、随机推荐或广告区域,应优先使用固定测试数据,或仅对稳定组件执行 locator.toHaveScreenshot()。无法固定且不属于测试目标的区域,可以通过 mask 参数进行遮罩,但不要遮住真正需要验证的内容。
视觉断言默认会禁用动画并隐藏文本光标,但仍需确保异步内容已经加载到预期状态。遇到差异时,先检查页面是否稳定,再查看差异图定位问题,不应直接无限增大 maxDiffPixels 来消除失败。
可以通过一次受控修改验证测试是否真正有效:在建立基准后,临时改变被测页面的标题字号或容器间距,运行测试并确认差异超过阈值时报告失败;随后恢复样式,再次运行应恢复通过。若修改发生在允许容差内,则需要扩大测试变化或收紧容差后重新检查。
视觉回归测试用于发现画面变化,不能代替功能和交互断言。只有在页面状态可重复、运行环境一致且基准经过人工确认时,截图比较才具有可靠的回归检测价值。