2026年前端避坑対照表：
リモート Mac 上 Vitest/jsdom と実 Safari/WebKit
Vitest／jsdom が緑でも Safari が壊れるのはテスト不足ではなく、WebKit との互換契約が未整理なことが多いです。イベント・フォント・メディア・ストレージの対照、リモート Mac を使う三段階検証と CI の指針をまとめました。併読：Safari 互換テスト（Playwright）、実機・シミュレータ・クラウド比較、ブログ一覧。
01 差異リスクの概要
02 対照表（重要 API／レンダリング）
設計・テスト計画用。既定 environment: 'jsdom' 想定（happy-dom は別評価）。
| 領域 | jsdom／Vitest（一般的） | Safari／WebKit（リモート Mac） | テスト上の含意 |
|---|---|---|---|
| ポインタ／タッチ | 合成のみ。passive／ヒットテストは弱い |
ネイティブ＋ iOS ジェスチャ | Safari でホイール・preventDefault を手動確認 |
| フォーカス／キーボード | Tab 順など単純化 | focus-visible、Shadow DOM 等 | フォーム・モーダルをキーボードのみでスモーク |
| レイアウト／CSS | 実ピクセルレイアウトなし | flex／grid、100dvh、backdrop-filter |
ヒーロー・sticky は目視または VRT |
| フォント／テキスト | メトリクスが macOS／iOS と不一致になりやすい | Core Text、可変フォント | 省略・改行・CJK を実 Safari で確認 |
| メディア | モック中心 | HLS、自動再生、低電力モード | ステージングで再生を1経路通す |
| ストレージ | localStorage がメモリ寄り、クォータなし |
ITP パーティション、追い出し | サイトデータ削除後のログイン／キャッシュを確認 |
| タイマー | rAF 近似 | 実フレーム、Visibility API | フレークするアニメは WebKit E2E へ |
| fetch／Cookie | MSW 等でモック | CORS、SameSite、サードパーティ |
本番オリジンまたは Playwright で結合 |
03 ローカル vs 実機検証フロー
リリース前3ステップ（実行可能な順序）を固定します。
- 1. ローカル／Linux CI：
vitest run＋カバレッジ。レイアウト／メディア系はファイル分割や skip で jsdom 偽陽性を避ける。 - 2. リモート Mac・Safari： ステージングで P0（認証・課金・メディア等）を手動。Web Inspector FAQ、WebKit デバッグ手順。
- 3. 自動化： 同一 Mac で Playwright
webkit、トレース保存。ビルド〜Safari 検証の連続手順。
Safari メジャーを計測値に合わせる・拡張オフ・動画はウィンドウ／全画面の両方・サイトデータ削除で ITP 相当も一度試す。
04 CI パラメータの提案
PR は jsdom、main／夜間は リモート Mac で WebKit、と分割するのが扱いやすいです。
| 観点 | 推奨設定 | 理由 |
|---|---|---|
| Vitest ワーカー | --pool=threads、共有 Mac は maxWorkers を控えめ |
Playwright と CPU を奪い合わない |
| タイムアウト | E2E だけ長め、単体は短め | WebKit 起動・メディア待ちにばらつき |
| Playwright | macOS のみ playwright install webkit |
Linux WebKit≠Safari と表示ラベル化 |
| 成果物 | 失敗時は trace＋動画 | E2E トリアージ と連携可 |
05 FAQ
単体だけで Safari は不要？ いいえ。jsdom はイベント・ストレージ・メディア・レイアウトを保証しません。単体→Mac 上 Safari／WebKit→P0 ステージングの三段が現実的です。
なぜリモート Mac？ 本物の Safari は Apple 系 OS 限定。ユーザーに近い WebKit／GPU を Linux 単体では再現しにくいからです。
Playwright webkit＝Safari？ 近いが同一ではない。自動化＋ Safari.app でクリティカル UX を補完。
最小コスト構成は？ 毎 push jsdom、定期 WebKit（専用 Mac）、リリースは赤ジョブまたはチェックリスト未完ならブロック。
対照表で機能を分類し、Vitest は速さ、リリースはリモート Mac の Safari／WebKit トレースで止める。ラベル化すれば「CI 緑＝Safari 安心」と混同しません。
Vitest と WebKit ゲート用にリモート Mac をレンタル
Apple Silicon で実 Safari／Playwright WebKit。購入・料金・ヘルプ は登録なしで閲覧可。関連：Safari 互換テスト、ブログ一覧。