visual-testing

ビジュアルテストスキル

スクリーンショット、レスポンシブテスト、Figma 連携を使用して、ビジュアルテスト、UI の検証、デザイン比較を行います。

使用する場面

このスキルは、次の場合に有効になります。

• ユーザーが UI の見た目を検証したい場合
• ページをデザインまたは Figma と比較したいとユーザーが求めた場合
• ユーザーがレスポンシブデザインのテストを必要としている場合
• ユーザーがビジュアルのリグレッションを確認したい場合
• ユーザーが UI のバグやスタイルの問題に言及した場合
• ユーザーがデザインとの一致度について尋ねた場合
• ユーザーが実装をデザインに照らして検証したい場合

機能

スクリーンショットの取得

browser-devtools-cli content take-screenshot --name "homepage"
browser-devtools-cli content take-screenshot --name "element" --selector ".hero"
browser-devtools-cli content take-screenshot --name "fullpage" --full-page
browser-devtools-cli content take-screenshot --name "photo" --type jpeg --quality 80
browser-devtools-cli content save-as-pdf --name "page" --format A4

注釈付きスクリーンショット（参照ラベル）

インタラクティブ要素に番号付きラベル [1]、[2] を重ねて表示します。最初に a11y take-aria-snapshot を呼び出してください。

browser-devtools-cli a11y take-aria-snapshot
browser-devtools-cli content take-screenshot --annotate --name "annotated"
browser-devtools-cli content take-screenshot --annotate --annotate-content --name "with-headings"

レスポンシブテスト

browser-devtools-cli interaction resize-viewport --width 375 --height 667   # Mobile
browser-devtools-cli interaction resize-viewport --width 768 --height 1024  # Tablet
browser-devtools-cli interaction resize-viewport --width 1920 --height 1080 # Desktop

Figma デザイン比較

browser-devtools-cli figma compare-page-with-design \
  --figma-file-key "ABC123xyz" \
  --figma-node-id "12:34"

browser-devtools-cli figma compare-page-with-design \
  --figma-file-key "ABC123xyz" \
  --figma-node-id "12:34" \
  --selector ".hero-section"

browser-devtools-cli figma compare-page-with-design \
  --figma-file-key "ABC123xyz" \
  --figma-node-id "12:34" \
  --mssim-mode semantic

DOM の調査

browser-devtools-cli content get-as-html
browser-devtools-cli content get-as-html --selector ".component"
browser-devtools-cli content get-as-text --selector ".content"

ビューポートのプリセット

デバイス	幅	高さ	コマンド
モバイル S	320px	568px	--width 320 --height 568
モバイル M	375px	667px	--width 375 --height 667
モバイル L	425px	812px	--width 425 --height 812
タブレット	768px	1024px	--width 768 --height 1024
ノート PC	1366px	768px	--width 1366 --height 768
デスクトップ	1920px	1080px	--width 1920 --height 1080

Figma 比較の前提条件

Figma API アクセス：

• FIGMA_ACCESS_TOKEN 環境変数を設定します
• Figma アカウントの設定からトークンを取得します

任意（比較を強化する場合）：

• 画像／テキスト埋め込み用の AWS 認証情報
• クラウド推論プロファイルの設定

ビジュアルテストのワークフロー

SESSION="--session-id visual-test"

# 1. Navigate
browser-devtools-cli $SESSION navigation go-to --url "https://example.com"
browser-devtools-cli $SESSION sync wait-for-network-idle

# 2. Capture desktop
browser-devtools-cli $SESSION content take-screenshot --name "desktop"

# 3. Test mobile viewport
browser-devtools-cli $SESSION interaction resize-viewport --width 375 --height 667
browser-devtools-cli $SESSION content take-screenshot --name "mobile"

# 4. Test tablet viewport
browser-devtools-cli $SESSION interaction resize-viewport --width 768 --height 1024
browser-devtools-cli $SESSION content take-screenshot --name "tablet"

# 5. Cleanup
browser-devtools-cli session delete visual-test

Figma 比較のワークフロー

1. Figma の参照を取得

Figma ファイルキーとノード ID を確認します。

• ファイルキー：URL figma.com/file/{FILE_KEY}/... から取得します
• ノード ID：フレームを選択 → リンクをコピー → node-id パラメーターを抽出します

2. 実際のページと比較

browser-devtools-cli figma compare-page-with-design \
  --figma-file-key "ABC123xyz" \
  --figma-node-id "12:34" \
  --selector ".hero-section"

3. 結果を分析

• スコア 0.9～1.0：非常によく一致
• スコア 0.7～0.9：軽微な差異
• スコア 0.5～0.7：大きな差異
• スコア < 0.5：大幅な不一致

4. 差異を調査

スコアが低い場合：

# Take screenshot of the area
browser-devtools-cli content take-screenshot --name "mismatch" --selector ".hero-section"

# Check HTML structure
browser-devtools-cli content get-as-html --selector ".hero-section"

比較モード

セマンティックモード（デフォルト）

• テキストやデータの差異を許容します
• レイアウトと構造に重点を置きます
• サンプルデータと実データの比較に適しています

browser-devtools-cli figma compare-page-with-design \
  --figma-file-key "ABC123" \
  --figma-node-id "1:2" \
  --mssim-mode semantic

生モード

• より厳密なピクセル比較を行います
• ほぼ同一の出力を想定します
• 静的コンテンツの比較に適しています

browser-devtools-cli figma compare-page-with-design \
  --figma-file-key "ABC123" \
  --figma-node-id "1:2" \
  --mssim-mode raw

よくあるシナリオ

ページ全体の比較

browser-devtools-cli figma compare-page-with-design \
  --figma-file-key "ABC123" \
  --figma-node-id "1:2" \
  --full-page

コンポーネントの比較

browser-devtools-cli figma compare-page-with-design \
  --figma-file-key "ABC123" \
  --figma-node-id "5:10" \
  --selector ".card-component"

Figma を使用したレスポンシブテスト

# Resize viewport first
browser-devtools-cli interaction resize-viewport --width 375 --height 667

# Then compare with mobile design
browser-devtools-cli figma compare-page-with-design \
  --figma-file-key "ABC123" \
  --figma-node-id "20:30"

よくあるビジュアルチェック

• ブレークポイントごとの要素の表示状態
• テキストのはみ出しや省略
• 画像のアスペクト比
• 色とタイポグラフィの一貫性
• 余白と配置
• インタラクティブ状態のスタイル

ベストプラクティス

1. 実データとサンプルデータの比較にはセマンティックモードを使用します
2. ページ全体だけでなく、コンポーネントを比較します
3. レスポンシブデザインでは複数のビューポートをテストします
4. CI/CD 用にFigma の参照を記録します
5. リグレッションテスト用にベースラインスコアを設定します
6. シグナルの詳細を確認するため、レスポンス内のメモを確認します
7. 重要な状態（初期、ホバー、アクティブ）でスクリーンショットを撮影します