agent-capabilities

エージェントの機能 — ビジュアルリグレッションテスト

このドキュメントでは、Web アプリケーションにおけるビジュアルリグレッションテストのインフラストラクチャを実装、管理するための Claude の包括的な機能について説明します。

中核となる機能

1. ビジュアルリグレッションテストのインフラストラクチャ

Claude は、Ant Design、Argos CI などの主要な組織における業界のベストプラクティスに従って、ビジュアルリグレッションテストのインフラストラクチャ全体をセットアップできます。

機能：

• ✅ ビジュアルテスト用に Playwright を設定
• ✅ ピクセル単位の比較に jest-image-snapshot を導入
• ✅ ベースラインのスクリーンショット管理システムを作成
• ✅ HTML／Markdown 出力でビジュアル差分レポートを生成
• ✅ 複数のビューポートとブラウザーでのテストをセットアップ
• ✅ アンチエイリアス検出機能を備えたしきい値ベースの比較を設定

実装リファレンス：

• スキル：.claude/skills/visual-regression-testing/SKILL.md
• テストユーティリティ：tests/shared/imageTest.tsx
• スクリプト：scripts/visual-regression/

2. CI/CD との統合

Claude は、自動 PR チェック、ベースラインの更新、アーティファクト管理を備えた GitHub Actions のワークフローにビジュアルリグレッションテストを統合できます。

機能：

• ✅ ビジュアルリグレッション発生時に失敗する PR チェックワークフローを作成
• ✅ main ブランチへのマージ時にベースラインを自動更新
• ✅ ビジュアル差分のアーティファクトを生成してアップロード
• ✅ ビジュアル比較プレビューを添えた PR コメントを投稿
• ✅ パフォーマンス向上のために並列テスト実行を設定
• ✅ レポートの生成と配布をセットアップ

実装リファレンス：

• PR ワークフロー：.github/workflows/visual-regression-pr.yml
• ベースラインワークフロー：.github/workflows/visual-regression-baseline.yml
• レポートワークフロー：.github/workflows/visual-regression-report.yml

3. スクリーンショット管理

Claude は、動的コンテンツのマスキング、アニメーションの停止、ビューポート制御に対応した高度なスクリーンショットのキャプチャおよび管理システムを実装できます。

機能：

• ✅ ページ全体や特定の要素のスクリーンショットをキャプチャ
• ✅ タイムスタンプ、日付、その他の動的コンテンツを自動的に非表示
• ✅ 一貫性を保つためにアニメーションとトランジションを停止
• ✅ 複数のビューポートでレスポンシブデザインに対応
• ✅ テーマのバリエーション（ライトモード／ダークモード）に対応
• ✅ 意味の分かる名前を付けてスクリーンショットを整理

実装リファレンス：

• ベースラインのキャプチャ：scripts/visual-regression/capture-baselines.ts
• テストユーティリティ：tests/shared/imageTest.tsx:45-100

4. 比較とレポート

Claude は、設定可能なしきい値によるピクセル単位の比較を実装し、包括的なビジュアル差分レポートを生成できます。

機能：

• ✅ pixelmatch を使用したピクセル単位の比較
• ✅ 差分しきい値を設定（0.01%～5%）
• ✅ 誤検出を減らすアンチエイリアス検出
• ✅ 並べて比較できる HTML レポートを生成
• ✅ GitHub の PR コメント用に Markdown レポートを作成
• ✅ リグレッションの履歴と傾向を追跡

実装リファレンス：

• 比較：scripts/visual-regression/compare-screenshots.ts
• HTML レポート：scripts/visual-regression/generate-report.js

5. クラウドストレージとの統合

Claude は、長期保存や共有のために、ビジュアルリグレッションのアーティファクトをクラウドストレージプロバイダーと統合できます。

機能：

• ✅ AWS S3、Azure Blob Storage、Alibaba OSS にアップロード
• ✅ アーティファクト共有用の公開 URL を生成
• ✅ 保持ポリシーを導入
• ✅ CDN 配信を設定
• ✅ 開発時のローカルストレージに対応

実装リファレンス：

• アップロードユーティリティ：scripts/visual-regression/upload-to-storage.ts

ワークフローパターン

パターン 1：初期セットアップ

ユーザーがビジュアルリグレッションテストのセットアップを依頼した場合、Claude は次の手順を実行します。

1. ディレクトリ構造を作成：

   tests/shared/imageTest.tsx
   scripts/visual-regression/
   .github/workflows/visual-regression-*.yml
   __image_snapshots__/baseline/
   

2. 依存関係をインストール：

   {
     "devDependencies": {
       "@playwright/test": "^1.40.0",
       "playwright": "^1.40.0",
       "jest-image-snapshot": "^6.2.0",
       "pixelmatch": "^5.3.0",
       "pngjs": "^7.0.0"
     }
   }
   

3. npm スクリプトを追加：

   {
     "scripts": {
       "visual:test": "playwright test",
       "visual:baseline": "GENERATE_BASELINE=true playwright test --grep @baseline",
       "visual:update-baseline": "npm run visual:baseline",
       "visual:compare": "node scripts/visual-regression/compare-screenshots.ts",
       "visual:report": "node scripts/visual-regression/generate-report.js",
       "visual:upload": "node scripts/visual-regression/upload-to-storage.ts"
     }
   }
   

4. Playwright を設定：

   // playwright.config.ts
   export default {
     testDir: './tests',
     use: {
       baseURL: 'http://localhost:5173',
       screenshot: 'only-on-failure',
       video: 'retain-on-failure',
     },
     projects: [
       { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
     ],
   };
   

パターン 2：コンポーネントテスト

新しいコンポーネントにビジュアルテストを追加する場合：

1. テストファイルを作成します：

   import { test } from '@playwright/test';
   import { runVisualTest, VIEWPORTS } from '../shared/imageTest';
   
   test('button component - all variants', async ({ page }) => {
     await runVisualTest(page, {
       identifier: 'button-variants',
       url: '/components/button',
       viewport: VIEWPORTS.desktop,
       threshold: 0.05,
     });
   });
   

2. ベースラインを生成します：

   npm run visual:baseline
   

3. CI で実行します：

   • PR の作成時に自動実行されます
   • ビジュアルの差分が検出されると失敗します
   • PR のコメントに差分画像を投稿します

パターン 3：ベースラインの更新

意図的にビジュアルを変更した場合：

1. 差分レポートを確認します：

   • CI のアーティファクトを確認します
   • visual-report.html をダウンロードします
   • 変更が意図したものか検証します

2. ベースラインを更新します：

   npm run visual:update-baseline
   git add __image_snapshots__/baseline/
   git commit -m "chore: update visual baselines for button redesign"
   

3. プッシュして再テストします：

   • CI でテストが再実行されます
   • 更新されたベースラインでテストが成功します

パターン 4：トラブルシューティング

ビジュアルテストが予期せず失敗した場合：

1. 環境の違いを確認します：

   • フォントのレンダリング（Docker を使用します）
   • ブラウザーのバージョン（CI で固定します）
   • OS の違い（CI と同じプラットフォームでテストします）

2. 必要に応じてしきい値を調整します：

   threshold: 0.1, // Increase from 0.05 to 0.1
   

3. 動的なコンテンツをマスクします：

   hideSelectors: [
     '[data-testid="timestamp"]',
     '.loading-spinner',
   ],
   

ベストプラクティス

1. テスト対象

✅ テストするもの：

• ユーザーにとって重要なコンポーネント
• レイアウトとレスポンシブ動作
• テーマのバリエーション（ライト／ダーク）
• 複数のビューポートでのレンダリング
• コンポーネントの状態のバリエーション

❌ テストしないもの：

• 頻繁に変化するコンテンツ（ニュースフィード、タイムスタンプ）
• ランダム／動的なデータの表示
• サードパーティーの埋め込みコンテンツ
• スピナーを含む読み込み状態

2. しきい値の設定

// Critical UI - strict comparison
threshold: 0.01  // 0.01% = ~10 pixels in 100k

// Standard components
threshold: 0.1   // 0.1% = ~100 pixels in 100k

// Charts/graphs with anti-aliasing
threshold: 0.5   // 0.5% = ~500 pixels in 100k

3. パフォーマンスの最適化

• ワーカー間でテストを並列実行します
• CI でヘッドレスモードを使用します
• Playwright のブラウザーをキャッシュします
• 影響を受けるコンポーネントだけを選んでテストします
• 変更されていないベースラインを再利用します

4. 誤検出の削減

• CSS でアニメーションを停止します
• 一貫した環境（Docker）を使用します
• ブラウザーのバージョンを固定します
• タイムスタンプと動的なコンテンツをマスクします
• アンチエイリアス検出を有効にします

既存ツールとの統合

ビジュアルリグレッションテストは、以下と統合できます：

Webapp Testing スキル

• Playwright のセットアップに webapp-testing スキルを使用します
• サーバー管理に scripts/with_server.py を活用します
• 調査してから実行するパターンに従います

参照： .claude/skills/webapp-testing/SKILL.md

CI/CD パイプライン

• ユニットテスト／コンポーネントテストの合格後に実行します
• ビジュアルリグレッションがある場合、マージをブロックします
• GitHub Actions にアーティファクトをアップロードします
• PR のコメントに結果を投稿します

参照： .github/workflows/visual-regression-pr.yml:1

Odoo 開発

• Odoo のウェブインターフェースのコンポーネントをテストできます
• 複数のテーマのテストに対応しています
• レスポンシブレイアウトを検証します
• モジュール固有の UI 変更をテストします

実例

例 1：ホームページのビジュアルテスト

import { test } from '@playwright/test';
import { runVisualTest, VIEWPORTS } from '../shared/imageTest';

test('homepage - responsive design', async ({ page }) => {
  for (const [name, viewport] of Object.entries(VIEWPORTS)) {
    await runVisualTest(page, {
      identifier: `homepage-${name}`,
      url: '/',
      viewport,
      fullPage: true,
      threshold: 0.1,
    });
  }
});

例 2：コンポーネントライブラリのテスト

test('design system - all components', async ({ page }) => {
  const components = ['button', 'input', 'select', 'modal', 'table'];

  for (const component of components) {
    await runVisualTest(page, {
      identifier: `component-${component}`,
      url: `/components/${component}`,
      selector: `[data-testid="${component}-showcase"]`,
      threshold: 0.05,
    });
  }
});

例 3：テーマ切り替えのテスト

test('dark mode - all pages', async ({ page }) => {
  const pages = ['/', '/about', '/contact'];

  for (const pagePath of pages) {
    // Test light mode
    await runVisualTest(page, {
      identifier: `${pagePath.replace(/\//g, '-')}-light`,
      url: pagePath,
      fullPage: true,
    });

    // Switch to dark mode
    await page.evaluate(() => {
      document.documentElement.setAttribute('data-theme', 'dark');
    });

    // Test dark mode
    await runVisualTest(page, {
      identifier: `${pagePath.replace(/\//g, '-')}-dark`,
      url: pagePath,
      fullPage: true,
    });
  }
});

学習リソース

公式ドキュメント

• Ant Design のビジュアルリグレッション
• Playwright のスクリーンショット
• jest-image-snapshot

業界ツール

• Argos CI - ビジュアルテストプラットフォーム
• Percy - ビジュアルレビュープラットフォーム
• Chromatic - Storybook のビジュアルテスト

実装リファレンス

すべてのコードはこのリポジトリで確認できます：

• .claude/skills/visual-regression-testing/SKILL.md - スキルの全ドキュメント
• .github/workflows/visual-regression-*.yml - CI/CD ワークフロー
• tests/shared/imageTest.tsx - テストユーティリティ
• scripts/visual-regression/ - 実装スクリプト

この機能を使用するタイミング

Claude は、次の場合にビジュアル回帰テストを積極的に提案してください。

1. ユーザーがビジュアルテストや回帰テストに言及した場合

   • 「UI の変更をテストしたい」
   • 「ビジュアルバグを防ぐにはどうすればよいですか？」
   • 「スクリーンショットテストを設定してください」

2. コンポーネント開発のコンテキスト

   • デザインシステムの構築
   • コンポーネントライブラリの作成
   • レスポンシブレイアウトの実装

3. CI/CD の強化に関するリクエスト

   • 「テストパイプラインを改善してください」
   • 「UI チェックを自動化してください」
   • 「PR でビジュアルバグを防いでください」

4. ビジュアルの問題のデバッグ

   • 「何かが違って見えますが、何が違うのかわかりません」
   • 「モバイルでは UI が壊れますが、デスクトップでは動作します」
   • 「テーマの切り替えに問題があります」

エージェントの判断フロー

User request → Contains visual/UI/screenshot keywords?
  ├─ Yes → Offer visual regression testing setup
  │   ├─ Already has visual tests? → Enhance/extend
  │   └─ No visual tests? → Full setup
  │
  └─ No → Monitor for component development
      └─ Creating UI components? → Suggest visual testing

概要

Claude は、本番環境に対応したビジュアル回帰テスト基盤を実装するための包括的な機能を備えています。これには以下が含まれます。

• ✅ Playwright + jest-image-snapshot の完全なセットアップ
• ✅ GitHub Actions との CI/CD 統合
• ✅ ベースラインの自動管理
• ✅ HTML/Markdown によるビジュアル差分レポート
• ✅ 複数のビューポートとブラウザーのサポート
• ✅ 成果物のクラウドストレージ統合
• ✅ 業界をリードする企業（Ant Design、Argos）のベストプラクティス

すべての実装は、主要なデザインシステムで実証済みのパターンに従っており、すぐに使用できる本番環境対応の状態です。

---

最終更新日： 2025-11-13 手法の出典： Ant Design のビジュアル回帰テスト 実装状況： ✅ 完了、本番環境ですぐに使用可能