Playwright 视觉测试完整指南

Playwright 视觉测试完整指南

周五晚上,您合并了页眉的改版。周一早上,同事告诉您,价格页上的登录按钮偏移了几个像素:而这个页面您根本没碰过。没有任何测试发出警报,因为没有任何测试在检查外观。视觉测试填补的正是这个空白。

微软的 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 与其他工具的相对位置,请参阅我们的回归测试工具对比。