Posted inAI

AIを活用したビジュアルテスト：PlaywrightとClaude 3.5 SonnetでUIリグレッションを検出する

AI tutorial - IT technology blog
AI tutorial - IT technology blog

脆いピクセルマッチングからの脱却

従来のユニットテストでは到底防げないCSSのリグレッション対応で、午後の時間を丸ごと潰してしまったことが何度もあります。多くのチームはピクセル単位のスナップショットテストに頼っていますが、これらのツールは驚くほど過敏です。

macOSとLinuxの間で発生するわずか1ピクセルのズレやアンチエイリアスの微妙な変化がビルドを失敗させ、誤報を引き起こします。ビジョンLLM、特にClaude 3.5 Sonnetは、このアプローチを根本から変えます。生のピクセルを比較する代わりに、人間のような視点でインターフェースを解釈するようAIに依頼するのです。

このテクニックを習得することは、基本的な自動化からインテリジェントな品質保証へとステップアップするための大きな一歩となります。Playwrightのブラウザ制御とClaudeの視覚的推論を組み合わせることで、テキストの重なり、アクセシビリティの欠如、レイアウトの崩れなどを特定できます。これらは、標準的なスクリプトが見落としがちな「ビジュアル負債」の典型例です。

クイックスタート：AIビジュアル監査の実行

実際に試すには、Node.js環境、AnthropicのAPIキー、そしてPlaywrightが必要です。このセットアップでは、アプリケーションの高解像度スクリーンショットをキャプチャし、構造的な批評のためにClaudeに渡します。

1. プロジェクトの初期化

mkdir visual-ai-tester
cd visual-ai-tester
npm init -y
npm i playwright @anthropic-ai/sdk dotenv

2. 検出スクリプトの作成

audit.jsという名前のファイルを作成します。このスクリプトはブラウザのロジックを処理し、画像バッファを生成し、AIに構造化された分析を要求します。

const { chromium } = require('playwright');
const Anthropic = require('@anthropic-ai/sdk');
require('dotenv').config();

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

async function runVisualAudit(url) {
    const browser = await chromium.launch();
    const page = await browser.newPage();
    await page.setViewportSize({ width: 1280, height: 800 });
    await page.goto(url, { waitUntil: 'networkidle' });
    
    const screenshot = await page.screenshot({ fullPage: false });
    const base64Image = screenshot.toString('base64');

    const response = await anthropic.messages.create({
        model: "claude-3-5-sonnet-20240620",
        max_tokens: 1024,
        messages: [{
            role: "user",
            content: [
                {
                    type: "image",
                    source: {
                        type: "base64",
                        media_type: "image/png",
                        data: base64Image,
                    },
                },
                {
                    type: "text",
                    text: "シニアQAエンジニアとして振る舞ってください。このUIスクリーンショットを分析し、要素の重なりやコントラスト不足などの視覚的なバグがないか確認してください。結果は 'has_bugs'（真偽値）と 'issues'（配列）を含むJSONオブジェクトで返してください。"
                }
            ],
        }],
    });

    console.log(response.content[0].text);
    await browser.close();
}

// ステージングサイトのURLを指定して実行
runVisualAudit('https://your-staging-site.com');

なぜ Claude 3.5 Sonnet なのか？

Claude 3.5 Sonnetは、その優れた空間認識能力により、UI分野で際立っています。他のモデルが「ボタンが存在する」ことを認識するのに対し、Claudeは要素間の関係性を理解します。例えば、「送信」ボタンが入力フィールドからわずか2ピクセルしか離れていない場合、Claudeはそれを「窮屈な」レイアウトとして特定します。ピクセルマッチングツールでは、ベースライン画像と異ならない限り、これを指摘することはできません。

最も効果的なプロンプティング戦略

信頼できる結果を得るための真のコツは、リクエストの枠組みにあります。単に「バグはありますか？」と尋ねるだけでは、曖昧で役に立たない回答につながります。代わりに、特定のデザインカテゴリを評価させる詳細なシステムプロンプトを使用します。

  • 視覚的階層（Visual Hierarchy）: 主要なアクションが二次的なものより目立っているか？
  • 整列（Alignment）: 要素が意図したグリッドシステムに従っているか？
  • カラーコントラスト: テキストは可読性に関するWCAG基準を満たしているか？
  • アセットの整合性: 壊れた画像アイコンや空のプレースホルダーはないか？

巨大なページと解像度の管理

ビジョンモデルには特定の解像度制限とトークンコストがあります。12,000ピクセルの巨大な垂直スクリーンショットを送信すると、詳細が失われたりリクエストが失敗したりする可能性があります。これを解決するために、ページを論理的なセクションに分割します。<nav>や.dashboard-gridといった特定のセレクターをターゲットにすることで、AIの集中力を維持し、コストを抑えることができます。

GitHub ActionsによるCI/CD統合

これらのチェックを自動化することで、ビジュアルリグレッションがユーザーに届くのを防ぐことができます。開発者がプルリクエストを開くたびにAI監査をトリガーするワークフローを設定できます。

ワークフロー設定の例

自動化されたゲートキーパーとして機能する .github/workflows/visual-qa.yml を作成します。

name: ビジュアルバグ検出
on: [push]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm install
      - run: npx playwright install --with-deps chromium
      - name: AI監査の実行
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          node audit.js > result.json
          if grep -q '"has_bugs": true' result.json; then
            echo "ビジュアルバグが検出されました！ログを確認してください。"
            exit 1
          fi

このパイプラインは、手動レビューの時間を大幅に削減します。人間がすべてのステージングリンクをチェックする代わりに、AIが最初のパス（一次審査）を提供します。Claudeが問題をフラグ立てした場合、ビルドは即座に失敗し、コードが本番環境に到達する前に開発者に通知されます。

本番環境に向けた実践的なTips

ローカルでの実験から本番グレードのツールへと移行するには、いくつかの最適化が必要です。エンタープライズワークフローにこれを導入して学んだ3つの教訓を紹介します。

1. コストの抑制

Claude 3.5 Sonnetは効率的ですが、すべてのコミットに対して実行するとコストがかさむ可能性があります。1回の監査につき約0.03ドルから0.05ドルかかると、開発スピードの速いチームではコストが急増します。監査のトリガーをプルリクエスト時に限定するか、特定のCSSやコンポーネントディレクトリに変更があった場合のみ実行することをお勧めします。

2. 動的データの取り扱い

動画の背景や回転するカルーセルなどの動的コンテンツは、AIを混乱させる可能性があります。誤検知を防ぐために、Playwrightの locator.evaluate() を使用して、撮影前にこれらの要素を非表示にします。動きのある動画を静的なグレーのボックスに置き換えることで、AIがレイアウトの安定性だけに集中できるようにします。

3. 「Human-in-the-Loop（人間による介在）」戦略

AIは時としてハルシネーション（幻覚）を起こしたり、批判的すぎたりすることがあります。人間によるレビュー経路を設けずに、AIだけでリリースをブロックさせることは避けるべきです。最善のアプローチは、スクリプトがAI監査の調査結果をGitHubのPRにコメントとして投稿するようにすることです。これにより、開発者はワンクリックでバグを確認したり、誤検知を却下したりできます。

テストスイートにビジョンLLMを統合することは単なるトレンドではありません。人間の目と従来のスクリプトの両方が見落としがちな、微妙なエラーをキャッチするための実用的な方法です。テスト1回につき数セントを費やすことで、将来的に数千ドルのコンバージョン損失を招く可能性のあるリグレッションを未然に防ぐことができるのです。

Share:
Tags: