# テスト妥当性レビュー: agen
- 評価: 概ね良い

## 確認範囲
- Workspace root: `/home/hare/Projects/yoi`
- Crate/package: `crates/agen` / `agen`
- 読んだ範囲:
  - `crates/agen/Cargo.toml`
  - `crates/agen/src/**`
  - `crates/agen/tests/**`
  - `crates/agen/docs/{requirements,architecture}.md`
- ソースファイル、Ticket、設定ファイルは変更していない。

## 現在のテストがよくカバーしていること
- Provider adapter 周りの単体テストはかなり厚い。
  - Anthropic / Gemini / OpenAI Chat / OpenAI Responses の request projection、SSE event parsing、tool call/result、usage、reasoning metadata、prompt cache 関連が細かく検証されている。
  - OpenAI Responses は未知 event/error の保持、reasoning item の round-trip、encrypted content、stateless ZDR default など、最近壊れやすい仕様面もテストされている。
- Worker の主要な in-process 挙動は integration test で押さえられている。
  - text response、tool call、tool call collector、history update、locked/mutable state transition、system prompt preservation、turn count、tool registration など。
  - `trybuild` による compile-fail test があり、typestate 制約の一部を型レベルで検証している点は良い。
- Callback / hook / parallel tool execution のテストがある。
  - text/tool/usage/turn/retry callback、pre/post tool hook、synthetic/skip path、execution context の order / batch id が検証されている。
- Provider fixture smoke test がある。
  - Anthropic / Gemini / Ollama / OpenAI fixture を deserialize し、timeline と usage token の最低限の整合を見る構成になっている。
- Transport/retry 境界にもテストがある。
  - retryable/non-retryable status、`Retry-After` preservation、mid-stream SSE error、response timeout retryability、Codex backend header/compression が検証されている。
- prune / token counter / tool server / truncation など、Worker 周辺の重要な小さい invariant も単体テスト化されている。

## 不足 / 疑問のあるテスト
- Core requirement に見える Pause/Resume 系の実行テストが不足している。
  - `PreToolAction::Pause` / `TurnEndAction::Pause`、pending tool call の保持、`resume()` 後の再開、resume 時に余計な user message を積まないこと、複数 tool call batch の途中停止などは、少なくとも現行テスト名からは直接確認できなかった。
  - typestate や history accumulation は見ているが、「pause を跨いだ Worker の安全性」は別の重要 invariant。
- Cancel / interruption / continuation の安全性テストが薄い。
  - `cancel()` は doc example と API として存在するが、stream 中 cancel、tool 実行前後 cancel、partial assistant content の扱い、未完成 tool JSON/reasoning fragment を history に残さないことのような Worker として重要な保証がテストで明確に固定されていない。
  - stream-started failure 後の continuation / retry path も、単体の timeout/probe test はあるが、history-aware continuation の最終状態を integration で確認するテストが欲しい。
- 一部 integration test が `worker.run(...).await` の戻り値を捨てており、後段で限定的な副作用だけを見る形になっている。
  - 意図的に error path を見ている箇所以外では、`expect` または error 内容の明示 assert にした方が、run 後半の失敗を取り逃がしにくい。
- Fixture tests は smoke としては有用だが、契約テストとしては緩い箇所がある。
  - `common` 側で usage や timeline が不足した場合に warning 寄りの扱いになっている部分があり、provider-specific contract を固定するには弱い。
  - provider ごとの差異を許す helper は便利だが、重要な event sequence は fixture ごとにもう少し strict にしてよい。
- Parallel execution test に wall-clock threshold 依存がある。
  - 現状は短時間 sleep ベースで並列性を確認しているため、遅い/混雑した CI では flaky になり得る。barrier と atomic max-concurrency などで「同時に走った」ことを直接見る方が堅い。
- Doc tests は 24 件 list されるが、すべて `ignore` 扱い。
  - API 使用例の維持には役立ちにくい。外部 API surface が重要な crate なので、可能なものは `no_run` または compile-only doctest に寄せる価値がある。
- 実 provider との E2E はない。
  - crate 単体の妥当性評価としては必須ではないが、provider schema drift を検知する意味では fixture 更新だけでは限界がある。

## 追加を提案するテスト
- Pause/Resume integration tests を追加する。
  - pre-tool pause → pending tool call 確認 → resume → tool result commit → assistant continuation。
  - turn-end pause → history に assistant output が残る → resume で次 request が正しく構築される。
  - 複数 tool calls のうち一部/全部を pause した場合の order、batch id、history item の不変条件。
- Cancel/interruption tests を追加する。
  - stream 中 cancel で partial text/reasoning/tool call fragment が安全に扱われること。
  - tool 実行中 cancel の結果が history/callback/result にどう反映されるか。
  - incomplete tool JSON と reasoning fragment が次 turn の request に混入しないこと。
- Continuation/retry の Worker-level integration を追加する。
  - stream-started 後の transport error → continuation notice callback → safe partial history commit → retry/continue request の形。
  - continuation limit 到達時の error と history post-condition。
- `worker.run` の戻り値を捨てている既存テストを見直す。
  - 正常系は `expect("worker run succeeds")`。
  - 異常系は error kind/message と、その時点までに許される副作用を明示 assert。
- Fixture tests を provider-specific に少し強める。
  - usage が必須の fixture では warning ではなく assert。
  - event sequence の必須 block / tool / usage / reasoning metadata を fixture ごとに固定。
- Parallel execution test の時間依存を下げる。
  - sleep duration で速さを見るより、barrier + concurrent counter で最大同時実行数を assert する。
- 主要 public examples を `ignore` から compile-only doctest に移す。
  - 実行不能な外部 call は `no_run`、擬似コードは明確に `text` fence などに分ける。

## 実行したコマンド
- `cargo test -p agen`
  - Result: passed.
- `cargo test -p agen -- --list`
  - Result: passed/listed.
  - Executable tests listed: unit/integration/trybuild 全体で 237 件。
  - Doc tests listed: 24 件、すべて ignored。
- `cargo test -p agen --quiet`
  - Result: passed.

