test-web-ui

Web Tester Skill

あらゆる Web サイトやプロジェクトを、体系的な QA テストに変換します： 検出 → 計画 → 実行 → レポート

---

フェーズの概要

Phase 1 → DISCOVERY   : Explore the site, understand its purpose and features
Phase 2 → USE CASES   : Generate end-user use case list
Phase 3 → TEST PLAN   : Convert use cases into concrete, executable test cases
Phase 4 → EXECUTION   : Run tests with Playwright, capture screenshots
Phase 5 → REPORT      : Compile HTML + Markdown report with all results

---

実行ツールの選択

お使いの環境で利用できる、最初の選択肢を使用してください：

オプション 1：Playwright MCP ツール（推奨）

Playwright MCP ツール（例：mcp__plugin_playwright_playwright__*）を利用できる場合は、 これらを使用してください。最も高速で、トークン効率に優れた選択肢です（CLI より約 2.8 倍高速で、 各 MCP 呼び出しでより多くの処理が行われるため、必要なツール呼び出しも少なくなります）：

browser_navigate → navigate to URL
browser_snapshot → get page state and element refs
browser_take_screenshot → capture screenshots
browser_click → click elements
browser_type → type into inputs
browser_evaluate → run JS assertions
browser_resize → test mobile viewports
browser_console_messages → check for JS errors

オプション 2：Playwright CLI

@playwright/cli は、コーディングエージェント向けに 設計された CLI です。MCP ツールを利用できない場合に使用してください。 必要に応じてインストールします：

npm install -g @playwright/cli@latest

QA テストで使用する主なコマンド：

# Open a page
playwright-cli open https://example.com

# Take a snapshot (returns element refs for interaction)
playwright-cli snapshot

# Screenshot the page
playwright-cli screenshot

# Click, fill forms, type
playwright-cli click <ref>
playwright-cli fill <ref> "text value"
playwright-cli type "search query"
playwright-cli press Enter

# Mobile viewport testing — use a named session with mobile config
playwright-cli -s=mobile open https://example.com
# (configure viewport in .playwright/cli.config.json)

# Check console errors via snapshot output
playwright-cli snapshot

# Close when done
playwright-cli close

Playwright CLI はデフォルトでヘッドレスモードです。ブラウザーを画面上で確認するには、--headed を追加してください。 playwright-cli show を使用すると、すべてのアクティブなセッションのダッシュボードを開けます。

オプション 3：Python Playwright スクリプト

Python と Playwright がインストールされている場合は、scripts/ 内の付属スクリプトを使用してください：

# Install if needed
pip install playwright && playwright install chromium

# Run discovery
python scripts/discover.py --url <URL> --output discovery.json

# Run tests
python scripts/run_tests.py --url <URL> --test-plan test_plan.json --output test_results/

# Generate report
python scripts/generate_report.py --results test_results/results.json --output qa_report.html

オプション 4：手動テスト

上記のいずれも利用できない場合は、ソースコードを直接読み、手動で分析してください。基本的な HTTP チェックには、 curl または fetch を使用してください。

---

フェーズ 1：検出

収集する情報

• URL — ユーザーから稼働中の URL が提供された場合は、そこにアクセスして調査します
• プロジェクトファイル — 稼働中の URL がない場合は、プロジェクトディレクトリ内のソースファイルを調べます
• 目的 — サイトでは何ができますか？（ランディングページ、E コマース、ダッシュボード、ブログなど）
• 主要なページ — ホーム、認証、主な機能ページ、フォーム、チェックアウトなど
• 技術スタック — 任意ですが、対象を絞ったチェックに役立ちます

Playwright MCP による検出

1. browser_navigate to the URL
2. browser_snapshot to get the page structure
3. browser_take_screenshot for visual reference
4. Examine links, forms, headings, navigation from the snapshot
5. Navigate to discovered subpages and repeat

Playwright CLI による検出

playwright-cli open <URL>
playwright-cli screenshot --name discovery_home
playwright-cli snapshot
# Examine snapshot output for links, forms, navigation, headings
# Follow important links to discover subpages
playwright-cli goto <subpage-url>
playwright-cli screenshot --name discovery_subpage

Python スクリプトによる検出

python scripts/discover.py --url <URL> --max-pages 10 --output discovery.json

ローカルプロジェクト（稼働中の URL なし）

ソースファイルのみを利用できる場合：

1. ローカルサーバーを起動します：python -m http.server 8080 --directory <project-path> （または npx serve <project-path>、その他の静的サーバー）
2. http://localhost:8080 を対象に検出を実行します
3. ポートが使用中の場合は、8081、8082 などを試します

重要： file:// URL は一部のツールでブロックされることがあります。必ず HTTP で配信してください。

---

フェーズ 2：ユースケースの作成

検出後、エンドユーザーの視点からユースケースのリストを作成します。

形式

UC-01: [Actor] can [action] so that [goal]
UC-02: [Actor] can [action] so that [goal]
...

対象とするカテゴリ

• ナビゲーション — ページを閲覧できる、メニューが機能する、リンク先に移動できる
• 認証 — サインアップ、ログイン、パスワードのリセット、ログアウト
• 主要機能のフロー — サイトの主な機能（購入、検索、フォームの送信など）
• コンテンツの検証 — 必要なテキスト、画像、価格、ラベルが正しく表示される
• フォーム — 入力、送信、エラーの検証、成功状態の確認
• レスポンシブ対応 — モバイルのビューポートで機能する
• エラー処理 — 404 ページ、空の状態、無効な入力
• パフォーマンス／表示 — 画像の読み込みに失敗しない、コンソールエラーがない、読み込み時間が妥当
• アクセシビリティの基本 — 画像の alt テキスト、見出しの階層、ランドマーク要素

サイトの複雑さに応じて、10～25 件のユースケースを目指してください。

---

フェーズ 3：テスト計画

各ユースケースを具体的なテストケースに変換します：

TC-01 [UC-01]: Homepage Navigation
  Given: User opens the site root URL
  When:  Page finishes loading
  Then:  - Page title is not empty
         - Navigation menu is visible
         - Logo/brand element is present
         - No 404/500 status code
         Checks: title, nav links count > 0, hero text present

含めるテストケースの種類

種類	例
存在チェック	要素が存在する、テキストが表示される、画像が読み込まれる
機能チェック	ボタンをクリックできる、フォームを送信できる、メニューが展開する
データ検証	価格の形式、電話番号の形式、必須フィールド
ナビゲーションチェック	リンクが 404 にならない、ルーティングが機能する
フォーム検証	空の状態で送信するとエラーが表示される、有効な状態で送信すると成功する
レスポンシブ対応	モバイルのビューポートがオーバーフローせずに表示される
コンソールエラー	ページ読み込み時に JS エラーがない
アクセシビリティの基本	画像に alt テキストがある、見出しに階層がある、ランドマークがある

Python スクリプトを使用する場合は、テスト計画を test_plan.json として保存してください。JSON スキーマについては、 references/test_case_schema.md を参照してください。

フェーズ 4：テストの実行

使用するツールにかかわらず、各テストケースで次の手順に従います。

1. 移動 — 対象ページに移動します
2. 「実行前」のスクリーンショットを撮影
3. 手順を実行 — クリック、フォーム入力、スクロール、待機
4. アサーションを実行 — 要素の有無、テキストの内容、コンソールエラー、画像の読み込み
5. 操作を行った場合は「実行後」のスクリーンショットを撮影
6. 結果を記録 — PASS ／ FAIL ／ SKIP ＋ エラーメッセージ ＋ 所要時間

Playwright MCP での実行

browser_navigate to target URL
browser_take_screenshot for "before" capture
browser_snapshot to check element presence
browser_evaluate to run JS assertions:
  - document.title !== ''
  - document.querySelectorAll('nav').length > 0
  - document.querySelectorAll('img').filter(i => i.naturalWidth === 0).length
browser_click / browser_type for interactions
browser_take_screenshot for "after" capture
browser_console_messages to check for JS errors
browser_resize for mobile viewport testing

Playwright CLI での実行

# Navigate and screenshot
playwright-cli goto <URL>
playwright-cli screenshot --name tc01_before

# Get page state for assertions
playwright-cli snapshot
# Parse snapshot output to verify elements exist, text content matches, etc.

# Interact
playwright-cli click <ref>
playwright-cli fill <ref> "[email protected]"
playwright-cli press Enter

# After screenshot
playwright-cli screenshot --name tc01_after

モバイルビューポートのテストでは、モバイル用のサイズを指定して別のセッションを開くか、 ブラウザーのサイズを変更します。

ステータスコードのテスト（例：/404 が 404 を返すことの確認）には、playwright-cli による ナビゲーションを使用します。ツールは出力に HTTP ステータスを表示します。なお、 4xx／5xx ページへの移動で、一部のツールではエラーが発生することがあります。その場合は 適切にエラーを捕捉し、エラーメッセージからステータスコードを記録してください。

Python スクリプトでの実行

python scripts/run_tests.py \
  --url <URL> \
  --test-plan test_plan.json \
  --output test_results/

コンソールエラーの収集

コンソールエラーは重要な兆候です。各テスト中に収集してください。

• Playwright MCP：browser_console_messages または browser_evaluate を使用します
• Playwright CLI：スナップショットの出力を確認するか、playwright-cli の評価機能を使用します
• Python スクリプト：スクリプトはナビゲーションの前にコンソールリスナーを登録します

画像の読み込みチェック

壊れた画像を検出するには、ページ上で次の JS を実行します。

Array.from(document.images)
  .filter(img => img.naturalWidth === 0 && img.src && !img.src.startsWith('data:'))
  .map(img => img.src)

結果が空であれば、すべての画像が読み込まれています。それ以外の場合は、壊れた URL を一覧表示します。

アクセシビリティチェック

各ページで実行する簡易チェック：

// Images missing alt text
document.querySelectorAll('img:not([alt]), img[alt=""]').length

// Heading hierarchy (should have h1, not skip levels)
[...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].map(h => h.tagName)

// Landmark elements
document.querySelectorAll('main, nav, header, footer, [role]').length

---

フェーズ 5：レポートの生成

レポートの内容

• 概要ダッシュボード — テスト総数、合格／不合格／スキップ数、合格率（％）、テスト対象 URL、タイムスタンプ
• ユースケース一覧とテストケースとのトレーサビリティ
• テスト結果テーブル — TC ID、名前、ステータスバッジ、所要時間、エラーメッセージ
• スクリーンショットギャラリー — テストケースごとのインライン base64 スクリーンショット（またはファイルパス）
• コンソールエラーログ — 収集された JS エラー
• 推奨事項 — 失敗に基づいて自動生成される改善提案

レポート形式

• 主形式：HTML（埋め込みスクリーンショットを base64 形式で含む自己完結型）
• 副形式：Markdown による概要（すばやく確認するためのもの）

Python レポートジェネレーターの使用

python scripts/generate_report.py \
  --results test_results/results.json \
  --screenshots test_results/screenshots/ \
  --output qa_report.html

手動でのレポート生成

Python スクリプトが利用できない場合は、HTML レポートを直接生成します。 次の要素を含む自己完結型の HTML ファイルを作成します。

• サイト名、URL、タイムスタンプを記載した暗色のヘッダー
• 統計カード：テスト総数、合格、失敗、スキップ、合格率
• ステータスバッジ（緑の PASS、赤の FAIL、黄色の SKIP）付きの結果テーブル
• 埋め込みスクリーンショット（base64 エンコードされた PNG）
• 失敗に基づく推奨事項のセクション

レポートは、現在の作業ディレクトリ、またはユーザーが指定した場所に保存します。

---

ワークフローの概要（手順）

1. Receive URL or project files from user
2. Pick your execution tool (MCP > Playwright CLI > Python > Manual)
3. Run discovery → understand pages, structure, features
4. Generate use case list (10–25 use cases)
5. Generate test plan → structured test cases
6. Run tests → collect results + screenshots
7. Generate HTML report
8. Show the report path to the user

---

よくある状況への対応

ライブ URL のないローカルプロジェクト → ファイルをローカルで配信します：python -m http.server 8080 または npx serve . → http://localhost:8080 を対象にテストします → file:// URL は使用しないでください。ブロックされる場合があります

サイトで認証が必要 → ユーザーにテスト用認証情報を尋ねる、または → 公開ページのみをテストします → 認証が必要なテストは、注記を添えて SKIP にします

シングルページアプリ（React/Vue/Angular） → ページが完全に描画されるまで待機します（networkidle または特定のセレクター） → JS バンドルがコンソールエラーなしで読み込まれることを確認します → スナップショット／評価機能を使って、動的に描画されたコンテンツを検証します

大規模なサイト（ページ数が多い場合） → 重要なユーザーパスを優先します → 最も重要なフローを上位 5～10 件に絞ります → 対象外となったページをレポートに記載します

ステータスコードのテスト（4xx／5xx ページ） → 2xx 以外のレスポンスでエラーをスローするツールがあります → エラーを捕捉し、そこからステータスコードを抽出します → または、ナビゲーションせずにステータスコードを確認するため、JS の fetch() を使用します

モバイル対応のテスト → ビューポートを 390×844（iPhone）または 360×800（Android）に変更します → 水平方向のオーバーフローを確認します：document.body.scrollWidth > window.innerWidth → 重要な要素が引き続き表示され、読みやすいことを確認します

---

参照ファイル

• references/test_case_schema.md — test_plan.json の JSON スキーマ
• scripts/discover.py — サイト検出の自動化（Python + Playwright）
• scripts/run_tests.py — テスト実行エンジン（Python + Playwright）
• scripts/generate_report.py — HTML レポート生成ツール（Python）