qa-browser-automation

QA ブラウザー自動化

エージェントは Chrome MCP を操作してブラウザーのライブテストを行い、4 つの Python ツールを使って、再現性のある健全性スコアの算出、アクセシビリティ監査、ビジュアルリグレッションの追跡、レポートの生成を行います。

---

まず確認すること

QA の一連のチェックを始める前に、以下の入力を確定してください。不足している、または曖昧な入力によって結果が変わる場合は質問してください。結果が変わらない場合は、妥当な既定値を使い、使用した値を伝えてください。

• 対象 URL／アプリ＋認証情報： テスト対象とログイン方法（一連のチェック全体の対象です）。
• テストレベル： Quick／Standard／Deep／Exhaustive（範囲、ブレークポイント、所要時間を設定します）。
• 修正の自律性： P3／P4 を自動修正してコミットするか、レポートのみとするか／コード変更の前に確認するか（作業ツリーを変更するかどうかが変わります）。
• WCAG の目標レベル： A／AA／AAA（アクセシビリティの合格基準を設定します）。

リクエストに最も影響する 2〜3 項目について質問し、全項目を一度に尋ねないでください。ユーザーがすぐに結果を求めている場合は、前提を冒頭に示して結果を作成してください。

クイックスタート

# Score QA findings (0-100 weighted across 10 categories)
python scripts/qa_health_scorer.py findings.json --threshold 85 --baseline .qa-baselines/latest.json --save-baseline --json

# Audit HTML for WCAG 2.1 violations
python scripts/accessibility_auditor.py page.html --level AA --json

# Track visual regressions
python scripts/visual_regression_tracker.py --init --baseline-dir ./baselines
python scripts/visual_regression_tracker.py --register ./baselines
python scripts/visual_regression_tracker.py --baseline ./baselines --current ./screenshots --threshold 5

# Generate full QA report
python scripts/test_report_generator.py session_data.json --format markdown -o report.md

ツールの概要

ツール	入力	出力
qa_health_scorer.py	Findings JSON	スコア 0～100、グレード A～F、カテゴリ別の内訳、トレンドデータ
accessibility_auditor.py	HTML ファイル（または stdin）	レベル別の WCAG 違反と修正ガイダンス
visual_regression_tracker.py	ベースラインと最新のスクリーンショットディレクトリ	ページごとの合否、変更率
test_report_generator.py	セッションデータ JSON	推奨事項付きの Markdown または JSON レポート

健全性スコアラー、アクセシビリティ監査ツール、リグレッション追跡ツールは、機械処理用の出力に --json を指定します。レポート生成ツールでは --format json を使います。健全性スコアラーとリグレッション追跡ツールは、失敗時に終了コード 1 を返します（CI に適しています）。

---

ワークフロー 1：アプリケーション全体の QA チェック（11 フェーズ）

フェーズ 1〜2：事前確認と認証。

• git status がクリーンであることを確認します。変更があれば中止します。
• セッションディレクトリを作成します：.qa-sessions/{timestamp}/
• 必要に応じて Chrome MCP で認証します。

フェーズ 3〜4：全体の把握と調査。

• mcp__claude-in-chrome__read_page を使ってサイトマップ／ページマップを作成します。
• 各ルートに移動します。read_console_messages でエラーを、read_network_requests で 4xx／5xx を確認します。
• 有効なデータ、空の送信、境界値で、すべてのフォームをテストします。

フェーズ 5：状態のテスト。

• 読み込み状態（空白ではなくスケルトン画面）、空状態（最初のアクションへの案内）、エラー状態、成功状態、部分状態を確認します。
• 各操作につき 4 つの代替経路： 正常系、nil 入力、空の入力、上流のエラー。

フェーズ 6：デバイス間の確認とセキュリティ。

• 幅を 320px、768px、1024px、1440px、1920px に変更します。
• タッチターゲット（最小 44x44px）とレイアウトシフトを確認します。
• セキュリティヘッダー（CSP、HSTS、X-Frame-Options）と Cookie のフラグを確認します。

フェーズ 7〜8：記録とスコア算出。

• すべての検出事項をスクリーンショットの証拠とともに記録します。証拠のない検出事項は記録しません。
• 深刻度（P0〜P4）とカテゴリ（10 カテゴリ）で分類します。
• 次を実行します：python scripts/qa_health_scorer.py findings.json --baseline .qa-baselines/latest.json

フェーズ 9：トリアージと修正の反復。

• P3／P4：自動修正し、まとめてコミットして検証します。
• P0／P1／P2：確認を求め、証拠を提示し、修正案を提案して、承認を待ちます。
• 各修正後にチェックを再実行します。失敗した場合は git revert を実行します。
• 修正は 50 件で必ず停止します。

フェーズ 10〜11：リグレッションチェックとレポート。

• 修正したページを再確認します。新たなエラーがないことを検証します。
• スコアを次のベースラインとして保存します：python scripts/qa_health_scorer.py findings.json --save-baseline（.qa-baselines/{date}.json と .qa-baselines/latest.json に書き込みます）
• レポートを生成します：python scripts/test_report_generator.py session.json -o report.md

検証チェックポイント： 健全性スコアが 85 以上。P0 の検出事項がゼロ。WCAG AA が 95% 以上。

---

ワークフロー 2：ビジュアル回帰テスト

# Set up baseline
python scripts/visual_regression_tracker.py --init --baseline-dir ./baselines
# Capture and register screenshots
python scripts/visual_regression_tracker.py --register ./baselines
# After changes, compare
python scripts/visual_regression_tracker.py --baseline ./baselines --current ./screenshots --threshold 5 --json
# Accept intentional changes
python scripts/visual_regression_tracker.py --update-baseline --baseline ./baselines --current ./screenshots

しきい値（デフォルトは 5%）を超えるページは、回帰としてフラグが付けられます。トラッカーは、画像ファイルのデコード後のピクセルではなく、SHA-256 ハッシュと画像ファイルの生のバイト列を比較するため、変化率はおおまかな目安です。また、見た目が同一でも再エンコードされたスクリーンショットは、変更ありと判定されることがあります。

---

ワークフロー 3：アクセシビリティ監査

python scripts/accessibility_auditor.py page.html --level AA --json
curl -s https://example.com | python scripts/accessibility_auditor.py - --level AAA

レベルごとのチェック項目：

• A（要修正）： 代替テキスト、ページの言語、ページタイトル、見出しの階層、重複する ID、フォームのラベル、空のリンクテキスト、メディアのキャプションと自動再生、main と nav のランドマーク、正の tabindex
• AA（修正推奨）： outline:none で削除されたフォーカスインジケーターを追加し、インラインの色スタイルを持つ要素に手動でのコントラスト確認が必要なことを示します。ツールではスタイルを計算できないため、コントラスト比は測定されません
• AAA（できれば対応）： 「ここをクリック」のような一般的なリンクテキストを追加します（2.4.9）。強化コントラストの測定と読みやすさのレベルのチェックはないため、手動で確認してください

各違反には、WCAG 基準、重大度、要素セレクター、修正方法のガイダンスが含まれます。

---

テストティア

ティア	所要時間	対象範囲
クイック	30s	コンソールエラー、リンク切れ、基本的な a11y、モバイルでのリサイズ
標準	2-5 min	+ 上位 10 個のルート、フォーム、コントラスト、Core Web Vitals
ディープ	10-20 min	+ サイトマップ全体、状態テスト、WCAG AA、パフォーマンス、ビジュアル回帰、セキュリティヘッダー
徹底	30+ min	+ すべての要素、WCAG AAA、全ページのパフォーマンス、5 つのブレークポイント、認証のエッジケース、メモリーリーク

---

ヘルススコアリングシステム

10 個の重み付けカテゴリ、スコアは 0～100：

カテゴリ	重み	測定項目
機能性	18%	フォーム、CRUD、ナビゲーションフロー
アクセシビリティ	13%	WCAG 準拠、キーボード操作
コンソールエラー	12%	JS エラー、未処理の拒否
UX フロー	12%	論理的なナビゲーション、明確なフィードバック
パフォーマンス	12%	しきい値内の Core Web Vitals
ビジュアルの一貫性	10%	レイアウトシフト、配置、z-index
リンク切れ	8%	HTTP 4xx/5xx、リンク切れのアンカー
コンテンツ品質	5%	スペルミス、プレースホルダーテキスト、テキストの切り詰め
セキュリティヘッダー	5%	CSP、HSTS、Cookie フラグ
モバイル対応	5%	ブレークポイント、タッチターゲット、横スクロールなし

重大度による減点： P0：-30、P1：-18、P2：-10、P3：-4、P4：-1。

評価： A（90-100）、B（80-89）、C（70-79）、D（60-69）、F（0-59）。

---

安全制御

• 作業ツリーがクリーンであることが必須 -- git status が dirty の場合は中止します。
• 1 セッションにつき修正は最大 50 件 -- 上限に達したら即時停止します。
• リスク累積値 -- コンポーネント（+5）、スタイル（+2）、設定（+8）、取り消し（+15）。予算の 25% で停止します。
• WTF ヒューリスティック -- 修正の検証に 3 回連続で失敗した場合、すべての処理を停止します。
• アトミックコミット -- 1 件の修正につき 1 つのコミット：fix(qa): [P{severity}] {description}

---

トラブルシューティング

問題	原因	解決策
スコアラーがエラーなしでコード 1 を返して終了する	スコアが --threshold（デフォルトは 70）を下回っている	出力のスコアを確認し、しきい値を上げるか、検出事項を修正します
監査ツールが parse-error を報告する	HTML の形式が不正	ファイルが完全であることを確認し、curl がリダイレクトを返していないか確認します
回帰トラッカーがすべてのページで 100% の変更を報告する	ベースラインマニフェストが空	比較の前に --init を実行し、次に --register を実行します
検出事項がデフォルトで P3/機能性になる	severity または category キーがない	各 finding dict に両方のキーを含めます
SPA のナビゲーション後に Chrome MCP が古いコンテンツを返す	ページ全体を読み込まずに DOM が更新された	遷移を待ってから、もう一度 read_page を呼び出します

---

参考資料

ガイド	パス
ブラウザテストの方法論	references/browser_testing_methodology.md
WCAG 準拠ガイド	references/wcag_compliance_guide.md
パフォーマンスベンチマーク	references/performance_benchmarks.md

---

対象範囲と制限事項

対象範囲：

• Chrome MCP を通じて実施するライブ QA スイープです。ページの検出、コンソールとネットワークのエラー、フォーム、UI の状態、ブレークポイント、セキュリティヘッダーを、上記のテスト階層と安全対策に沿って確認します。
• qa_health_scorer.py を使用して、指摘事項の JSON から重み付けされた健全性スコアを算出します。0〜100 のスコア、A〜F の評価、10 個のカテゴリ、ベースラインの傾向を出力し、--threshold を下回る場合は終了コードを返します。
• 保存された HTML に対し、accessibility_auditor.py を使用してレベル A、AA、または AAA の静的 WCAG 2.1 チェックを実施します。
• visual_regression_tracker.py によるスクリーンショットのベースライン追跡と、test_report_generator.py による Markdown または JSON のセッションレポートを作成します。

対象外：

• 自動エンドツーエンドテストスイートの作成と保守（engineering/playwright-pro/ を参照）。
• スクリーンリーダーとキーボードのテストを含む、包括的なアクセシビリティプログラム（engineering/a11y-audit/ を参照）。
• 詳細なパフォーマンスプロファイリング（engineering/performance-profiler/ を参照）。
• ヘッダーと Cookie のチェックを超えるセキュリティテスト（engineering/security-audit/ を参照）。

重要な注意事項：

• Python ツールはブラウザーを開きません。ブラウザーでの作業には Chrome MCP が利用可能である必要があります。また、スコアラーとレポートジェネレーターは、手動またはエージェントが記録した指摘事項のみを処理します。
• accessibility_auditor.py は静的 HTML を解析します。スタイルを計算できないため、色のコントラストは測定されず、手動確認の対象として示されます。また、保存された HTML に含まれていない限り、JavaScript によって描画されたコンテンツは検出されません。
• visual_regression_tracker.py は画像ファイルのファイルハッシュとバイト列を比較し、ピクセルは比較しません。変更率はおおまかな指標であり、再エンコードされた同一のスクリーンショットでも変更ありと判定される場合があります。
• 修正ループではコードを編集してコミットします。上記のクリーンツリーチェック、修正上限、承認ルールによって制限されていますが、健全性スコアに合格しても、アプリケーションに欠陥がないとは限りません。

---

統合ポイント

スキル	統合
code-reviewer	PR レビューのコンテキストで健全性スコアと指摘事項を確認
senior-frontend	ビジュアル回帰のベースラインをコンポーネントライブラリに合わせる
senior-devops	終了コードを通じて健全性スコアを CI/CD のゲートとして使用
senior-secops	セキュリティヘッダーに関する指摘事項をセキュリティレビューにエスカレーション
incident-commander	P0 の指摘事項を受けてインシデント対応を開始

---

最終更新日： 2026年4月 バージョン： 2.1.0