cross-browser-testing

Chrome だけのテストでは、誤った安心感につながります。Chromium で動作するレイアウトが WebKit では崩れたり、Chrome では成功するクリップボード呼び出しが Firefox では何もせずに失敗したり、分割された Cookie のフローが、ユーザーが使っている唯一のエンジン以外ではすべて通ったりすることがあります。このスキルでは、分析データに基づくブラウザマトリックス、それを実行する Playwright（またはクラウドプラットフォーム）の設定、既知のブラウザ間の差異を記録したコミット済みログを作成します。それぞれの差異は CSS ではなく、ユーザーが得る結果を検証するテストで確認します。

クイックルート

状況	参照先
テスト対象のブラウザを決める必要がある	ブラウザマトリックスの設計
すでに Playwright を使用していて、ブラウザを追加するだけ	Playwright のブラウザ設定 → references/playwright-and-cloud-config.md
エンジンではなく、実際の Safari／Windows／旧 OS が必要	クラウドプラットフォームの設定
あるブラウザの動作に問題があり、そのテストを作成したい	クロスブラウザでよくある問題と、references/testing-patterns.md の browserName 分岐
差異を記録して、再度デバッグすることを避けたい	既知の問題のログ
ピクセル差分／ベースラインのしきい値	visual-testing を使用

調査時の質問

まず .agents/qa-project-context.md を確認してください。ファイルが存在する場合はその内容を使い、すでに回答されている項目はスキップしてください。その後、次の項目を確認します。

1. 分析データに基づく対象ブラウザ： 実際のユーザーは何を使っていますか？分析ツールからブラウザ／OS のデータを取得してください。誰も使っていないブラウザのテストは無駄です。ユーザーの 15％が依存しているブラウザを見落とせば、それはバグです。
2. デスクトップとモバイルの両方が必要ですか？ iOS の Mobile Safari と Android の Chrome は、それぞれのデスクトップ版とは異なるレンダリングを行います。マトリックスでは別々の項目として扱ってください。
3. クラウドプラットフォーム： BrowserStack、Sauce Labs、LambdaTest、それともローカルエンジンのみですか？クラウドプラットフォームでは、実際のブランドのブラウザと OS を利用できます。Playwright に同梱されているエンジンで対応しているのは Chromium、Firefox、WebKit であり、Chrome や Safari そのものではありません。
4. プログレッシブエンハンスメントですか、それともピクセルパーフェクトですか？ プログレッシブエンハンスメントでは、適切な機能低下を許容します。ピクセルパーフェクトでは、同一のレンダリングが求められます。この答えによって合否基準が決まります。
5. 既存の Playwright 設定はありますか？ プロジェクトですでに Playwright を使っている場合、クロスブラウザテストは新しいツールを導入するのではなく、設定を変更するだけで実現できます。

---

基本原則

1. 分析データに基づくマトリックス。 ユーザーが実際に使っているブラウザをテストしてください。トラフィックの 0.3％を占めるブラウザに、40％を占めるブラウザと同じだけの投資をする必要はありません。ブラウザのシェアは変化するため、分析データを四半期ごとに確認してください。

2. ピクセルパーフェクトよりもプログレッシブエンハンスメント。 すべてのブラウザで同一のレンダリングを実現することは不可能であり、必要でもありません。「動作する」とは何かを定義してください。つまり、主要な機能が動き、コンテンツにアクセスでき、レイアウトが使いやすいことです。影、グラデーション、アニメーションのタイミングに見られる違いは許容できます。

3. クロスブラウザのバグが最も見つかりやすいのは Safari と Firefox です。 Chrome だけのテストで見つかるのは Chrome のバグです。Safari の WebKit エンジンと Firefox の Gecko エンジンは、Chromium との動作の違いが最も多いため、優先してください。

4. レンダリングエンジンの内部ではなく、機能をテストする。 クロスブラウザテストでは、CSS プロパティが同じようにレンダリングされるかではなく、ユーザーがタスクを完了できるかを検証してください。ピクセルレベルの違いは、ビジュアル比較ツールで扱います。

5. エンジンとブランドは別物です。 Playwright の WebKit は Safari ではなく、Chromium は Chrome ではありません。共有しているのはエンジンであり、出荷される製品ではありません（コーデック、フォント、企業向けポリシー、更新サイクルなどが異なります）。クラウドのグリッドで実際の Safari を実行していない限り、「Safari のカバレッジ」ではなく「WebKit のカバレッジ」と報告してください。

6. 1 つのテストを複数のブラウザで実行する。 テストは一度だけ作成し、ブラウザの設定を切り替えて実行してください。ブラウザごとにテストロジックを重複させないでください。

---

ブラウザマトリックスの設計

分析データに基づく方法

Step 1: Export browser/OS data from analytics (last 90 days)
Step 2: Rank by session share
Step 3: Group into tiers
Step 4: Assign test coverage per tier
Step 5: Review quarterly

ティアシステム

ティア	基準	カバレッジ	実行タイミング
P0	トラフィックシェアが10%超	全テストスイート	すべてのPR、デプロイのたび
P1	トラフィックシェアが3〜10%	スモークテスト＋重要なパス	毎晩、リリース前
P2	トラフィックシェアが1〜3%	スモークテストのみ	毎週、リリース前
Skip	トラフィックシェアが1%未満	テスト対象外	報告があった場合に手動でスポットチェック

マトリックスの例（分析データから作成）

## Browser Matrix — Q1 2026 (next-review: 2026-04-01)

| Browser | Version | Platform | Traffic % | Tier | Notes |
|---------|---------|----------|-----------|------|-------|
| Chrome | Latest | Windows | 34% | P0 | |
| Chrome | Latest | macOS | 12% | P0 | |
| Safari | Latest | macOS | 11% | P0 | WebKit-specific issues |
| Chrome | Latest | Android | 15% | P0 | Mobile viewport |
| Safari | Latest | iOS | 14% | P0 | Mobile Safari quirks |
| Firefox | Latest | Windows | 5% | P1 | Gecko rendering |
| Edge | Latest | Windows | 4% | P1 | Chromium-based but different UA/policy |
| Samsung Internet | Latest | Android | 3% | P1 | Chromium fork, lagging engine |
| Firefox | Latest | macOS | 1.5% | P2 | |
| Chrome | N-1 | Windows | 1.2% | P2 | Previous major version |

バージョンカバレッジ戦略

• 最新版： 現在の安定版を常にテストします。
• 最新版 - 1： 分析データで旧バージョンのシェアが1%を超えているP0ブラウザーのみ、前のメジャーバージョンをテストします。
• 延長サポートリリース（ESR）： 企業ユーザーが大きな割合を占める場合に限り、Firefox ESRをテストします。
• テスト対象外： ブラウザーベンダーである場合、またはブラウザー向けツールを構築している場合を除き、ベータ版／Canary／Nightlyリリースはテストしません。

---

Playwright ブラウザー設定

Playwrightには3つのブラウザーエンジン（Chromium、Firefox、WebKit）が付属しているため、基本的なエンジンレベルのカバレッジにクラウドプラットフォームは必要ありません。これはブランドのカバレッジではなく、エンジンのカバレッジです。付属のWebKitはSafariと同じではなく、付属のChromiumはChromeと同じではありません（コア原則5を参照）。マトリックスの各項目に対して1つのプロジェクトを定義し、devices[...]でモバイルデバイスを割り当て、channelオプションでローカルにインストールされたブランド版ブラウザーを実行します。

完全なplaywright.config.tsプロジェクト一覧、ブランド別チャンネルのスニペット、--project実行コマンドについては、references/playwright-and-cloud-config.mdを参照してください。

チャンネルを使う場合： 付属のエンジンとは異なる、実際のブランド固有の動作が必要な場合に使います。たとえば、拡張機能のサポート、企業ポリシー、コーデックを利用するために、インストール済みのChrome（channel: 'chrome'）またはEdge（channel: 'msedge'）を使う場合です。WebKitとFirefoxにはチャンネルオプションがなく、常にPlaywrightに付属するエンジンが使われます。設定内のedgeプロジェクトとmsedgeチャンネルのスニペットは、どちらかを選ぶ例であり、2つを統合するものではありません。設定に必要なedgeプロジェクトは1つであり、両方ではありません。

**page.screencast()（Playwright 1.59以降、現在の1.60で利用可能）**は、クロスブラウザー実行の注釈付き動画を記録します。マトリックスの失敗をエンジン間で人が確認する必要がある場合に便利です。エージェントによる再実行や失敗箇所の確認には、--ui（UIモード）または--debug（Inspector）を使います。その他の実際のエントリーポイントにはPWDEBUG=1と--headedがあります。--debug=cliフラグはありません。

---

クラウドプラットフォームの設定

クラウドプラットフォーム（BrowserStack、Sauce Labs）は、PlaywrightがCDP／Playwright WebSocketエンドポイント経由で接続する、実際のブランド版ブラウザー／OSのインスタンスを提供します。認証情報と機能は環境変数経由で渡し、プラットフォームのplaywrightVersionをpackage.json内のPlaywrightバージョン（現在は1.60.x）に合わせてください。クライアントとサーバーの不一致はソケットエラーの原因になります。

**BrowserStackは現在、**クライアントとグリッド間のソケットを同期させるため、client.playwrightVersion機能（browserstack.playwrightVersionに加えて）とnpx browserstack-node-sdkランナーを推奨しています。以下の直接接続用の生のwsEndpoint／CDP設定も引き続き使えます。新しい設定にはSDKの方法を使ってください。

client.playwrightVersion機能を含むBrowserStackの設定、Sauce Labsの設定、クラウドブラウザーに並列展開するGitHub Actionsのマトリックスについては、references/playwright-and-cloud-config.mdを参照してください。

---

よくあるクロスブラウザーの問題

クロスブラウザーテストで明らかになる実際の差異と、その検出パターンおよび修正方法を紹介します。それぞれのCSS回避策とPlaywrightテストについては、references/common-browser-issues.mdを参照してください。対象には、分割されたCookie／iframe内のCHIPS、<input type="date">、Clipboard API、scroll-behavior、backdrop-filter、<dialog>要素、View Transitions、Web Animationsのタイミングが含まれます。

現代のクロスブラウザーにおける注意点（2026年）

従来の「Safariが対応に遅れている」項目は、ほぼ解消されています（flexbox の gap、:has() のリリース、同一ドキュメント内の View Transitions はすべて Baseline です）。現在の主な差異は次のとおりです。

• パーティション化された Cookie／ストレージ： Chrome の CHIPS（Partitioned 属性）、Safari の ITP、Firefox の State Partitioning は、埋め込みのサードパーティコンテキストでそれぞれ異なる動作をします。「ブラウザーが Cookie に対応しているか」だけではなく、エンジンごとに iframe 内のサードパーティ Cookie をテストしてください。references/common-browser-issues.md に、エンジンごとに実行できる iframe テストがあります。
• :has() セレクターのパフォーマンス： 2023 年以降、すべてのブラウザーでサポートされていますが、:has() を多用するページでは、エンジンによってスタイル再計算のコストが大きく異なる場合があります。要注意項目です。あるエンジンでページの動きがぎこちなく感じられたらプロファイリングし、visual-testing でビジュアルリグレッションテストを実施してください。
• View Transitions API： 同一ドキュメント内のトランジションは Baseline です（Chrome 111、Safari 18、Firefox 144 — 2025 年 10 月）。そのため、もはや差異ではありません。ドキュメント間のトランジションは、まだ対応に差があります。Chrome 126 以降、Safari 18.2 以降で対応し、Firefox ではフラグが必要です。ドキュメント間のトランジションはプログレッシブエンハンスメントとして扱い、トランジションなしのフォールバックを検証してください。
• WebDriver BiDi： Selenium 4 では本番環境で利用できる状態で、Playwright では一部サポートされています。新しい複数のテストランナーを使うプロジェクトでは、BiDi が収束点となります。要注意項目です。

---

既知の問題の記録

差異が実際に存在し、アプリをすぐに修正できない場合は、コミット対象のファイル（docs/browser-issues.md）に記録し、最初から再度デバッグすることがないようにしてください。この表は Done When のチェック対象となる成果物です。また、各行のテストでは、CSS プロパティではなくユーザーにとっての結果を検証する必要があります。

| Affected browser | Repro | Workaround / fallback / ticket | Test asserts (user outcome, not CSS) |
|------------------|-------|--------------------------------|--------------------------------------|
| Safari (WebKit) ≤17 | scroll-behavior: smooth is partial | rely on anchor nav; no JS scroll dependency | anchor link puts heading in viewport (`toBeInViewport`) |
| Firefox ≤102 | backdrop-filter unsupported | -webkit- prefix + rgba background fallback | overlay readable; modal content visible |
| Firefox (current) | cross-document View Transitions flagged off | progressive enhancement; instant nav fallback | navigation completes; target page heading visible |

差異ごとに 1 行を記録してください。チケットもフォールバックもない行は、文書化された問題ではなく未解決のバグです。

---

テストパターン

基本となるパターンと、それらを適用するルールは次のとおりです。

• 同じテストを複数のブラウザーで実行する — デフォルトの方法です。テストは一度だけ記述し、すべてのブラウザーで実行するようプロジェクトを設定してください。ブラウザーごとにテストロジックを重複させないでください。
• ブラウザー固有のテストロジック — 動作が実際に異なる場合に限り、browserName で分岐します（WebKit の日付入力のフォールバックや、Chromium 限定のクリップボード権限などが該当します）。ルール： これはまれなケースにとどめてください。ブラウザーごとの分岐が多い場合は、回避策を講じるのではなく、修正すべきアプリケーションの互換性バグがあることを示しています。
• ブラウザー間のビジュアル比較 — maxDiffPixelRatio の許容値を指定した toHaveScreenshot を使用します。各ブラウザープロジェクトで独自のベースライン（homepage-chromium.png、homepage-webkit.png など）を生成します。しきい値の方針とベースラインの管理については、visual-testing を参照してください。
• プログレッシブエンハンスメントの検証 — スクリプトへのリクエストを中止し（Chromium のみ）、ネイティブ HTML を使ってもコア機能が動作することを検証します。

4 つすべてのパターンの実行可能なコードについては、references/testing-patterns.md を参照してください。

アンチパターン

Chrome だけでテストする。 デスクトップでのシェアは Chrome が最大ですが、Edge、Opera、Brave と同じエンジンを使用しています。Safari（WebKit）と Firefox（Gecko）では、実際のクロスブラウザーの問題が表面化します。Chrome だけのテストでは、誤った安心感が生まれます。

WebKit／Chromium を Safari／Chrome として報告する。 同梱エンジンが共有しているのはレンダリングであり、実際に提供されるブラウザーではありません。WebKit プロジェクトだけで「Safari 対応」と主張すると、実際の Safari でしか発覚しないコーデック、フォント、ポリシーに関するバグが隠れてしまいます。

すべてのブラウザーを同じようにテストする。 トラフィックシェアが 1％のブラウザーに、30％のブラウザーと同じだけの労力をかける必要はありません。ティアシステムを使って、シェアに応じて労力を配分してください。

ブラウザーごとにテストを重複させる。 テストは一度だけ記述し、設定を通じて複数のブラウザープロジェクトで実行します。同じロジックを持つ checkout.chrome.spec.ts と checkout.safari.spec.ts を作るのは、適切な方法ではありません。

あらゆる場所で browserName をチェックする。 テスト内の過度なブラウザー分岐は、アプリケーションの互換性に問題があることを示しています。テストで回避するのではなく、アプリを修正してください。

許容範囲を設けず、ピクセル単位で完全一致を求める。 フォントのレンダリング、アンチエイリアス、サブピクセルの丸め処理は、ブラウザーやプラットフォームによって異なります。ビジュアル比較では maxDiffPixelRatio または maxDiffPixels を使用してください。

モバイルブラウザーを無視する。 モバイル版 Chrome と Safari は、デスクトップ版と同じではありません。ビューポートの挙動、タッチ操作、CSS のサポートが異なります。マトリックスの個別項目としてテストしてください。

ブラウザーマトリックスを固定したままにする。 ブラウザーの利用状況は変化します。2 年前のデータに基づくマトリックスは正しくありません。分析データを四半期ごとに確認し、next-review の日付を更新してください。

フォールバックもチケットもない差異を記録する。 回避策も未解決のチケットも記載されていない既知の問題の行は、文書化済みのふりをした未文書化のバグです。

---

失敗パターン

症状	考えられる原因	修正または確認
クラウドテストがソケット／ハンドシェイクエラーで失敗する	Grid の Playwright バージョン ≠ ローカルのバージョン	playwrightVersion／client.playwrightVersion を npx playwright --version の結果に合わせて設定し、browserstack-node-sdk ランナーを使用します
クリップボードのテストが Chromium では成功し、Firefox／WebKit では失敗する	grantPermissions は Chromium でしか動作しない	クリップボード API ではなく、UI のフィードバック（Copied!）をアサートします。grantPermissions は browserName === 'chromium' の場合に限って実行します
プログレッシブエンハンスメントのテストが Firefox／WebKit でエラーになる	スクリプト中断のルートインターセプトは Chromium 専用	ルートの処理は browserName === 'chromium' の場合に限って実行し、それ以外では JavaScript 無効時のアサーションをスキップします
WebKit プロジェクトでは「成功」するが、実際の Safari ユーザーから不具合が報告される	WebKit エンジン ≠ 実際に提供される Safari	該当するフローについて、クラウドグリッドに実際の Safari の行を追加します
1 つのブラウザーだけでビジュアルのベースライン差分が急増する	すべてのブラウザーで単一のベースラインを共有している	プロジェクトごとにベースラインを生成します。各ブラウザーは独自の *-<project>.png を保持します
あるエンジンでのみ :has() を多用するページの動作がぎこちない	スタイル再計算のコストがエンジンによって異なる	そのエンジンでプロファイルを取り、:has() の適用範囲を狭めます。visual-testing でビジュアルリグレッションテストを実施します

---

完了条件

• 実際の分析データ（直近 90 日間）を使用してブラウザーマトリックスが定義され、ティア割り当て（P0／P1／P2）が文書化され、トラフィックシェアに基づいて妥当性が説明されており、日付入りの next-review フィールドを持つファイルにコミットされている。
• Playwright のプロジェクト設定（または BrowserStack／Sauce Labs の設定）がマトリックスを反映し、すべての PR で P0 ブラウザーを実行している。クラウド設定では playwrightVersion を package.json に合わせて固定している。
• docs/browser-issues.md が存在し、既知の差異ごとに 1 行があり、影響を受けるブラウザー、再現手順、回避策／フォールバックまたはリンクされたチケット、そして（CSS ではなく）ユーザーの結果をアサートするテストが記載されている。
• よくある差異のチェックリスト（パーティション化された Cookie、日付入力、クリップボード、スクロールの挙動、backdrop-filter、<dialog>、View Transitions）について、P0／P1 ブラウザーに該当する各項目にテストまたは既知の問題の行がある。
• 次回の四半期ごとのマトリックスレビューに対する追跡対象の課題が存在する（または、マトリックスファイルの next-review の日付が未来になっている）。これにより、更新を忘れずに済む。

関連スキル

• visual-testing — ピクセルレベルのベースライン戦略、しきい値テーブル、toHaveScreenshot の設定を担当します。スクリーンショットの差分をどの程度許容するかについては、こちらを参照してください。このスキルでは、どのブラウザーをベースラインの対象にするかだけを決定します。
• playwright-automation — クロスブラウザーテストの基盤となる、Playwright の基本的なパターン、フィクスチャ、CI 設定を扱います。
• ci-cd-integration — ブラウザーマトリックスを並列実行し、成果物を収集するためのパイプライン設定を扱います。
• mobile-testing — デバイスファームとネイティブ／ハイブリッドアプリのテスト（Appium/Detox）を扱います。対象がブラウザーのビューポートではなくアプリの場合は、こちらを参照してください。
• accessibility-testing — このマトリックスと関連する、ブラウザー間のアクセシビリティの違い（スクリーンリーダーの動作、ARIA のサポート）を扱います。

参照ファイル（references/ 内）

• playwright-and-cloud-config.md — playwright.config.ts のプロジェクトリスト、ブランド別チャンネル、--project の実行コマンド、BrowserStack（SDK と client.playwrightVersion）／Sauce Labs／CI のマトリックス設定。
• common-browser-issues.md — エンジンごとに分割された Cookie を扱う iframe テスト、日付入力の WebKit フォールバック、クリップボード、スクロール動作、backdrop-filter、<dialog>、View Transitions、Web Animations。
• testing-patterns.md — 複数のブラウザーで同じテストを実行する方法、browserName による分岐、ビジュアル比較、プログレッシブエンハンスメントのコード。