VRCT/src-python/docs/test_client.md

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 エクスポート

結果レコード構造

{
  "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 への組み込みを容易にする基盤を提供する。