test-doctor

テストドクター

テストは実装の正しさを証明するものではなく、製品を保護するものとして扱います。各テストについて、「これが失敗した場合、ユーザーに見えるどの機能、または文書化されたどの契約が壊れている可能性が高いか」と問いかけてください。具体的な答えがない場合は、そのテストを残す価値があることを示す根拠を求めてください。

運用モードを選択する

• 監査、分析、診断、計画の依頼では、ファイルを編集せずに調査して報告します。
• 変更を明示的に求められた場合は、まず監査を行い、その後、回帰防止を維持または改善する最小限のテスト変更を行います。
• ユーザーが修正を明示的に求めていない限り、テストを満たすためだけに本番の動作を変更しないでください。
• 期待される動作を評価する前に、リポジトリの指示と関連する設計文書や契約文書を読んでください。どちらが正しいか推測するのではなく、契約との不一致を報告してください。

根拠を集める

1. テストファイル、フィクスチャ、ヘルパー、設定、パッケージスクリプト、CI ワークフローを特定します。
2. ソースパッケージの境界と公開エントリーポイントを特定します。
3. 関連する機能、アーキテクチャ、API、バグ修正のドキュメントを読みます。
4. 疑わしいテストが存在する理由の解明に役立つ場合は、対象を絞って git の履歴を調べます。
5. 利用可能なテストコマンドとその対象範囲を記録します。所見または依頼された変更の検証に必要なコマンドだけを実行してください。

大規模なリポジトリでは、まずパッケージ単位の一覧とリスクの高いパスから着手します。根拠からシグナルの弱さ、重複、壊れやすさ、または保護の欠落が示された場合に限り、個々のテストまで調査を広げます。

テストが保護する機能を対応付ける

テストファイルまたは関連するテストグループごとに 1 行を設け、簡潔な対応表を作成します。

項目	意味
テスト	ファイルとテスト名またはスイート名
種別	ユニット、インテグレーション、コントラクト、コンポーネント、E2E
保護する機能	失敗によって検出されるユーザーの動作または文書化された契約
境界	実際の依存関係と置き換えられた依存関係
リスク	回帰の影響度と発生可能性
コスト	実行時間、セットアップの複雑さ、壊れやすさ、保守負担
信頼度	根拠を添えた高、中、低

根拠が不十分な場合は、保護する機能を unclear と記します。テスト名だけから意図を作り上げないでください。

テストの価値を評価する

これは相対的な判断基準として使い、実測値のような数値をでっち上げないでください。

Test value = user impact × regression risk × bug-detection strength
             --------------------------------------------------------
                            maintenance cost

各要素を高、中、低で評価し、意見が分かれる評価については説明します。

次の保護を行うテストを優先します。

• ユーザーのワークフロー、データの正確性、セキュリティ、互換性、復旧。
• 公開 API、プロバイダーインターフェース、永続化形式、マイグレーション、パッケージ間の契約。
• コアランタイムのオーケストレーション、ファイル処理、セッション状態、重要な障害パス。
• 過去に障害が発生した境界条件や、回帰しやすい境界条件。

主に次の内容を保護するテストは、価値を低く評価します。

• プライベートヘルパー、内部オブジェクトの形状、厳密な呼び出し順序、偶発的な関数呼び出し回数。
• 観測可能な動作ではなく、モックの設定。
• 契約やユーザーへの影響がない静的なフォーマット。
• より強い境界で、すでに直接保護されている重複パス。

重いスナップショット、過剰なモック、壊れやすいセレクター、内部 API への結合、大規模で重複したフィクスチャ、タイミングへの依存、時間のかかる環境セットアップがある場合は、保守コストの評価を引き上げます。

テストの不適切なパターンを検出する

実装への結合

プライベートメソッド、内部状態、厳密な呼び出し順序、または偶発的な呼び出しに関するアサーションを指摘します。返された状態、永続化されたデータ、発行された公開イベント、描画されたセマンティクス、または外部から観測可能なエラーに対するアサーションを推奨します。

インタラクションに関するアサーションを自動的に問題視しないでください。認可チェック、冪等性、トランザクション境界、必須のプロトコル呼び出しなど、インタラクション自体が契約である場合は維持します。

過剰なモック

大半の依存先がモック化され、アサーションがモックの動作を言い換えているだけのテストスイートを特定します。できるだけ狭く、現実に即した境界を優先します。

• 実際のドメインロジックとストア。
• 実際の動作を忠実に再現するインメモリデータベースまたはファイルシステム。
• ネットワークプロバイダーやモデルプロバイダー用の、小規模で決定的なフェイク。
• 高コスト、非決定的、破壊的、または外部所有の境界に限ったモック。

不要または実質のないテスト

スキップまたはフォーカスされたテスト、空のテスト、恒真なアサーション、古い API、到達不能なセットアップ、テスト対象のコードを削除しても失敗しないテスト、意味のない変更を受け入れるスナップショットを見つけます。

スキップされたテストは慎重に分類します。既知の問題へのリンクがある場合は、不要なコードではなく、保留中のカバレッジである可能性があります。

重複するカバレッジ

似た名前ではなく、機能と障害モードごとにテストをグループ化します。あるテストを削除しても、異なる回帰の検出能力が低下しない場合に限り、カバレッジが重複していると判断します。重複するセットアップや、密接に関連するライフサイクル動作は、まとまりのある統合テストまたはコントラクトテストのスイートに統合することを優先します。

スナップショットの過剰使用

アクセシビリティ出力、シリアライズされたプロトコル、重要な UI 状態など、安定していてレビュー可能なコントラクトにはスナップショットを残します。広範な生成マークアップやノイズの多いコンポーネントのスナップショットは、意味に焦点を当てたアサーションに置き換えます。

負のケースと境界条件のカバレッジ不足

検証、権限、キャンセル、リトライ、部分的な失敗、並行処理、マイグレーション、復旧、不明なバリアントなどについて、成功ケースしか扱っていないテストスイートを調べます。具体的なコントラクトと、現実に起こりうる回帰を特定できる場合に限り、追加を推奨します。

対応を選ぶ

各指摘につき、主な対応を必ず 1 つだけ選びます。

• 維持：そのテストは、妥当なコストで固有の動作を保護しています。
• 削除：そのテストは不要、実質のないもの、または完全に重複しており、維持されるカバレッジも明示されています。
• 統合：複数のテストが、重複するセットアップやアサーションで 1 つの機能を保護しています。
• 移動：その動作は、通常は統合またはコントラクトのレベルなど、別の境界でテストすべきです。
• 書き換え：その機能は重要ですが、現在のアサーションは誤った抽象化を保護しています。
• 昇格：低レベルのケースが繰り返し現れており、パブリックコントラクトまたはエンドツーエンドのワークフローテストが不足しています。
• 追加：リスクの高い機能に、有効な回帰保護がありません。

維持される保護を明示するか、許容するカバレッジの不足を明確にしない限り、削除を推奨してはいけません。

エージェントアプリケーションと Electron アプリケーションへの対応

該当する場合は、次の重要度の高いコントラクトを調べます。

• プロバイダー：初期化、モデルの検出、ストリーミング、ツール呼び出し、推論のサポート、使用量の報告、キャンセル、エラー。
• ランタイム：ユーザー入力、コンテキストの組み立て、モデルリクエスト、ツール実行、永続化、最終応答。
• ストレージ：セッションの作成、メッセージの追加、履歴の読み込み、マイグレーション、復旧、破損への対応。
• スキルとプラグイン：インストール、検出、読み込み、実行、権限、障害の隔離。
• デスクトップ UI：パブリックな preload または IPC コントラクトを通じたレンダラーの動作、アクセシブルな操作、永続化された状態、プラットフォーム間の違い。

プロバイダー固有のケースは、プロバイダー間に実際の違いがある場合に限って維持します。共通の動作は、再利用可能なコントラクトテストスイートにまとめます。

依頼された変更を検証する

編集する前に、変更の前後で保護される機能を特定します。テストを削除または統合する場合は、代替となるカバレッジを示す証拠を残します。

影響に応じて検証します。

1. 影響を受ける最小のテスト対象を実行します。
2. 境界の変更が妥当な理由となる場合に限り、対象パッケージのより広範なテスト対象を実行します。
3. 議論のある指摘に答えられる場合は、既存のカバレッジツールまたはミューテーションツールを使います。
4. 許可されており安全な場合に限り、対象を絞ったミューテーションを導入します。テストが失敗することを確認し、ソースを正確に元へ戻してから、テストが成功することを確認します。

テストが通ったというだけで、保護が強化されたと主張してはいけません。アサーションが検出できる現実的な回帰を説明します。

結果の報告

対応が必要な調査結果を、機能リスクの高い順に記載します。各調査結果には、以下を含めてください。

Priority:
Location:
Protected capability:
Evidence:
Problem:
Primary action:
Replacement or retained coverage:
Expected benefit:
Confidence:

続いて、以下を記載します。

1. 高・中・低価値のカバレッジの概要。インベントリが完全な場合に限り、件数を使用してください。
2. 置き換えのカバレッジを確保してから削除する順序で、移行計画を示してください。
3. 文書化された動作を根拠として、不足している高リスクのカバレッジを示してください。
4. 実施した検証と、残っているエビデンスの不足を示してください。

対応が必要な調査結果がない場合は、その旨を明確に述べ、残存するカバレッジまたは検証上の不足を列挙してください。観測された事実と推奨事項を分け、不確かな推論にはその旨を明記してください。