# VCR テスト（Virtual Cassette Recorder）

VCR テストとは、外部 API との通信をモック化するテスト手法です。実際の HTTP リクエストとレスポンスを「カセット」と呼ばれるファイルに記録し、以降のテスト実行時にはその記録を再生することで、外部サービスに依存せずテストを実行できます。

## VCR テストの目的と利点

1. **一貫性の確保**: 外部 API の応答変更に影響されず、一貫したテスト結果を得られます
2. **高速化**: 実際のネットワークリクエストが不要なため、テスト実行が高速化します
3. **オフライン対応**: インターネット接続がない環境でもテストが可能です
4. **API 負荷軽減**: 外部サービスへの不必要なリクエストを減らせます

## VCR テストの仕組み

1. 初回テスト実行時に実際の HTTP リクエストを送信
2. リクエストとレスポンスの詳細（URL、ヘッダー、ボディなど）を YAML ファイルに記録
3. 2 回目以降の実行時は YAML ファイルから応答を再生

## 重要な注意事項

1. **ローカル実行時の挙動**: ローカル環境での実行時には 2 回目以降もリクエスト照合が行われます。つまり、実際のリクエストの内容とカセットに記録されたリクエストの内容が一致するか確認され、一致する場合のみ記録された応答が返されます。

2. **カセット修正のルール**: カセットファイルを手動で修正する場合、必ず人間（チームメンバーまたは管理者）に修正許可を得てください。カセットの内容を不用意に変更すると、テストの信頼性が損なわれる可能性があります。

3. **機密情報の扱い**: API キーなどの機密情報がカセットファイルに記録される場合があるため、それらが適切にフィルタリングされていることを grep などを駆使して確認してから人間に成果を報告してください。

## VCR テスト共通の実装ルール

1. **テスト関数の命名**: 関数名の末尾に `_vcr` を付けて、VCR テストであることを明示する

   ```python
   def test_md_to_pdf_vcr(client: ToolsClient) -> None:
   ```

2. **pytest.mark.vcr() デコレータ**: 全ての VCR テスト関数に付与する

   ```python
   @pytest.mark.vcr()
   def test_md_to_pdf_vcr(client: ToolsClient) -> None:
   ```

3. **マルチパートリクエストの扱い**: ファイルアップロードを伴うテストでは、リクエストボディが環境によって変化するため、`match_on` パラメータを使用してマッチング条件を調整する

   ```python
   @pytest.mark.vcr(match_on=["method", "scheme", "port", "path", "query"])
   def test_pdf_to_page_images_vcr(client: ToolsClient) -> None:
   ```

4. **機密情報のカセット記録**: このリポジトリは public リポジトリのため、機密情報（API キーや本番環境以外の環境の URL など）がカセットに残ると悪用の可能性がある。そのため、 @vcr_utils.py @conftest.py にあるように機密情報をフィルタリングしている。もし、機密情報がカセットに記録されていることに気づいた場合、フィルタリングを追加し、人間にもその旨を理由と共に報告すること。
