Make snapshot updates possible without modifying test code

[uzulla]

PRとしては完成しているので、これを手動レビュー、動作確認して上流にPRを送る。

---

Why

Updating test snapshots required modifying constants inside the test suite.
This made the workflow unnecessarily awkward and error-prone:

• Snapshot updates required editing test code.
• Accidental commits of development-only changes were possible.
• Numeric flags were hard to remember and not self-explanatory.
• Cache and fixtures were controlled separately even though they are always updated together

As a result, contributors could not easily refresh snapshots, raising
the barrier for maintaining or improving tests.

This PR introduces a simple environment-based switch so contributors can
update snapshots without touching the codebase.

---

What

New environment variables

Variable	Purpose
UPDATE_EMBED_SNAPSHOTS=1	Re-fetch from the network and regenerate both cache and fixtures used in tests
EMBED_STRICT_CACHE=1	Fail tests if required cache files are missing (useful for CI)

Developer workflow

Developers can now refresh snapshots with a single command:

UPDATE_EMBED_SNAPSHOTS=1 ./vendor/bin/phpunit

No code edits and no numeric flags are required.

CI updates

GitHub Actions now runs with:

EMBED_STRICT_CACHE=1

to ensure snapshot files are always present and up to date.

Documentation

A new "Testing" section has been added to the README, describing how
snapshots are updated and how strict mode behaves in CI.

---

Usage Examples

# Update snapshots for a specific test
UPDATE_EMBED_SNAPSHOTS=1 ./vendor/bin/phpunit --filter testYoutube

# Update all snapshots
UPDATE_EMBED_SNAPSHOTS=1 ./vendor/bin/phpunit

Summary by CodeRabbit

リリースノート

• Documentation

  • テスト実行方法、スナップショットモード、キャッシュ構造・管理方法をREADMEに追加。関連する環境変数の説明を追記しました。

• Tests

  • テストのキャッシュ/フィクスチャ管理を強化。更新モードで自動的にフィクスチャを書き出す挙動や、厳格モードで欠損フィクスチャを失敗扱いにする挙動を追加しました。

• Chores

  • CIテスト実行環境に新しい環境変数を追加しました（テストキャッシュ挙動の制御）。

[coderabbitai]

ウォークスルー

GitHub Actionsのテストジョブに環境変数を追加し、READMEにテスト／スナップショット／キャッシュ運用を追記。テスト基底クラスに CACHE / FIXTURES 定数と環境変数優先のモード判定ヘルパーを追加し、fixture存在時と不在時のアサーション制御を環境に応じて変更しています。

変更箇所

コホート / ファイル	変更概要
ワークフロー設定 \.github/workflows/test.yml	Testsステップに環境変数 EMBED_STRICT_CACHE=1 を追加
ドキュメンテーション更新 README.md	テスト実行、スナップショットモード、キャッシュ構造および環境変数（UPDATE_EMBED_SNAPSHOTS, EMBED_STRICT_CACHE）を説明する新しい「Testing」セクションを追加
テストクラス設定 tests/PagesTestCase.php	CACHE と FIXTURES 定数を追加。getCacheMode(): int, getFixturesMode(): int, isStrictMode(): bool の保護静的ヘルパーを追加。getEmbed() と assertEmbed() をこれらのヘルパーで制御し、fixtureの存在／非存在時に strict/update/非strict の分岐を導入

シーケンス図

sequenceDiagram
    autonumber
    participant TestRunner as テストランナー
    participant Pages as PagesTestCase
    participant FS as ファイルシステム

    TestRunner->>Pages: テスト開始 -> getCacheMode()
    Note right of Pages `#e6f7ff`: 環境変数優先\n`UPDATE_EMBED_SNAPSHOTS` / `EMBED_STRICT_CACHE`\nなければ定数を使用
    Pages->>Pages: getEmbed() 実行
    Pages->>FS: fixture 存在確認
    alt fixture が存在
        FS-->>Pages: fixture を返す
        Pages->>TestRunner: 通常アサーション実行
    else fixture が欠如
        alt strict モード
            Pages->>TestRunner: テスト失敗（fixture 必須）
        else update fixtures モード
            Pages->>FS: fixture を書き込み
            Pages->>TestRunner: 保存メッセージ出力 + テストをスキップ
        else 非 strict モード
            Pages->>FS: fixture を書き込み
            Pages->>TestRunner: 保存メッセージ出力 + テストをスキップ
        end
    end

Loading

推定レビュー工数

🎯 3（Moderate） | ⏱️ ~20分

• tests/PagesTestCase.php の環境変数優先順位と分岐（EMBED_STRICT_CACHE / UPDATE_EMBED_SNAPSHOTS）が仕様どおり動作するか確認
• fixture 書き込み／スキップ／失敗メッセージの出力とパス権限の妥当性をチェック
• README の説明が実装（環境変数名と挙動）と一致しているか確認

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	PRのタイトルは、変更セットの主要な目的である「テストコードを変更せずにスナップショットの更新を可能にする」を明確に要約しており、簡潔で具体的です。
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/fix-snapshot-flag-bug-01Bk221NZvUN7HFF9R9ViGg4

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

📥 Commits

Reviewing files that changed from the base of the PR and between a0bdfef and 795216b.

📒 Files selected for processing (3)

• .github/workflows/test.yml (1 hunks)
• README.md (1 hunks)
• tests/PagesTestCase.php (3 hunks)

🔇 Additional comments (1)

tests/PagesTestCase.php (1)

18-39: CACHE / FIXTURES 定数とモードのドキュメントは分かりやすいです

キャッシュモード・フィクスチャモードの意味と、環境変数による上書きの関係が docblock で丁寧に説明されていて、テスト挙動を追いやすくなっていると思います。また static::CACHE / static::FIXTURES を使っているので、サブクラス側で定数を上書きしてテストごとにデフォルトモードを変えられる設計も良いです。