周五晚上,您合并了页眉的改版。周一早上,同事告诉您,价格页上的登录按钮偏移了几个像素:而这个页面您根本没碰过。没有任何测试发出警报,因为没有任何测试在检查外观。视觉测试填补的正是这个空白。
微软的 Playwright 自 1.22 版本起内置了视觉测试功能:toHaveScreenshot() 方法。它可以捕获截图并自动与参考图像比对,无需外部插件。这是一个完全免费的方案:想了解其他免费视觉测试工具,请查看我们的对比。
对于想在现有测试套件中添加视觉测试的团队,这是最可靠的选择之一。要了解视觉回归的基础知识,请参阅我们的完整指南。本指南涵盖安装、配置、最佳实践和 CI/CD 集成,然后介绍 Delta-QA 的 Vision SDK 在这些测试中带来的变化。
一页读懂:无代码工具到底自动化了什么,以及它的对比情况:无代码测试自动化。
toHaveScreenshot() 仍然要求您编写和维护代码? Delta-QA 无需写一行代码即可捕获并比对您的页面,无需绑定银行卡。免费使用 Delta-QA →
安装与第一个测试
如果您已有 Node.js 项目,配置很快:
npm install -D @playwright/test
npx playwright install
然后在 tests/visual.spec.ts 中创建您的第一个视觉测试:
import { test, expect } from '@playwright/test';
test('homepage visual test', async ({ page }) => {
await page.goto('https://your-site.com');
await expect(page).toHaveScreenshot('homepage.png');
});
第一次运行会生成基线(baseline,即参考图像)。之后的运行会把当时的截图与该基线比对,并报告差异。
# Première fois : générer les baselines
npx playwright test --update-snapshots
# Ensuite : comparer
npx playwright test
起步就是这么简单。复杂性出现在真实的场景中。
配置容差
默认情况下,Playwright 会报告哪怕一个像素的差异。实际使用中,需要配置容差阈值以避免误报。
在 playwright.config.ts 中:
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
toHaveScreenshot: {
maxDiffPixelRatio: 0.01, // 1 % de pixels différents toléré
animations: 'disabled', // désactive les animations CSS
scale: 'device', // tient compte des écrans Retina
},
},
});
您也可以逐个测试进行调整:
// Page statique : seuil strict
await expect(page).toHaveScreenshot('landing.png', {
maxDiffPixelRatio: 0.001
});
// Tableau de bord avec graphiques : seuil plus souple
await expect(page).toHaveScreenshot('dashboard.png', {
maxDiffPixelRatio: 0.05,
mask: [page.locator('.chart')]
});
阈值是一种折中:太低,哪怕极小的渲染差异也会让测试失败;太高,边距从 16px 变成 12px 这样的改动就会悄悄溜过而不被发现。
处理动态内容
动态内容(日期、广告、头像、计数器)是视觉测试的噩梦。Playwright 提供三种解决办法:
遮盖动态区域,这是最常见的方法:
await expect(page).toHaveScreenshot({
mask: [
page.locator('.ad-banner'),
page.locator('.timestamp'),
page.locator('.user-avatar')
]
});
替换内容以固定数值:
await page.evaluate(() => {
document.querySelector('.date').textContent = '01/01/2026';
});
await expect(page).toHaveScreenshot();
用 CSS 隐藏完全不应出现的元素:
await page.addStyleTag({
content: '.dynamic-element { visibility: hidden !important; }'
});
await expect(page).toHaveScreenshot();
这些办法都需要手动维护:页面上每多一个动态区块,就要多加一个选择器。
稳定测试
一个今天通过、明天无故失败的视觉测试是无法使用的。下面是保证稳定性的方法:
test('stable visual test', async ({ page }) => {
await page.goto('https://your-site.com');
// Attendre que le réseau soit calme
await page.waitForLoadState('networkidle');
// Attendre le chargement des polices
await page.evaluate(() => document.fonts.ready);
// Attendre un élément critique
await page.waitForSelector('.hero-image', { state: 'visible' });
await expect(page).toHaveScreenshot();
});
当全局选项不够用时,手动禁用动画:
await page.addStyleTag({
content: `
*, *::before, *::after {
animation-duration: 0s !important;
transition-duration: 0s !important;
}
`
});
测试多种分辨率
Playwright 通过项目(projects)让多分辨率测试变得简单:
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'Desktop',
use: { viewport: { width: 1920, height: 1080 } },
},
{
name: 'Tablet',
use: { viewport: { width: 768, height: 1024 } },
},
{
name: 'Mobile',
use: { ...devices['iPhone 13'] },
},
],
});
每个项目生成各自的基线。因此一个测试会在三种分辨率下运行三次,需要维护三套截图。
CI/CD 集成
集成到 GitHub Actions 很直接。完整配置请参阅我们的 GitHub Actions 回归测试指南,GitLab 方面则参阅 GitLab CI 视觉测试指南。
name: Visual Tests
on: [push, pull_request]
jobs:
visual-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
- uses: actions/upload-artifact@v4
if: failure()
with:
name: playwright-report
path: playwright-report/
测试失败时,Playwright 会生成三张图像:基线(预期)、当时的截图,以及用红色标出差异的 diff 图。HTML 报告(npx playwright show-report)会将它们并排显示。
注意事项:字体渲染因系统而异。在 Mac 上生成的基线与 CI 的 Linux runner 上截取的图像不会一致。请在 CI 中生成基线,或使用 Playwright 官方 Docker 镜像。
toHaveScreenshot() 还要您编写代码吗? Delta-QA 以无代码方式捕获并比对您的页面,无需绑定银行卡。免费使用 Delta-QA →
Playwright 方式的局限
Playwright 非常适合自己编写测试的团队,但 toHaveScreenshot() 有一些必须了解的局限:
必备技能:需要掌握 TypeScript/JavaScript、选择器和项目配置。不写代码的 QA 既无法创建也无法维护这些测试。
没有评审界面:没有用于判定差异的共享空间。基线的管理通过终端和文件系统完成。在团队中,这很快就会变得复杂。
像素比对:diff 显示的是一块红色区域,而不是具体变化了什么。浏览器之间的抗锯齿差异、操作系统之间的字体渲染差异:这一切都会产生噪音,必须用遮罩和阈值手动处理。
维护:每一次有意的界面变更,都需要重新生成基线(--update-snapshots)。在一个有 200 个视觉测试和 3 个浏览器的项目中,就有 600 张基线需要管理,并被纳入仓库的版本控制。我们关于基线管理的指南详细介绍了维护它们的策略。
保留 Playwright,更换比对方式:Vision SDK
如果您的 Playwright 测试已经存在,就无需放弃它们来消除其中一部分局限。Delta-QA 的 Vision SDK(@delta-qa/vision)会在测试需要查看页面的地方添加一次 Delta-QA 验证:
import { test } from "@delta-qa/vision/fixture";
test("Checkout", async ({ page, vision }) => {
const checkout = await vision.open(page, { id: "checkout", name: "Checkout" });
await page.goto("https://shop.example.com/checkout");
await checkout.check("Payment");
}); // 由 fixture 关闭:未经判定的差异会让测试失败
SDK 从变量 DELTAQA_API_KEY 读取 API 密钥。不使用 fixture 时,@delta-qa/vision 的 open(page, { … }) 打开同样的测试,并在 afterEach 中用 close() 关闭它。
与 toHaveScreenshot() 相比的变化:
- 报告会指出发生变化的元素。 不是一块需要自己解读的红色区域:报告会告诉您哪个元素发生了变化,例如"支付"按钮从蓝色变成了绿色。
- 参考不再存放在仓库中。 首次运行时,每个 check 成为参考。之后,存在未判定的差异时测试失败,CI 日志会给出报告链接。您在那里判定每处差异:"有意"或"缺陷"。
- 每个分支一份参考。 测试给出自己的分支和基础分支(
branch、baseBranch):新分支从首次运行起就与其基础分支比对,而"有意"只适用于您勾选的分支。 - 测试的其余部分不变。
playwright.config.ts中的项目继续生效:每种屏幕尺寸都有自己的参考。唯一的条件:屏幕像素密度为 1(deviceScaleFactor: 1)。
该 SDK 支持 TypeScript 和 JavaScript 的 Playwright,运行于 Chromium。它目前先以抢先体验的方式提供:可从其页面申请访问权限。
对于不编写测试的人
Playwright 测试终究是代码。要让 QA、产品负责人或设计师也能验证应用的外观,像 Delta-QA 这样的无代码方案提供了另一条路:在浏览器中录制一个流程,Delta-QA 在每个版本中重放,并将每一步与其参考比对。这些场景和 Vision SDK 的 check 在同一个 Delta-QA 空间中判定,使用同一份报告。
想在不写一行 TypeScript、不重新生成任何一张基线的情况下测试吗? 现在就用 Delta-QA 比对您的页面,免费,无需绑定银行卡。免费使用 Delta-QA →
常见问题
Playwright 的视觉测试免费吗?
是的,完全免费。toHaveScreenshot() 是 Playwright 的原生内置功能,Playwright 是开源的,由微软维护。没有许可证,也没有截图数量限制。
搭建 Playwright 视觉测试需要多长时间?
如果您已经熟悉 Playwright,配置并编写第一批测试大约需要几个小时。如果从零开始(安装、学习 TypeScript、配置 CI),则需要 2 到 3 天。
视觉测试选 Playwright 还是 Cypress?
Playwright 的优势是原生集成了视觉测试(toHaveScreenshot()),而 Cypress 需要外部插件。Playwright 还支持三种浏览器引擎(Chromium、Firefox、WebKit),而 Cypress 支持 Chromium 和 Firefox 浏览器,WebKit 仍处于实验阶段。详情请参阅我们的 Playwright 与 Cypress 对比,如果您在这两个框架之间犹豫,也可参阅 Playwright 与 Selenium。
Playwright 和 Delta-QA 可以一起使用吗?
可以,而且就在同一个测试里。借助 Vision SDK,您在需要验证页面的步骤中添加 vision.check():Playwright 驱动浏览器和您的功能断言,Delta-QA 将页面与其参考比对。QA 团队无需代码录制的流程则在同一个空间中判定。
使用 Vision SDK 需要移除我的 toHaveScreenshot() 吗?
不需要。两者可以共存于同一个测试套件:您可以在少数页面上添加 vision.check(),比较结果,然后逐页决定保留哪个。
Playwright 为自动化视觉测试提供了坚实的基础。对于用 TypeScript 编写测试的团队,toHaveScreenshot() 很可能是 2026 年可用的最佳开源选项,前提是一开始就调好阈值并稳定好测试。当像素 diff 和仓库中的基线成为主要负担时,Vision SDK 会保留您的测试,更换比对方式。要了解 Playwright 与其他工具的相对位置,请参阅我们的回归测试工具对比。
