| name | ylc-e2e-playwright |
| description | この拡張の Playwright E2E テスト専用ガイド。E2E テスト実行・新テスト追加・失敗/フレーク調査・URL ドリフト修正・trace/PWDEBUG デバッグで使う。フルスクリーンチャット・チャットなし動画・リプレイ不可・アーカイブ遷移・SPA 遷移の E2E テストを扱う。実ブラウザでの手動動作確認や DOM/見た目の現物確認には使わず、その場合は `ylc-agent-browser` を使う。 |
E2E Playwright — YLC プロジェクト固有ガイド
Chrome 拡張の Playwright 汎用パターン（拡張ロード、SW 起動、evaluate スコープ、chrome.storage、Shadow DOM、iframe）は chrome-extension-e2e-playwright スキルを参照。本スキルはこのプロジェクト固有のインフラ・契約に特化する。
ブラウザ上の挙動を現物確認するときはこの skill に寄せない。YouTube を開いて switch や iframe の状態を直接調べる作業は ylc-agent-browser を使う。
Reference table
| トピック | 参照先 |
|---|
| Fixture の設計意図・URL 探索・非自明なパターン | references/architecture.md |
| 4 モード契約・skip/fail 判定基準 | references/mode-contracts.md |
Guardrails
- 既定は workers=1 — CI・ローカルとも直列実行する。YouTube のフルスクリーン状態と persistent context は並列 Worker 間で不安定になりやすく、macOS Chromium では競合によるフレークも起きる。速度を優先するときだけ CLI の
--workers で明示的に上書きする
- ランダム sleep 禁止 —
waitForTimeout() で flaky を隠さない。expect.poll() / waitForFunction() を使う
- skip で実装不具合を隠さない — 環境の問題 → skip、拡張のバグ → fail。詳細は
references/mode-contracts.md の Skip vs Fail tree
- POM を使う —
YouTubeWatchPage / ExtensionOverlay を経由する。spec 内で直接 DOM 操作しない
- addInitScript ヘルパーを使う —
window.__ylcHelpers の既存メソッドを活用する。evaluate 内で DOM ヘルパーを再実装しない
data-ylc-* セレクタを使う — Tailwind クラス名でなく data-ylc-* カスタム属性で要素を特定する。プロダクトコードに属性がなければ追加してから E2E を書く- 3段階フォールバッククリック —
reliableClick(locator, verify) を使う。通常クリック→force→JS の順で昇格する。force を最初に使うと addLocatorHandler が発火しない。常に二重クリックするとトグル UI が反転する
- consent handler が共通 fixture に登録済み —
registerConsentHandler() が sharedPage、liveUrl、archiveReplayUrl の各 fixture で自動登録される。YouTube の同意ダイアログは addLocatorHandler で自動処理される。production code では noWaitAfter: true を使用中（高速化のため）だが、一般的には消える UI にはデフォルト動作（消滅を待機）が安定
- Storage はランタイムフォールバック —
createStorageAccessor は Worker → e2e.html bridge のランタイムフォールバック。e2e.html は React/Zustand なしなので rehydration リスクなし。Worker が死んでも自動で Page パスに切り替わる
