# test_client.py ドキュメント

## 概要
`test_client.py` は stdin/stdout 経由でバックエンド (`mainloop.py`) と通信し、各種 API エンドポイントを自動 / 半自動でテストするためのクライアントユーティリティ。初期化完了待機、ログ (status=348) 展開表示、サイレントモード、結果エクスポート(JSON/CSV)、Watchdog ハートビート送信 (/run/feed_watchdog) などの補助機能を備える。

## 主な責務
- バックエンドプロセス起動と初期化完了待機 (`/run/initialization_complete`)
- エンドポイント単発送信/応答待機 (Base64 エンコード/デコード)
- status=348 ログエントリの全文展開表示
- タイムアウト / 例外発生時の復旧メッセージ出力
- Watchdog ハートビート送信スレッド管理
- 自動テスター (`AutomatedEndpointTester`) による包括的エンドポイント試験
- テスト結果の JSON / CSV エクスポート (インタラクティブ指定)

## クラス構成
### `Color`
ANSIカラー定数を定義し、可読性の高い出力を実現。

### `TestClient`
バックエンドとの 1 プロセス・1 チャンネル通信を管理。

| 属性 | 役割 |
|------|------|
| `process` | 起動した Python バックエンド subprocess |
| `_watchdog_stop_event` | Watchdog スレッド停止制御用 Event |
| `_watchdog_thread` | /run/feed_watchdog 送信スレッド |

#### 初期化フロー
1. `subprocess.Popen([sys.executable, 'mainloop.py'], ...)` でバックエンド起動
2. `_wait_for_initialization()` を呼び出し `/run/initialization_complete` 受信まで待機
   - VRCT_INIT_TIMEOUT 環境変数があれば soft timeout として利用 (超過時 WARN のみ)
   - 30 秒間隔で進捗ログ (最後に受信した endpoint)
   - status=348 レコードは全文 JSON 展開
3. 初期化完了後 `_start_watchdog()` がバックグラウンドで /run/feed_watchdog を 30 秒間隔送信

#### 重要メソッド
- `send_request(endpoint, data=None, timeout=30.0, silent=False)`
  - リクエスト JSON を構築し送信
  - `data` は JSON シリアライズ → Base64 → `data` フィールド
  - 指定 endpoint のレスポンス行まで逐次読み取り (他 endpoint のログ行は通過)
  - status=348 の場合ログとして全文表示（silent=False のとき）
  - タイムアウト時 504 レスポンスを合成

- `_wait_for_initialization(timeout=None)`
  - 無期限または soft timeout 待機
  - プロセス死亡検知で RuntimeError

- `_start_watchdog()` / `cleanup()`
  - Watchdog スレッド開始と安全停止 (Event セット後 join)

### `AutomatedEndpointTester`
`backend_test.py` のロジック移植版（stdin/stdout プロトコル向け）。

| 属性 | 説明 |
|------|------|
| `silent` | True ならクライアント側詳細出力を抑制 |
| `export_path` | JSON エクスポート先 (None なら未出力) |
| `export_csv` | CSV 追加出力有無 |
| `results` | 収集したテストレコード一覧 |

#### エンドポイント分類 (ハードコード暫定)
- 有効/無効化: `/set/enable/*`, `/set/disable/*`
- 設定更新: `/set/data/*`
- 実行系: `/run/*`
- 削除系: `/delete/data/*`

#### 主メソッド
- `test_validity_single(endpoint)` 有効/無効化系単一試験
- `test_set_data_single(endpoint)` 設定更新系単一試験（事前に動的取得が必要な値は `/get/data/...` を呼び最新値をキャッシュ）
- `test_run_single(endpoint)` 実行系単一試験
- `test_delete_single(endpoint)` 削除系単一試験
- `run_all()` 全カテゴリ順次実行
- `run_random(count=1000)` 全エンドポイントプールからランダム選択
- `run_specific_random(category, count)` 指定カテゴリ内ランダム
- `summary()` 結果集計出力および必要な場合 JSON/CSV エクスポート

#### 結果レコード構造
```json
{
  "endpoint": "/set/data/transparency",
  "status": 200,
  "result": 85,
  "expected": "status==200"
}
```

CSV 例:
```
endpoint,status,expected,success
/set/data/transparency,200,status==200,True
```

## status=348 ログ取り扱い
- 初期化待機中: 展開してインデント付き表示
- リクエスト応答処理中: silent=False ならログエントリ全文を優先表示
- 通常 API 応答 (status != 348) との区別を明確化しデバッグ容易化

## Watchdog ハートビート
- 30 秒間隔で `/run/feed_watchdog` を送信 (fire-and-forget)
- 送信失敗時は警告を表示しループ終了
- クライアント終了時に停止イベントをセットしスレッド join でリーク防止

## エクスポート機能
### JSON エクスポート
- `export_path` が指定されていれば `results` を UTF-8 / ensure_ascii=False で整形出力
- フィールド: endpoint, status, result, expected, success

### CSV エクスポート
- JSON パスから拡張子置換（`.csv`）で派生 (内部 `_derive_csv_path` 相当ロジック)
- 成功判定: `status` と `expected` 文字列評価結果に依存 (単純比較)

## 例外 / エラー処理方針
| ケース | 対応 |
|--------|------|
| バックエンド終了検知 | 初期化待機中: RuntimeError を投げる / 通常通信: 500 レスポンス合成 |
| JSONDecodeError | ログ行扱いでスキップ (初期化中は進捗ログとして表示) |
| BrokenPipe / OSError | 通信切断とみなして 500 レスポンス返却 |
| タイムアウト | 504 レスポンス返却 (endpoint 同梱) |

## 制限事項
- エンドポイント一覧は動的取得ではなくハードコード (将来的改善余地)
- レスポンスの並行受信は未対応（1 リクエスト同期待ち）
- status=200 以外の詳細な意味的検証は限定的 (expected = 単純条件)
- Watchdog レスポンスは読み取らないため送信失敗検知は例外経路のみ

## 今後の改善候補
1. CLI 引数サポート (`--mode random --count 500 --silent --export result.json`)
2. 動的エンドポイント列挙 API 追加後の自動反映
3. リトライポリシー (指数バックオフ) 導入
4. 応答時間測定とパフォーマンスレポート出力
5. 並列テスト実行 (複数 subprocess / async IO)

## 参考
- `backend_test.py` : 元ロジック
- `utils.py` : status=348 ログ出力仕様
- `mainloop.md` : 通信プロトコル詳細

## まとめ
`test_client.py` は VRCT バックエンドに対する包括的なテストおよび運用補助を 1 ファイルで実現するツール。初期化待機の堅牢化（無期限 + soft timeout）、Watchdog ハートビート、ログ展開、静音化オプション、結果エクスポートにより長時間動作・回帰試験・CI への組み込みを容易にする基盤を提供する。