visual-regression-gen

name	visual-regression-gen
description	為 Web 應用生成視覺回歸測試（Visual Regression）腳本與 baseline 管理流程。支援 Playwright snapshot / Percy / Chromatic / BackstopJS 四大主流方案。自動偵測動態元素（時間 / 廣告 / animation）並 mask 掉，設定差異容忍度（pixelmatch threshold）。當使用者提到「視覺回歸 / visual regression / screenshot test / Percy / Chromatic / Playwright snapshot / 介面比對 / UI baseline」時觸發。配套：test-automation（生成 E2E 腳本）、test-master（視覺回歸 TC 規劃）、smoke-test-analyzer（VR 屬於 T2 release）。
disable-model-invocation	false
allowed-tools	Read, Grep, Glob, Write, Edit, Bash
argument-hint	[頁面 URL / 元件路徑] [--tool=playwright|percy|chromatic|backstop]

visual-regression-gen

⚙️ 執行前先讀 modules/config-loader.md。 啟用條件：config.platforms.web.enabled = true 且 config.visual_regression.enabled = true。

適用場景

• ✅ Web App 有重要的視覺品質要求（品牌頁 / Marketing site / Dashboard）
• ✅ 已有 E2E 但沒有「視覺改變」守門
• ✅ 想在 PR 看到 "視覺 diff" 自動標出
• ✅ 多瀏覽器要對齊（Chrome / Safari 渲染差異）

不適用場景

• ❌ 純 API 後端 — 用 tc-to-pytest
• ❌ UI 變動頻繁的早期 MVP — baseline 維護成本高
• ❌ 大量動態內容（隨機推薦 / 廣告） — 即使 mask 也 flaky

工具選擇

工具	適合	雲服務	成本
Playwright snapshot（推薦）	自託管、開源、最簡	❌ self-host	免費
Percy	雲端 baseline 管理、PR 整合	✅	$$
Chromatic	Storybook 元件、視覺 review workflow	✅	$$
BackstopJS	Legacy 專案、需要 hot reload baseline	❌ self-host	免費

預設 {{VR_TOOL}}（從 config 讀），可用 --tool= 覆寫。

執行流程

Phase 1: 偵測既有設定

# 找配置檔
ls playwright.config.* .percy.* .chromatic.* backstop.json 2>/dev/null

若已有對應配置 → 直接擴充，不從零建。

Phase 2: 識別關鍵 viewport

從 config.platforms.web.viewport_sizes 讀（預設 desktop / tablet / mobile）：

Viewport	用途
1920×1080 desktop	主流桌機
1366×768 desktop	老舊 / 低解析度
768×1024 tablet	iPad 直
375×667 mobile	iPhone SE/小螢幕

Phase 3: 動態元素 masking 策略

自動偵測該 mask 掉的元素（避免 false-positive flaky）：

類型	locator	處理
時間戳	[data-testid*="time"] / time	mask
動畫 GIF / video	img[src*=".gif"], video	mask
廣告	iframe[src*="ads"], [class*="ad-banner"]	mask
即時數字（unread count）	[data-testid*="badge"]	mask
隨機推薦	[data-testid*="recommendation"]	mask

讓使用者覆核，可自加自定義 mask。

Phase 4: 生成腳本

Playwright snapshot 範例

// tests/visual/home.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Home page visual regression', () => {

  for (const viewport of [
    { name: 'desktop', width: 1920, height: 1080 },
    { name: 'tablet',  width: 768,  height: 1024 },
    { name: 'mobile',  width: 375,  height: 667 },
  ]) {
    test(`TC: VR-HOME-001 home page @ ${viewport.name}`, async ({ page }) => {
      await page.setViewportSize({ width: viewport.width, height: viewport.height });
      await page.goto('/');
      await page.waitForLoadState('networkidle');

      // Mask 動態元素
      await expect(page).toHaveScreenshot(`home-${viewport.name}.png`, {
        mask: [
          page.locator('[data-testid="current-time"]'),
          page.locator('iframe[src*="ads"]'),
          page.locator('[class*="ad-banner"]'),
        ],
        maxDiffPixelRatio: 0.02,   // 2% 容忍
        animations: 'disabled',     // 凍結動畫
      });
    });
  }
});

Percy 範例

const percySnapshot = require('@percy/playwright');

test('TC: VR-HOME-001 home page', async ({ page }) => {
  await page.goto('/');
  await percySnapshot(page, 'Home page', {
    widths: [1920, 1366, 768, 375],
    percyCSS: `
      [data-testid="current-time"] { visibility: hidden; }
      iframe[src*="ads"] { display: none; }
    `,
  });
});

Chromatic（Storybook 整合）範例

// Button.stories.tsx
export const Primary = {
  args: { variant: 'primary', children: 'Click me' },
  parameters: { chromatic: { viewports: [320, 768, 1200] } },
};

Phase 5: Baseline 管理

工具	Baseline 存哪
Playwright snapshot	git 內 tests/visual/__screenshots__/
Percy	Percy cloud
Chromatic	Chromatic cloud
BackstopJS	backstop_data/ (git 或 S3)

git 內 baseline 注意：

• ✅ Commit 進 git（小團隊好做 diff review）
• ⚠️ 大團隊建議 Git LFS（baseline 累積會肥）
• ❌ 不該 in CI cache（每次 CI re-generate 失去 baseline 意義）

Phase 6: 處理 false positive

當 PR 改動觸發視覺 diff 但實際 UI 正確：

1. 誤判 → 加 mask / 提高 maxDiffPixelRatio
2. 真的改了 UI → npx playwright test --update-snapshots 更新 baseline，commit 進 PR

Phase 7: CI 整合

# .github/workflows/visual-regression.yml
on:
  pull_request:
    paths: ['src/**', 'public/**', 'styles/**']

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

PR 內若有 diff，自動上傳 diff 影像。

⚠️ 安全護欄

• ❌ 不主動 --update-snapshots（需要使用者明確同意）
• ✅ Diff > threshold → CI fail（守門）
• ✅ Baseline commit 必須通過 review
• ⚠️ baseline 規模 > 50 個 / 100 MB → 提示用 Git LFS

設定依賴

設定 Key	用途	缺值時行為
visual_regression.enabled	啟用此 skill	skill 不啟用
visual_regression.tool	預設工具	playwright
visual_regression.max_diff_ratio	預設容忍度	0.02 (2%)
platforms.web.viewport_sizes	跑哪些 viewport	3 個預設

範例

詳見 examples.md