playwright-visual-testing

Playwright によるビジュアルテストとブラウザー自動化

Playwright MCP サーバーとの連携を使用した、ブラウザー自動化とビジュアルテストの包括的なスキルです。このスキルを使うと、最新の Web アプリケーションの UI テスト、ビジュアルリグレッションの検出、ブラウザー操作の自動化、クロスブラウザー検証を迅速に実行できます。

このスキルを使用するタイミング

次のような場合にこのスキルを使用してください。

• 複数のブラウザー（Chromium、Firefox、WebKit）で Web アプリケーションをテストする場合
• UI の変更に対するビジュアルリグレッションテストを実装する場合
• QA やテストのためにユーザー操作を自動化する場合
• 異なるビューポートでレスポンシブデザインを検証する場合
• ドキュメントやバグ報告用のスクリーンショットを撮影する場合
• フォーム送信やユーザーワークフローをテストする場合
• Web インターフェースのアクセシビリティを確認する場合
• ブラウザー固有の問題をデバッグする場合
• 自動 E2E テストスイートを作成する場合
• デプロイ前に Web アプリケーションを検証する場合
• PWA やシングルページアプリケーションをテストする場合
• デザインレビュー用に画面の状態をキャプチャする場合

主なコンセプト

Playwright のブラウザー自動化の理念

Playwright は、最新の Web アプリ向けに信頼性の高いエンドツーエンドテストを提供します。

• 自動待機：操作可能になるまで要素を自動的に待ってから操作します
• Web ファーストのアサーション：アサーションが成功するかタイムアウトするまで再試行します
• クロスブラウザー：単一の API で Chromium、Firefox、WebKit をテストします
• アクセシビリティスナップショット：視覚的なレンダリングではなく、セマンティック構造を使用してページを操作します
• ビジュアルテスト：スクリーンショットを比較してビジュアルリグレッションを検出します
• ネットワーク制御：ネットワークリクエストをインターセプトしてモックします
• マルチコンテキスト：分離されたブラウザーコンテキストで複数のシナリオをテストします

Playwright の主なエンティティ

1. ブラウザー：ブラウザーのインスタンス（Chromium、Firefox、WebKit）
2. ページ：ブラウザー内の単一のページまたはタブ
3. ロケーター：アクセシビリティツリーを使用した要素セレクター
4. スナップショット：ページの状態を表すアクセシビリティツリー
5. スクリーンショット：ページまたは要素の視覚的なキャプチャ
6. ネットワークリクエスト：ページが実行する HTTP リクエスト
7. コンソールメッセージ：ブラウザーコンソールの出力
8. ダイアログ：ブラウザーのプロンプト、アラート、確認ダイアログ

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

1. 対象ページに移動します
2. ページが安定するまで待機します（アニメーション、読み込み）
3. 状況を把握するためにアクセシビリティスナップショットをキャプチャします
4. ページまたは特定の要素のスクリーンショットを撮影します
5. ベースラインと比較します（任意）
6. 見た目と機能を検証します
7. 結果と問題を記録します

Playwright MCP サーバーのツールリファレンス

ブラウザーのライフサイクル管理

browser_navigate

現在のページで URL に移動します。

パラメーター：

url: The URL to navigate to (required)

例：

url: "https://example.com"

ベストプラクティス：

• プロトコル（https://）を含む完全な URL を使用します
• 操作を開始する前に、ナビゲーションが完了するまで待機します
• リダイレクトやページ遷移に対応します

browser_navigate_back

履歴内の前のページに戻ります。

パラメーター： なし

例：

// Navigate back after clicking a link

使用例：

• ナビゲーションのフローをテストする
• 戻るボタンの動作を確認する
• 複数ステップのフォームのナビゲーションをテストする

browser_close

現在のブラウザーページを閉じます。

パラメーター： なし

使用するタイミング：

• テスト後にクリーンアップする
• システムリソースを解放する
• ブラウザーの状態をリセットする

browser_resize

ブラウザーのビューポートのサイズを変更します。

パラメーター：

width: Width in pixels (required)
height: Height in pixels (required)

一般的なビューポート：

// Mobile
width: 375, height: 667  // iPhone SE
width: 414, height: 896  // iPhone XR

// Tablet
width: 768, height: 1024  // iPad

// Desktop
width: 1280, height: 720  // HD
width: 1920, height: 1080 // Full HD

例：

width: 375
height: 667

ページの検査とスナップショット

browser_snapshot

現在のページのアクセシビリティスナップショットをキャプチャします。

パラメーター： なし

戻り値：

• セマンティック構造を含むアクセシビリティツリー
• 操作に使用する要素参照（ref）
• テキストコンテンツとロール
• インタラクティブな要素とその状態

スナップショットを使用する理由：

• 自動化ではスクリーンショットよりも優れています
• ページ構造をセマンティックに理解できます
• 正確な操作に使える要素参照を取得できます
• 視覚的な解析よりも高速です
• 視覚的なレンダリングなしで動作します

スナップショット構造の例：

heading "Welcome" [ref=123]
  text "to our site"
button "Sign In" [ref=456]
textbox "Email" [ref=789]
  value: ""

browser_take_screenshot

現在のページまたは要素のスクリーンショットを撮影します。

パラメーター：

filename: Output filename (optional, defaults to page-{timestamp}.png)
type: Image format - "png" or "jpeg" (default: png)
fullPage: Capture full scrollable page (default: false)
element: Human-readable element description (optional)
ref: Element reference from snapshot (optional, requires element)

スクリーンショットの種類：

1. ビューポートのスクリーンショット（デフォルト）：

filename: "homepage-viewport.png"

2. ページ全体のスクリーンショット：

filename: "homepage-full.png"
fullPage: true

3. 要素のスクリーンショット：

filename: "header.png"
element: "main header navigation"
ref: "123"

ベストプラクティス：

• コンテキストがわかる説明的なファイル名を使用します
• UI 要素には PNG を使用します（可逆圧縮）
• 写真や画像には JPEG を使用します（ファイルサイズが小さいため）
• ドキュメントにはページ全体のスクリーンショットを使用します
• 焦点を絞ったテストには要素のスクリーンショットを使用します

ブラウザー操作

browser_click

要素をクリックします。

パラメーター：

element: Human-readable element description (required)
ref: Element reference from snapshot (required)
button: "left", "right", or "middle" (default: left)
doubleClick: true for double-click (default: false)
modifiers: Array of modifier keys ["Alt", "Control", "ControlOrMeta", "Meta", "Shift"]

例：

1. 基本的なクリック：

element: "Submit button"
ref: "456"

2. 右クリック：

element: "Context menu trigger"
ref: "789"
button: "right"

3. 修飾キーを使ったクリック：

element: "Link to open in new tab"
ref: "123"
modifiers: ["ControlOrMeta"]

4. ダブルクリック：

element: "Word to select"
ref: "321"
doubleClick: true

browser_type

編集可能な要素にテキストを入力します。

パラメーター：

element: Human-readable element description (required)
ref: Element reference from snapshot (required)
text: Text to type (required)
slowly: Type one character at a time (default: false)
submit: Press Enter after typing (default: false)

例：

1. フォームへの入力：

element: "Email textbox"
ref: "123"
text: "[email protected]"

2. 検索して送信：

element: "Search field"
ref: "456"
text: "playwright testing"
submit: true

3. 1文字ずつ入力（キーイベントハンドラーを実行します）：

element: "Auto-complete input"
ref: "789"
text: "New York"
slowly: true

browser_press_key

キーボードキーを押します。

パラメーター：

key: Key name or character (required)

よく使うキー：

ArrowLeft, ArrowRight, ArrowUp, ArrowDown
Enter, Escape, Tab, Backspace, Delete
Home, End, PageUp, PageDown
F1-F12
Control, Alt, Shift, Meta

例：

// Navigation
key: "ArrowDown"

// Submit form
key: "Enter"

// Close dialog
key: "Escape"

// Tab through fields
key: "Tab"

browser_fill_form

複数のフォームフィールドに一度に入力します。

パラメーター：

fields: Array of field objects (required)
  - name: Human-readable field name
  - type: "textbox", "checkbox", "radio", "combobox", "slider"
  - ref: Element reference from snapshot
  - value: Value to set (string, "true"/"false" for checkboxes)

例：

fields: [
  {
    name: "Username",
    type: "textbox",
    ref: "123",
    value: "john_doe"
  },
  {
    name: "Password",
    type: "textbox",
    ref: "456",
    value: "secretpass123"
  },
  {
    name: "Remember me",
    type: "checkbox",
    ref: "789",
    value: "true"
  }
]

browser_select_option

ドロップダウンからオプションを選択します。

パラメーター：

element: Human-readable element description (required)
ref: Element reference from snapshot (required)
values: Array of values to select (required)

例：

element: "Country dropdown"
ref: "123"
values: ["United States"]

複数選択：

element: "Programming languages"
ref: "456"
values: ["JavaScript", "Python", "Go"]

browser_hover

要素にマウスカーソルを合わせます。

パラメーター：

element: Human-readable element description (required)
ref: Element reference from snapshot (required)

使用例：

• ツールチップを表示する
• ドロップダウンメニューを表示する
• ホバー時の状態をテストする
• 非表示の要素を表示する

例：

element: "Help icon"
ref: "123"

browser_drag

要素間でドラッグ＆ドロップします。

パラメーター：

startElement: Source element description (required)
startRef: Source element reference (required)
endElement: Target element description (required)
endRef: Target element reference (required)

例：

startElement: "Task card"
startRef: "123"
endElement: "Done column"
endRef: "456"

使用例：

• ドラッグ＆ドロップインターフェイス
• リストの並べ替え
• ファイルのアップロード
• カンバンボード

高度な操作

browser_evaluate

ページのコンテキストで JavaScript を実行します。

パラメーター：

function: JavaScript function as string (required)
element: Element description (optional)
ref: Element reference (optional, requires element)

例：

1. ページレベルのスクリプト：

function: "() => { return document.title; }"

2. 要素レベルのスクリプト：

element: "Custom widget"
ref: "123"
function: "(element) => { return element.getAttribute('data-value'); }"

一般的な使用例：

// Get page title
function: "() => document.title"

// Scroll to bottom
function: "() => window.scrollTo(0, document.body.scrollHeight)"

// Get element dimensions
function: "(element) => { const rect = element.getBoundingClientRect(); return { width: rect.width, height: rect.height }; }"

// Set local storage
function: "() => localStorage.setItem('theme', 'dark')"

// Get computed style
function: "(element) => getComputedStyle(element).backgroundColor"

browser_file_upload

ファイル入力にファイルをアップロードします。

パラメーター：

paths: Array of absolute file paths (required)
  - Omit or pass empty array to cancel file chooser

例：

paths: [
  "/Users/user/Documents/resume.pdf",
  "/Users/user/Photos/headshot.jpg"
]

単一ファイル：

paths: ["/Users/user/Downloads/report.csv"]

アップロードのキャンセル：

paths: []

ブラウザーの状態とデバッグ

browser_console_messages

ブラウザーのコンソールメッセージを取得します。

パラメーター：

onlyErrors: Return only error messages (default: false)

戻り値：

• すべての console.log、console.error、console.warn メッセージ
• タイムスタンプとメッセージの種類
• JavaScript エラーとスタックトレース

例：

1. すべてのメッセージ：

onlyErrors: false

2. エラーのみ：

onlyErrors: true

使用例：

• JavaScript エラーをデバッグする
• API の失敗を監視する
• コンソールの警告を追跡する
• ログ動作を確認する

browser_network_requests

ページの読み込み以降に発生したすべてのネットワークリクエストを取得します。

パラメーター： なし

戻り値：

• URL、メソッド、ステータスコード
• リクエスト／レスポンスヘッダー
• タイミング情報
• リクエスト／レスポンス本文

使用例：

• API 呼び出しを確認する
• リソースの読み込みを確認する
• 失敗したリクエストをデバッグする
• パフォーマンスを監視する
• アナリティクスのトラッキングを検証する

browser_handle_dialog

ブラウザーのダイアログに応答します。

パラメーター：

accept: Accept or dismiss dialog (required)
promptText: Text for prompt dialogs (optional)

ダイアログの種類：

• alert：情報メッセージ
• confirm：はい／いいえの選択
• prompt：テキスト入力の要求
• beforeunload：ページ遷移の警告

例：

1. アラートを承認：

accept: true

2. 確認ダイアログを閉じる：

accept: false

3. プロンプトに回答：

accept: true
promptText: "John Doe"

browser_wait_for

処理を進める前に、条件が満たされるまで待機します。

パラメーター：

text: Wait for text to appear (optional)
textGone: Wait for text to disappear (optional)
time: Wait for specified seconds (optional)

例：

1. テキストが表示されるまで待機：

text: "Loading complete"

2. 要素が削除されるまで待機：

textGone: "Loading..."

3. 指定時間待機：

time: 2

ベストプラクティス：

• 固定時間の待機より、特定の条件を待つ方法を優先します
• 動的コンテンツの読み込みに使用します
• アニメーションの完了を待ちます
• スクリーンショットを撮影する前に、ページが安定していることを確認します

タブ管理

browser_tabs

ブラウザーのタブを管理します。

パラメーター：

action: "list", "new", "close", "select" (required)
index: Tab index for close/select (optional)

アクション：

1. タブの一覧表示：

action: "list"

2. 新しいタブを開く：

action: "new"

3. タブを閉じる：

action: "close"
index: 1  // Optional, closes current if omitted

4. タブを切り替える：

action: "select"
index: 0

使用例：

• 複数タブを使うワークフロー
• タブ固有の機能のテスト
• リンクを新しいタブで開く
• 複数のセッションを管理する

ブラウザーのインストール

browser_install

設定で指定されたブラウザーをインストールします。

パラメーター： なし

使用する場面：

• 初回セットアップ
• 「ブラウザーがインストールされていません」というエラーが発生した場合
• ブラウザーのバージョンを更新する場合
• CI/CD 環境をセットアップする場合

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

パターン 1：基本的なビジュアルリグレッションテスト

シナリオ： ホームページの見た目に変更がないことを確認します

1. Navigate to page
   - Use browser_navigate with target URL
   - Wait for page to load completely

2. Capture baseline
   - Take full-page screenshot
   - Use browser_snapshot for context
   - Document visible elements

3. Make changes (if testing changes)
   - Update code, deploy
   - Clear cache

4. Capture new state
   - Navigate to same URL
   - Take identical screenshot
   - Compare manually or with tools

5. Validate differences
   - Expected changes present
   - No unexpected regressions
   - Document findings

パターン 2：レスポンシブデザインのテスト

シナリオ： デバイスごとにレイアウトをテストします

1. Define viewports
   - Mobile: 375x667 (iPhone SE)
   - Tablet: 768x1024 (iPad)
   - Desktop: 1920x1080 (Full HD)

2. For each viewport:
   a. Resize browser
      - browser_resize with dimensions

   b. Navigate to page
      - browser_navigate to URL

   c. Wait for layout
      - browser_wait_for with condition

   d. Capture snapshot
      - browser_snapshot for structure

   e. Take screenshot
      - browser_take_screenshot with descriptive name
      - Include viewport in filename

3. Compare layouts
   - Verify responsive breakpoints
   - Check element reflow
   - Validate mobile navigation
   - Ensure content accessibility

4. Document issues
   - Screenshot any problems
   - Note viewport where issue occurs
   - Record expected vs actual behavior

パターン 3：フォームテストのワークフロー

シナリオ： 複数ステップのフォーム送信をテストします

1. Navigate to form
   - browser_navigate to form URL
   - browser_snapshot to get field refs

2. Fill form fields
   - Use browser_fill_form for batch entry
   - Or individual browser_type for each field
   - Include validation triggers

3. Test validation
   - Submit with invalid data
   - browser_snapshot to see errors
   - Screenshot error states
   - Verify error messages appear

4. Complete valid submission
   - Fill all required fields
   - browser_click submit button
   - Wait for success message
   - browser_wait_for confirmation text

5. Verify results
   - Check success page
   - Verify data submission
   - Screenshot confirmation
   - Check network requests

パターン 4：要素ごとのビジュアルテスト

シナリオ： 個々のコンポーネントの変更をテストします

1. Navigate to component page
   - browser_navigate to page
   - browser_snapshot for structure

2. Locate component
   - Find element ref from snapshot
   - Verify component is visible

3. Test states
   a. Default state
      - Take element screenshot
      - Document initial appearance

   b. Hover state
      - browser_hover on element
      - Take element screenshot
      - Compare with default

   c. Active/focused state
      - browser_click on element
      - Take element screenshot
      - Verify visual feedback

   d. Error state (if applicable)
      - Trigger validation error
      - Take element screenshot
      - Verify error styling

4. Document state changes
   - Compare screenshots
   - Note expected behaviors
   - Report any issues

パターン 5：クロスブラウザーテスト

シナリオ： ブラウザー間で一貫性があることを確認します

1. Define browser matrix
   - Chromium (Chrome/Edge)
   - Firefox
   - WebKit (Safari)

2. For each browser:
   a. Configure browser
      - Set in MCP server config

   b. Run test suite
      - Navigate to pages
      - Capture snapshots
      - Take screenshots
      - Test interactions

   c. Document results
      - Save browser-specific screenshots
      - Note rendering differences
      - Log browser-specific bugs

3. Compare results
   - Side-by-side screenshots
   - Functionality differences
   - Performance variations
   - CSS rendering issues

4. Address discrepancies
   - Fix critical cross-browser bugs
   - Document acceptable differences
   - Add browser-specific styles if needed

パターン 6：E2E ユーザージャーニーテスト

シナリオ： ユーザーのワークフロー全体を検証します

1. Start journey
   - browser_navigate to landing page
   - browser_snapshot initial state
   - Screenshot starting point

2. Authentication
   - Navigate to login
   - Fill credentials with browser_fill_form
   - Submit form
   - Wait for redirect
   - Screenshot logged-in state

3. Main workflow steps
   For each step:
   - Take snapshot before action
   - Perform user action
   - Wait for completion
   - Take screenshot after action
   - Verify expected state

4. Complete transaction
   - Submit final action
   - Wait for confirmation
   - Screenshot success state
   - Verify completion message

5. Cleanup
   - Logout if needed
   - Screenshot final state
   - Document journey results

パターン 7：アクセシビリティのスナップショットテスト

シナリオ： セマンティック構造とアクセシビリティを確認します

1. Navigate to page
   - browser_navigate to URL

2. Capture accessibility snapshot
   - browser_snapshot for semantic tree
   - Review element roles
   - Check heading hierarchy
   - Verify labels and descriptions

3. Validate structure
   - Proper heading levels (h1 → h2 → h3)
   - Form inputs have labels
   - Buttons have accessible names
   - Interactive elements have roles
   - ARIA attributes present

4. Test keyboard navigation
   - browser_press_key "Tab"
   - Snapshot after each tab
   - Verify focus indicators
   - Ensure logical tab order
   - Test skip links

5. Test screen reader experience
   - Review snapshot text content
   - Verify alt text present
   - Check ARIA live regions
   - Validate semantic landmarks
   - Ensure meaningful structure

6. Document findings
   - Screenshot accessibility tree
   - Note missing labels
   - Report hierarchy issues
   - Suggest improvements

ブラウザー自動化のベストプラクティス

スクリーンショットのベストプラクティス

1. 一貫した命名規則

{page}-{viewport}-{state}-{timestamp}.png

Examples:
homepage-desktop-default-1634567890.png
login-mobile-error-1634567891.png
checkout-tablet-success-1634567892.png

2. ファイル名の整理

screenshots/
  ├── baselines/
  │   ├── homepage-desktop.png
  │   ├── homepage-mobile.png
  │   └── homepage-tablet.png
  ├── current/
  │   └── homepage-desktop-20251017.png
  └── diffs/
      └── homepage-desktop-diff-20251017.png

3. ページ全体とビューポート

• ドキュメントにはページ全体を使用します
• リグレッションテストにはビューポートを使用します
• コンポーネントには要素のスクリーンショットを使用します
• ページ全体をキャプチャする場合は、ページの長さを考慮します

4. 画像形式の選択

• PNG：UI 要素、テキスト、輪郭が鮮明な画像（可逆圧縮）
• JPEG：写真、背景、大きな画像（ファイルサイズが小さい）
• テストではデフォルトで PNG を使用します

スナップショットとスクリーンショットの使い分け

スナップショットを使用する場面：

• 操作を自動化する場合
• 機能をテストする場合
• 構造を確認する場合
• アクセシビリティを確認する場合
• 要素の参照が必要な場合
• 動的コンテンツをテストする場合

スクリーンショットを使用する場面：

• ビジュアルリグレッションテスト
• ドキュメント作成
• バグ報告
• デザインレビュー
• ステークホルダーへのプレゼンテーション
• 視覚的な比較

両方を使用する場面：

• 包括的なテスト
• ビジュアルの問題のデバッグ
• テストレポートの作成
• 複雑なフローの記録

待機方法

1. 特定の要素を待機

// Good
browser_wait_for with text: "Data loaded"

// Avoid
browser_wait_for with time: 5

2. アニメーションを待機

// Wait for loading spinner to disappear
browser_wait_for with textGone: "Loading..."

3. ネットワークがアイドル状態になるのを待機

// Check network requests after waiting
browser_network_requests to verify completion

4. 動的コンテンツ

// Wait for specific text before screenshot
browser_wait_for with text: "Results: 42 items"

操作の信頼性

1. 必ず最初にスナップショットを使用

1. browser_snapshot
2. Find element ref in snapshot
3. Use ref for interaction
4. Never guess element references

2. 要素の状態を確認

// Take snapshot to verify element exists
// Check element is visible and actionable
// Then perform interaction

3. 動的な要素を処理

// Wait for element to appear
browser_wait_for with text: "Submit"
// Then take fresh snapshot
browser_snapshot
// Get updated ref and interact

4. エラーからの復旧

// If interaction fails:
1. Take screenshot of current state
2. Capture console messages (browser_console_messages)
3. Check network requests (browser_network_requests)
4. Take new snapshot to see current state

フォームテストの方針

1. 一括入力と個別入力

// Batch for simple forms (faster)
browser_fill_form with all fields

// Individual for complex forms (better control)
browser_type for each field
browser_wait_for after each entry
Verify validation triggers

2. 検証テスト

// Test each validation rule
1. Enter invalid data
2. Attempt submission
3. Snapshot to see errors
4. Screenshot error messages
5. Correct data
6. Verify error clears

3. 複数ステップのフォーム

// Document each step
1. Fill step 1
2. Screenshot before submit
3. Click next
4. Wait for step 2
5. Snapshot new state
6. Repeat for each step

ネットワークの監視

1. API 呼び出しを追跡

// After user action
browser_network_requests
// Verify expected endpoints called
// Check status codes
// Validate request/response data

2. パフォーマンステスト

// Capture network timing
browser_network_requests
// Analyze:
- Request count
- Total transfer size
- Response times
- Failed requests

3. 失敗したリクエストをデバッグ

browser_network_requests
// Find failed requests
// Check error messages
// Screenshot current state
// Console messages for errors

開発を加速するための戦略

戦略 1：テストテンプレートの作成

再利用可能なテストパターンを作成します：

Visual Regression Test Template:
1. Navigate: browser_navigate to {URL}
2. Wait: browser_wait_for for {condition}
3. Baseline: browser_take_screenshot "baseline-{name}.png", fullPage: true
4. [Make changes]
5. Capture: browser_take_screenshot "current-{name}.png", fullPage: true
6. Compare: [Manual or automated comparison]
7. Document: Screenshot any differences

Responsive Test Template:
For viewport in [mobile, tablet, desktop]:
  1. Resize: browser_resize to {viewport dimensions}
  2. Navigate: browser_navigate to {URL}
  3. Wait: browser_wait_for for stability
  4. Snapshot: browser_snapshot
  5. Screenshot: browser_take_screenshot "{page}-{viewport}.png"
  6. Validate: Check layout integrity

Form Test Template:
1. Navigate: browser_navigate to {form URL}
2. Snapshot: browser_snapshot for refs
3. Fill: browser_fill_form with test data
4. Screenshot: "form-filled.png"
5. Submit: browser_click submit button
6. Wait: browser_wait_for for result
7. Verify: Snapshot and screenshot result
8. Check: browser_network_requests for submission

戦略 2：スクリーンショットの自動整理

スクリーンショットを体系的に整理します：

Project Structure:
tests/
  visual/
    baselines/        # Reference screenshots
    results/          # Current test screenshots
    diffs/            # Difference images
    reports/          # HTML reports with comparisons

Naming Convention:
{test-name}_{viewport}_{state}_{date}.png

Examples:
login_desktop_default_20251017.png
cart_mobile_empty_20251017.png
checkout_tablet_error_20251017.png

Metadata File:
screenshot-metadata.json:
{
  "screenshot": "login_desktop_default_20251017.png",
  "timestamp": "2025-10-17T10:30:00Z",
  "url": "https://example.com/login",
  "viewport": {"width": 1920, "height": 1080},
  "browser": "chromium",
  "test": "login_flow",
  "passed": true
}

戦略 3：複数ブラウザーでの並列テスト

ブラウザー間で効率よくテストします：

Browser Matrix:
- Chromium (latest)
- Firefox (latest)
- WebKit (latest)

Parallel Execution:
1. Define test suite
2. Configure each browser
3. Run tests in parallel
4. Collect results
5. Compare across browsers
6. Generate cross-browser report

Result Organization:
screenshots/
  chromium/
    homepage.png
    login.png
  firefox/
    homepage.png
    login.png
  webkit/
    homepage.png
    login.png
  comparison/
    homepage-browsers.html
    login-browsers.html

戦略 4：ビジュアルリグレッションの自動化

ビジュアル比較のワークフローを自動化します：

1. Capture Baselines (one-time):
   - Navigate to each page
   - Take reference screenshots
   - Store in baselines/

2. Run Visual Tests:
   - Navigate to each page
   - Take current screenshots
   - Store in results/

3. Compare Images:
   - Pixel-by-pixel comparison
   - Highlight differences
   - Generate diff images
   - Calculate similarity score

4. Generate Report:
   - List all comparisons
   - Show side-by-side views
   - Highlight failures
   - Include metrics

5. Review and Update:
   - Review failures
   - Accept intentional changes
   - Update baselines
   - Fix regressions

戦略 5：コンポーネントライブラリのテスト

デザインシステムのコンポーネントをテストします：

Component Test Suite:
For each component:
  1. Navigate to component page
  2. Snapshot for structure
  3. Test each variant:
     - Default
     - Hover
     - Active
     - Disabled
     - Error
  4. Screenshot each state
  5. Verify accessibility
  6. Check responsive behavior

Documentation Generation:
1. Capture all component states
2. Organize by component
3. Generate visual catalog
4. Include code examples
5. Document usage guidelines

Example:
components/
  Button/
    button-default.png
    button-hover.png
    button-active.png
    button-disabled.png
    button-error.png
  Input/
    input-default.png
    input-focus.png
    input-error.png
    input-disabled.png

トラブルシューティング

よくある問題

スクリーンショットが空白に見える

• ページの読み込みを待ちます：browser_wait_for
• 要素が表示されているか確認します：browser_snapshot
• ページがレンダリングされていることを確認します：遅延を追加します
• URLが正しいことを確認します

操作対象の要素が見つからない

• 最新のスナップショットを取得します：browser_snapshot
• 要素の参照が最新であることを確認します
• 要素が表示されるまで待ちます：browser_wait_for
• スナップショットに要素が存在することを確認します

ブラウザーが起動しない

• browser_install を実行します
• MCP サーバーの設定を確認します
• ブラウザーのバイナリパスを確認します
• システムの権限を確認します

スクリーンショットが想定と異なる

• ビューポートのサイズを確認します：browser_resize
• アニメーションが終わるまで待ちます：browser_wait_for
• フォントの読み込みが完了していることを確認します
• 動的コンテンツ（タイムスタンプ、広告）を無効にします

フォームの送信に失敗する

• 必須項目がすべて入力されていることを確認します
• 入力検証エラーを確認します：browser_snapshot
• 送信ボタンが有効になるまで待ちます
• コンソールで JavaScript エラーを確認します：browser_console_messages

ネットワークリクエストが取得されない

• 操作後に browser_network_requests を呼び出します
• ページのリクエストが完了していることを確認します
• リクエストの失敗がないか確認します
• リクエストのタイミングを確認します

ダイアログが処理されない

• ダイアログを表示する前に browser_handle_dialog を設定します
• 適切に承認または却下します
• プロンプトダイアログには promptText を指定します
• 事前にダイアログをテストします

デバッグのワークフロー

1. 現在の状態を取得

1. browser_snapshot - See page structure
2. browser_take_screenshot - See visual state
3. browser_console_messages onlyErrors: true - Check errors
4. browser_network_requests - See network activity

2. 問題を切り分ける

1. Simplify test to minimum reproduction
2. Test in single browser
3. Disable dynamic content
4. Remove variable elements
5. Test step-by-step

3. 問題を記録する

1. Screenshot before issue
2. Screenshot at failure point
3. Capture console messages
4. Save network requests
5. Note expected vs actual
6. Include reproduction steps

実践的な例

例 1：ホームページのビジュアルリグレッション

ホームページの見た目に変更がないことをテストします：

1. Navigate
   browser_navigate
   url: "https://example.com"

2. Wait for page load
   browser_wait_for
   textGone: "Loading..."

3. Capture baseline
   browser_take_screenshot
   filename: "homepage-baseline.png"
   fullPage: true

4. [After code changes, repeat]

5. Capture current
   browser_take_screenshot
   filename: "homepage-current.png"
   fullPage: true

6. Compare images manually or with tools
7. Document differences

例 2：ログインフォームのテスト

ログインフォームの機能をテストします：

1. Navigate to login
   browser_navigate
   url: "https://example.com/login"

2. Get form structure
   browser_snapshot

3. Fill form
   browser_fill_form
   fields: [
     {
       name: "Email",
       type: "textbox",
       ref: "123",
       value: "[email protected]"
     },
     {
       name: "Password",
       type: "textbox",
       ref: "456",
       value: "password123"
     }
   ]

4. Screenshot filled form
   browser_take_screenshot
   filename: "login-filled.png"

5. Submit
   browser_click
   element: "Sign In button"
   ref: "789"

6. Wait for redirect
   browser_wait_for
   text: "Welcome back"

7. Screenshot success
   browser_take_screenshot
   filename: "login-success.png"

8. Verify network request
   browser_network_requests

例 3：レスポンシブデザインの確認

レスポンシブレイアウトをテストします：

Mobile:
1. Resize to mobile
   browser_resize
   width: 375
   height: 667

2. Navigate
   browser_navigate
   url: "https://example.com"

3. Wait
   browser_wait_for
   time: 2

4. Screenshot
   browser_take_screenshot
   filename: "homepage-mobile.png"
   fullPage: true

Tablet:
5. Resize to tablet
   browser_resize
   width: 768
   height: 1024

6. Navigate
   browser_navigate
   url: "https://example.com"

7. Screenshot
   browser_take_screenshot
   filename: "homepage-tablet.png"
   fullPage: true

Desktop:
8. Resize to desktop
   browser_resize
   width: 1920
   height: 1080

9. Navigate
   browser_navigate
   url: "https://example.com"

10. Screenshot
    browser_take_screenshot
    filename: "homepage-desktop.png"
    fullPage: true

例 4：コンポーネントの状態テスト

ボタンの状態をテストします：

1. Navigate to component library
   browser_navigate
   url: "https://example.com/components/button"

2. Get page structure
   browser_snapshot

3. Default state
   browser_take_screenshot
   filename: "button-default.png"
   element: "Primary button"
   ref: "123"

4. Hover state
   browser_hover
   element: "Primary button"
   ref: "123"

   browser_take_screenshot
   filename: "button-hover.png"
   element: "Primary button"
   ref: "123"

5. Active state
   browser_click
   element: "Primary button"
   ref: "123"

   browser_take_screenshot
   filename: "button-active.png"
   element: "Primary button"
   ref: "123"

6. Snapshot for verification
   browser_snapshot

例 5：E2E チェックアウトのフロー

チェックアウトの一連のプロセスをテストします：

1. Navigate to product
   browser_navigate
   url: "https://example.com/products/item-123"

2. Add to cart
   browser_snapshot

   browser_click
   element: "Add to Cart button"
   ref: "456"

   browser_wait_for
   text: "Added to cart"

3. Go to cart
   browser_click
   element: "Cart icon"
   ref: "789"

   browser_take_screenshot
   filename: "cart-with-item.png"

4. Proceed to checkout
   browser_click
   element: "Checkout button"
   ref: "101"

5. Fill shipping info
   browser_snapshot

   browser_fill_form
   fields: [
     {name: "Name", type: "textbox", ref: "111", value: "John Doe"},
     {name: "Address", type: "textbox", ref: "222", value: "123 Main St"},
     {name: "City", type: "textbox", ref: "333", value: "New York"},
     {name: "Zip", type: "textbox", ref: "444", value: "10001"}
   ]

6. Screenshot checkout
   browser_take_screenshot
   filename: "checkout-filled.png"
   fullPage: true

7. Complete order
   browser_click
   element: "Place Order button"
   ref: "555"

   browser_wait_for
   text: "Order confirmed"

8. Screenshot confirmation
   browser_take_screenshot
   filename: "order-confirmed.png"
   fullPage: true

9. Verify network requests
   browser_network_requests

例 6：アクセシビリティテスト

キーボード操作と構造をテストします：

1. Navigate to page
   browser_navigate
   url: "https://example.com/form"

2. Capture semantic structure
   browser_snapshot

3. Verify heading hierarchy
   - Check h1 → h2 → h3 order
   - Ensure single h1
   - Verify logical structure

4. Test keyboard navigation
   browser_press_key
   key: "Tab"

   browser_snapshot

   browser_take_screenshot
   filename: "focus-field-1.png"

5. Continue tabbing
   browser_press_key
   key: "Tab"

   browser_snapshot

   browser_take_screenshot
   filename: "focus-field-2.png"

6. Verify all interactive elements reachable
   - Buttons
   - Links
   - Form fields
   - Custom widgets

7. Check ARIA labels
   - Form labels present
   - Button labels descriptive
   - Error messages announced
   - Status updates live

8. Screenshot accessibility tree
   browser_take_screenshot
   filename: "accessibility-structure.png"

例 7：ネットワークのデバッグ

失敗した API 呼び出しをデバッグします：

1. Navigate to page
   browser_navigate
   url: "https://example.com/dashboard"

2. Wait for page
   browser_wait_for
   time: 3

3. Check console errors
   browser_console_messages
   onlyErrors: true

4. Check network requests
   browser_network_requests

5. Find failed requests
   - Status: 4xx or 5xx
   - Timeout errors
   - CORS issues

6. Screenshot error state
   browser_take_screenshot
   filename: "api-error-state.png"

7. Retry action
   browser_click
   element: "Refresh button"
   ref: "123"

8. Monitor new requests
   browser_network_requests

9. Document findings
   - Failed endpoint
   - Error message
   - Request/response data
   - Screenshot

例 8：ダイアログの処理

確認ダイアログをテストします：

1. Navigate to page
   browser_navigate
   url: "https://example.com/settings"

2. Trigger delete action
   browser_snapshot

   browser_click
   element: "Delete Account button"
   ref: "123"

3. Handle confirmation
   browser_handle_dialog
   accept: false  # Cancel first time

4. Verify still on page
   browser_snapshot

5. Try again
   browser_click
   element: "Delete Account button"
   ref: "123"

6. Accept this time
   browser_handle_dialog
   accept: true

7. Wait for result
   browser_wait_for
   text: "Account deleted"

8. Screenshot confirmation
   browser_take_screenshot
   filename: "account-deleted.png"

例 9：タブの管理

複数タブのワークフローをテストします：

1. List current tabs
   browser_tabs
   action: "list"

2. Open link in new tab
   browser_click
   element: "Privacy Policy link"
   ref: "123"
   modifiers: ["ControlOrMeta"]

3. Switch to new tab
   browser_tabs
   action: "select"
   index: 1

4. Screenshot new tab
   browser_take_screenshot
   filename: "privacy-policy.png"

5. Switch back
   browser_tabs
   action: "select"
   index: 0

6. Close extra tab
   browser_tabs
   action: "close"
   index: 1

7. Verify single tab
   browser_tabs
   action: "list"

例 10：アニメーションのテスト

読み込みアニメーションをテストします：

1. Navigate to page
   browser_navigate
   url: "https://example.com/data-heavy"

2. Screenshot loading state
   browser_take_screenshot
   filename: "loading-spinner.png"

3. Wait for loading to complete
   browser_wait_for
   textGone: "Loading..."

4. Wait for animations
   browser_wait_for
   time: 1

5. Screenshot final state
   browser_take_screenshot
   filename: "content-loaded.png"
   fullPage: true

6. Verify stability
   browser_wait_for
   time: 2

   browser_take_screenshot
   filename: "stable-state.png"
   fullPage: true

7. Compare screenshots
   - loading-spinner.png
   - content-loaded.png
   - stable-state.png

クイックリファレンス

主要なコマンド

Navigate:
  browser_navigate url: "{URL}"

Snapshot:
  browser_snapshot

Screenshot:
  browser_take_screenshot filename: "{name}.png"

Full Page Screenshot:
  browser_take_screenshot filename: "{name}.png", fullPage: true

Element Screenshot:
  browser_take_screenshot filename: "{name}.png", element: "{description}", ref: "{ref}"

Click:
  browser_click element: "{description}", ref: "{ref}"

Type:
  browser_type element: "{description}", ref: "{ref}", text: "{text}"

Fill Form:
  browser_fill_form fields: [{name, type, ref, value}, ...]

Wait:
  browser_wait_for text: "{text}"
  browser_wait_for textGone: "{text}"
  browser_wait_for time: {seconds}

Resize:
  browser_resize width: {width}, height: {height}

Console:
  browser_console_messages onlyErrors: true

Network:
  browser_network_requests

一般的なビューポートサイズ

Mobile:
  375 x 667   (iPhone SE)
  390 x 844   (iPhone 12/13/14)
  414 x 896   (iPhone 11 Pro Max)
  360 x 640   (Android Small)
  412 x 915   (Android Large)

Tablet:
  768 x 1024  (iPad Portrait)
  1024 x 768  (iPad Landscape)
  810 x 1080  (Android Tablet)

Desktop:
  1280 x 720  (HD)
  1366 x 768  (Laptop)
  1920 x 1080 (Full HD)
  2560 x 1440 (2K)
  3840 x 2160 (4K)

テスト構成のテンプレート

tests/
  ├── visual/
  │   ├── baselines/
  │   ├── results/
  │   └── diffs/
  ├── e2e/
  │   ├── auth/
  │   ├── checkout/
  │   └── navigation/
  ├── responsive/
  │   ├── mobile/
  │   ├── tablet/
  │   └── desktop/
  └── components/
      ├── buttons/
      ├── forms/
      └── navigation/

reports/
  ├── visual-regression.html
  ├── cross-browser.html
  └── accessibility.html

リソース

• Playwright のドキュメント
• Playwright API リファレンス
• Playwright MCP サーバー
• ビジュアルテストガイド
• ベストプラクティス
• アクセシビリティテスト

---

スキルのバージョン: 1.0.0 最終更新日: 2025年10月 スキルのカテゴリ: ブラウザー自動化、ビジュアルテスト、品質保証 対応環境: Playwright MCP Server、Chromium、Firefox、WebKit