使用 Playwright 进行视觉测试：完整教程

Source: Dev.to

自 1.22 版起，Microsoft 的 Playwright 包含了原生的视觉测试功能：toHaveScreenshot() 方法。它会捕获屏幕截图并自动将其与参考图像进行比较，无需外部插件。这是希望在现有技术栈中加入视觉测试的开发团队的强大选项。教程涵盖了安装、配置、最佳实践以及 CI/CD 集成。

安装与首次测试

Setup is quick with an existing Node.js project:

npm install -D @playwright/test
npx playwright install

Create your first visual test in 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');
});

The first run generates the baseline. Subsequent runs compare against it.

配置容差

默认情况下，Playwright 会标记任何单像素差异。实际使用中，配置阈值以避免误报：

// playwright.config.ts
export default defineConfig({
  expect: {
    toHaveScreenshot: {
      maxDiffPixelRatio: 0.01,
      animations: 'disabled',
      scale: 'device',
    },
  },
});

处理动态内容

常见的三种解决方案：

1. 遮罩动态区域 – 使用 mask 选项来忽略页面中变化的部分。
2. 通过 page.evaluate() 替换内容 – 在截图前注入确定性的数据。
3. 使用注入的 CSS 隐藏 – 添加样式块以隐藏或稳定动画元素。

每种方法在可靠性和维护工作量之间取得平衡。

稳定化测试

• 在捕获之前等待网络空闲、字体加载以及关键元素可见。
• 在 Playwright 配置中全局禁用动画（如上所示）。
• 在需要时使用显式等待或 page.waitForLoadState('networkidle')。

多分辨率测试

利用 Playwright 项目在不同的视口和设备上运行相同的测试套件，每个都有各自的基准：

// playwright.config.ts
export default defineConfig({
  projects: [
    {
      name: 'Desktop',
      use: { viewport: { width: 1920, height: 1080 } },
    },
    {
      name: 'Tablet',
      use: { viewport: { width: 768, height: 1024 } },
    },
    {
      name: 'Mobile',
      use: { device: 'iPhone 13' },
    },
  ],
});

CI/CD 集成

GitHub Actions（或任何 CI 系统）可以自动运行视觉测试。当测试失败时，Playwright 会生成三张图片：

• Baseline – 存储的参考截图。
• Actual – 新捕获的截图。
• Diff – 带有红色高亮的图像，显示像素差异。

HTML 报告会并排显示这些图片，便于在流水线中审查失败情况。

限制

• 需要 TypeScript/JavaScript 知识。
• 没有内置的审查仪表板；只能依赖生成的 HTML 报告。
• 像素比较比较基础——浏览器之间的抗锯齿和字体渲染差异可能导致噪声。
• 为多个浏览器的众多测试管理基线会产生大量文件（例如，200 + 测试 × 3 个浏览器 = 600 + 基线图像）。

对于倾向于无代码方式的团队，可考虑 Delta‑QA，它提供无需编写代码、管理基线或处理误报的视觉回归测试。

常见问题

Playwright 的视觉测试是免费的吗？

是的。toHaveScreenshot() 已内置于 Playwright，Playwright 是开源且免费使用的。

在视觉测试方面选择 Playwright 还是 Cypress？

Playwright 提供原生的视觉测试，而 Cypress 需要外部插件。Playwright 还支持三种浏览器引擎（Chromium、Firefox、WebKit），而 Cypress 只专注于单一引擎，这使得 Playwright 成为视觉测试的更佳选择。

可以同时使用 Playwright 和 Delta‑QA 吗？

当然可以。使用 Playwright 进行复杂的面向开发者的测试，使用 Delta‑QA 进行 QA 团队执行的常规视觉检查。