visual-testing-advanced

高度なビジュアルテスト

<default_to_action> ビジュアルのリグレッションを検出したり、UI を検証したりする場合：

1. ベースラインのスクリーンショットを撮影します（初回実行時にベースラインを確立します）
2. 新しいスクリーンショットをベースラインと比較します（ピクセル単位または AI による比較）
3. 動的コンテンツ（タイムスタンプ、広告、ユーザー数）をマスクします
4. デバイスをまたいでテストします（デスクトップ、タブレット、モバイルのビューポート）
5. 意図した変更をレビューして承認し、リグレッションがあれば失敗とします

ビジュアルテストの簡単な手順：

• main ブランチでベースラインを設定する
• フィーチャーブランチをベースラインと比較する
• 動的要素（タイムスタンプ、アバター）をマスクする
• AI を活用した比較を使って誤検出を減らす
• CI/CD に組み込み、ビジュアルのリグレッションを阻止する

成功のための重要な要素：

• 機能テストではビジュアルのバグを検出できません
• AI を活用したツールで誤検出を減らせます
• 差分をレビューし、自動承認だけに頼らないでください </default_to_action>

クイックリファレンスカード

使用するタイミング

• UI コンポーネントの変更
• CSS／スタイルの変更
• レスポンシブデザインの検証
• クロスブラウザーの一貫性チェック

ビジュアルバグの種類

バグの種類	説明
レイアウトのずれ	要素の位置が移動する
色の変化	意図しない色の変更
フォントのレンダリング	タイポグラフィの問題
配置	余白や配置の問題
画像の欠落	画像パスの破損
オーバーフロー	コンテンツの切り取り

比較アルゴリズム

アルゴリズム	最適な用途
ピクセル差分	完全一致が必要な場合
構造的類似性	アンチエイリアスに対応する場合
AI セマンティック比較	重要でない変更を無視する場合

---

優先パス：qe-browser visual-diff

ビジュアルリグレッション作業の大半は、qe-browser フリートスキルを使用してください。 Vibium（WebDriver BiDi）をラップし、保存済みベースラインとのピクセル差分比較、しきい値の適用、差分画像の出力を提供します。.claude/skills/qe-browser/SKILL.md を参照してください。

# Navigate
vibium go https://example.com
vibium wait load

# First run — creates baseline in .aqe/visual-baselines/homepage.png
node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage

# Subsequent runs — compare, non-zero exit on mismatch
node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage --threshold 0.02

# Scope to a single region
node .claude/skills/qe-browser/scripts/visual-diff.js --name hero --selector "#hero"

# Responsive — run diff at each breakpoint
for viewport in "375 667" "768 1024" "1920 1080"; do
  read w h <<< "$viewport"
  vibium viewport $w $h
  node .claude/skills/qe-browser/scripts/visual-diff.js --name "homepage-${w}x${h}"
done

# Reset baseline after an intentional design change
node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage --update-baseline

ベースラインは .aqe/visual-baselines/ に保存されます。このスクリプトは pixelmatch がインストールされている場合はそれを使用し、そうでない場合はハッシュベースの完全一致判定にフォールバックします。類似度が 1 - threshold 未満の場合はゼロ以外の終了コードを返すため、CI のゲート判定には $? を使います。

Playwright のビジュアルリグレッションを使う場合

以下が必要な場合に限り、下記の Playwright の手順を使ってください。

• AI セマンティック比較（Percy、Applitools）を使って、重要でないピクセルのずれを無視する
• Firefox／WebKit でのクロスブラウザーのレンダリングチェック（現時点で Vibium が対応しているのは Chrome のみです）
• 既存の Playwright テストスイートとの緊密な統合

---

従来の方法：Playwright によるビジュアルリグレッション（フォールバック）

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

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

  // Capture and compare screenshot
  await expect(page).toHaveScreenshot('homepage.png');
  // First run: saves baseline
  // Subsequent runs: compares to baseline
});

test('responsive design', async ({ page }) => {
  // Mobile viewport
  await page.setViewportSize({ width: 375, height: 667 });
  await page.goto('https://example.com');
  await expect(page).toHaveScreenshot('homepage-mobile.png');

  // Tablet viewport
  await page.setViewportSize({ width: 768, height: 1024 });
  await expect(page).toHaveScreenshot('homepage-tablet.png');
});

---

動的コンテンツへの対応

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

  await expect(page).toHaveScreenshot({
    mask: [
      page.locator('.timestamp'),     // Dynamic time
      page.locator('.user-count'),    // Live counter
      page.locator('.advertisement'), // Ads
      page.locator('.avatar')         // User avatars
    ]
  });
});

---

AI を活用したビジュアルテスト（Percy）

import percySnapshot from '@percy/playwright';

test('AI-powered visual test', async ({ page }) => {
  await page.goto('https://example.com');

  // Percy uses AI to ignore anti-aliasing, minor font differences
  await percySnapshot(page, 'Homepage');
});

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

  // Snapshot specific component
  const button = page.locator('.primary-button');
  await percySnapshot(page, 'Primary Button', {
    scope: button
  });
});

---

Playwright の設定

// playwright.config.js
export default {
  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 100,      // Allow 100 pixel difference
      maxDiffPixelRatio: 0.01, // Or 1% of image
      threshold: 0.2,          // Color similarity threshold
      animations: 'disabled',  // Disable animations
      caret: 'hide'            // Hide cursor
    }
  }
};

---

エージェント駆動のビジュアルテスト

// Comprehensive visual regression
await Task("Visual Regression Suite", {
  baseline: 'main-branch',
  current: 'feature-branch',
  pages: ['homepage', 'product', 'checkout'],
  devices: ['desktop', 'tablet', 'mobile'],
  browsers: ['chrome', 'firefox', 'safari'],
  threshold: 0.01
}, "qe-visual-tester");

// Returns:
// {
//   comparisons: 27,  // 3 pages × 3 devices × 3 browsers
//   differences: 2,
//   report: 'visual-regression-report.html'
// }

---

エージェント連携のヒント

メモリの名前空間

aqe/visual-testing/
├── baselines/*          - Baseline screenshots
├── comparisons/*        - Diff results
├── components/*         - Component snapshots
└── reports/*            - Visual regression reports

フリート連携

const visualFleet = await FleetManager.coordinate({
  strategy: 'visual-testing',
  agents: [
    'qe-visual-tester',   // Screenshot comparison
    'qe-test-executor',   // Cross-browser execution
    'qe-quality-gate'     // Block on visual regressions
  ],
  topology: 'parallel'
});

---

関連スキル

• アクセシビリティテスト - ビジュアルな a11y チェック
• 互換性テスト - クロスブラウザーの表示
• リグレッションテスト - リグレッションテストスイート

---

覚えておくこと

機能テストではビジュアルのバグを検出できません。 レイアウトのずれ、色の変化、フォントのレンダリング、配置の問題は、機能テストではすべて見えませんが、ユーザーには見えます。

AI を活用したツールで誤検出を減らせます。 Percy と Applitools は AI を使って、重要でない差異（アンチエイリアス、わずかなフォントのレンダリングの違い）を無視します。

エージェントの場合： qe-visual-tester はブラウザーやデバイスをまたいだビジュアルリグレッションを自動化し、AI でノイズを除去して、ビジュアル差分レポートを生成します。ユーザーが目にする前に UI のリグレッションを検出します。