CI/CDパイプラインにビジュアルテストを統合する方法

なぜCI統合が重要なのか

ビジュアルテストをローカルで実行するのは出発点にすぎません。真の価値は、すべてのプルリクエストで自動的に実行されることで生まれます。これにより、ビジュアルテストは手動チェックから、リグレッションがメインブランチに到達する前にキャッチするセーフティネットへと変わります。

GitHub Actionsのセットアップ

以下は本番対応のGitHub Actionsビジュアルテストワークフローです：

name: Visual Regression Tests
on:
  pull_request:
    branches: [main]

jobs:
  visual-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium

      - name: Build application
        run: npm run build

      - name: Run visual tests
        run: npx playwright test --project=visual

      - name: Upload diff artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: visual-diffs
          path: test-results/
          retention-days: 7

ポイントは、失敗時のupload-artifactステップです。ビジュアルテストが失敗すると、差分画像がビルドアーティファクトとしてアップロードされ、レビュアーが何が変わったかを正確に確認できます。

CIでのテスト失敗への対応

CIでのビジュアルテストの失敗には、通常のテスト失敗とは異なるレビュープロセスが必要です：

差分レビューワークフロー

1. 開発者がPRを作成する
2. CIがビジュアルテストを実行し、差異を検出する
3. 差分画像がPRコメントとして投稿されるか、アーティファクトとしてアップロードされる
4. 開発者とデザイナーが一緒に差分をレビューする
5. 変更が意図的であれば、ベースラインを更新する
6. 変更が意図しないものであれば、コードを修正する

差分コメントの自動化

GitHub APIを使用して、差分画像をPRコメントとして直接投稿できます：

// Post visual diff as PR comment
async function postDiffComment(
  prNumber: number,
  diffs: { name: string; url: string }[]
) {
  const body = diffs
    .map((d) => `### ${d.name}\n![diff](${d.url})`)
    .join('\n\n')

  await octokit.issues.createComment({
    owner: 'your-org',
    repo: 'your-repo',
    issue_number: prNumber,
    body: `## Visual Changes Detected\n\n${body}`,
  })
}

ビジュアルテストの並列実行

ビジュアルテストは、各テストが独立したスクリーンショットをキャプチャするため、本質的に並列化可能です。Playwrightは複数のCIランナーにわたるシャーディングをサポートしています：

strategy:
  matrix:
    shard: [1/4, 2/4, 3/4, 4/4]

steps:
  - name: Run visual tests
    run: npx playwright test --shard=${{ matrix.shard }}

これにより、ビジュアルテストの実行時間が4分の1になります（CI時間は4倍になります）。大規模なテストスイートでは、時間の節約に十分な価値があります。

キャッシュ戦略

ビジュアルテストの実行には重い処理が伴います：ブラウザのインストール、アプリのビルド、スクリーンショットのキャプチャ。スマートなキャッシュにより、CI時間を大幅に短縮できます：

ブラウザキャッシュ

Playwrightのブラウザバイナリを実行間でキャッシュします：

- uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: playwright-${{ hashFiles('package-lock.json') }}

ビルドキャッシュ

Next.jsのビルド出力をキャッシュして、テストファイルのみが変更された場合に再ビルドをスキップします。

ベースラインキャッシュ

ベースライン画像はGitに保存（推奨）するか、別のストレージバケットに保存します。Git保存ではベースラインがコードとともにバージョン管理されます。外部ストレージではリポジトリサイズが縮小されます。

ビジュアルテストの健全性を監視する

ビジュアルテストパイプラインの健全性を確保するために、以下のメトリクスを時系列で追跡します：

• 偽陽性率：失敗のうちノイズの割合はどのくらいか？
• 平均レビュー時間：ビジュアル差分がレビューされるまでどのくらいかかるか？
• カバレッジ：重要なUIパスのうちビジュアルテストがある割合はどのくらいか？
• フレーキネス率：テストが断続的に失敗する頻度はどのくらいか？

偽陽性率が10%を超えた場合は、閾値を調整するか、より多くのリージョンマスクを追加する時期です。平均レビュー時間が24時間を超える場合は、一定の差分閾値以下の変更に対する自動承認の追加を検討してください。

ScanUで始めましょう

これらのテクニックを本番環境で適用するには、まず対象を絞ったページセットから始め、意味のあるUI変更ごとにベースラインスクリーンショット比較を実行してください。Pricingでプランを確認し、FAQで実装の詳細を参照し、Featuresでプロダクトの機能をご覧ください。