Visual Regression Testing — Percy / Chromatic / Playwright Snapshot 完整對比

「UI 改 padding 改死人」、「按鈕從 red 變 dark-red 沒人發現」 — 這些功能性測試抓不到的、Visual Regression 抓得到。這篇給你完整工具地圖 + 實戰 setup。

基本用法

import { test, expect } from '@playwright/test';

test('homepage looks right', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveScreenshot('homepage.png');
});

第一次跑 → 建立 baseline homepage.png。 之後跑 → 比對 baseline、有差 → fail。

配置（playwright.config.ts）

export default defineConfig({
  use: {
    // 關掉動畫避免 flaky
    actionTimeout: 0,
  },
  expect: {
    toHaveScreenshot: {
      // 允許 0.1% 像素差異（防 anti-aliasing flaky）
      maxDiffPixelRatio: 0.001,
      // 動畫 disabled
      animations: 'disabled',
      // 截圖時隱藏 cursor
      caret: 'hide',
    },
  },
});

進階：mask 動態元素

test('avoid time / random masking', async ({ page }) => {
  await page.goto('/dashboard');
  await expect(page).toHaveScreenshot('dashboard.png', {
    mask: [
      page.locator('.timestamp'),
      page.locator('.random-banner'),
      page.locator('time'),
    ],
  });
});

跨裝置

test.describe('responsive', () => {
  for (const device of ['Desktop Chrome', 'iPhone 13', 'iPad Pro']) {
    test(`looks right on ${device}`, async ({ browser }) => {
      const context = await browser.newContext({ ...devices[device] });
      const page = await context.newPage();
      await page.goto('/');
      await expect(page).toHaveScreenshot(`home-${device}.png`);
    });
  }
});

更新 baseline

npx playwright test --update-snapshots

code review 時帶上 baseline diff 截圖、reviewer 才看得出變化是預期還是 bug。

Setup

npm install --save-dev @percy/cli @percy/playwright

import { test } from '@playwright/test';
import percySnapshot from '@percy/playwright';

test('homepage', async ({ page }) => {
  await page.goto('https://example.com');
  await percySnapshot(page, 'homepage');
});

跑：

PERCY_TOKEN=xxx npx percy exec -- npx playwright test

Percy 強項

npm install --save-dev chromatic
npx chromatic --project-token=xxx

Chromatic 抓你所有 Storybook stories、自動拍 + 比對。Component 層級的視覺穩定 → 整個 UI 穩。

優勢：

• Component-level snapshot（粒度比 page 細）
• 設計師 friendly UI
• 跟 Figma 對齊

不是 pixel diff、是 「語意一致」比對：

• 字體大小改 1px → AI 知道是同字體
• 顏色 hex 改 1 號 → AI 知道是同顏色
• 版面微調 → AI 容忍

減少 false positive 5-10 倍。但貴。

import { Eyes } from '@applitools/eyes-playwright';

test('with Applitools', async ({ page }) => {
  const eyes = new Eyes();
  await eyes.open(page, 'My App', 'Homepage Test');
  await page.goto('/');
  await eyes.check('Homepage');
  await eyes.close();
});

Playwright + GitHub Actions

name: Visual Tests
on: [pull_request]

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test --grep @visual
      - if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: visual-diff
          path: test-results/

PR 中失敗 → 下載 artifact 看 diff PNG。

1. 拍小區塊比拍整頁穩
2. 動態元素 mask、動畫 disable
3. 同 docker 跑 = 跨平台一致性
4. 新案先 Playwright snapshot、長大再 Percy
5. Code review 時帶 diff 圖、reviewer 才能判斷

Visual Regression 是 「功能測試抓不到、但使用者一眼看出來」的最後防線。從 Playwright 內建 snapshot 起步、設好 threshold + mask、CI 自動跑、PR 帶 diff — 半年後 UI 退步 bug 砍 80%。

延伸：

• Page Object Model 實戰
• Cross-browser Testing 策略
• Accessibility (a11y) Testing