test-audit

テスト監査

正当化できるコストの範囲内で、信頼性と有用なフィードバックを最適化します。意味のある契約は維持します。不審なテストの形は、削除の判定ではなく、調査すべき手がかりとして扱います。

1. スコープと権限を定める

ユーザーの既存の指示に基づいて、スコープとモードを判断します。

• 監査： 編集せずに調査、レビュー、または提案を行います。
• クリーンアップ： 整理、削減、修正、または調査結果の実装を求める依頼は、スコープ内のテストとテスト支援コードの編集を許可します。まず調査し、すでに与えられている承認を再度求めずに続行します。
• キャンペーン： リポジトリ、モノレポ、またはサブシステム内のすべてのテストが対象の場合は、references/campaign.md を読みます。以下の基準と併せて、同ファイルの網羅的な一覧とバッチ実行手順を使用します。キャンペーンでは完全性を定めますが、監査かクリーンアップかによって編集権限は引き続き決まります。

タスクを伴わない呼び出しでは、デフォルトで監査を行います。指定されたスコープ全体をレビューします。対象外、未レビュー、レビューしたが阻害要因がある作業を区別します。重大な判断が未解決でも、独立して進められる作業は続行し、影響を受ける範囲についてのみ質問します。

テストのクリーンアップとは別に許可されていない限り、製品の動作、公開 API、依存関係、CI ゲート、カバレッジのしきい値には手を加えません。製品の修正案や本番コードの簡素化案は、別途提示します。コミットと公開については、既存の許可に従います。

モード、対象テスト、除外対象、編集範囲を特定した時点で完了です。

2. プロジェクトとベースラインを把握する

適用されるルートおよびスコープ別の指示を読み、分割可能な調査作業は /swarm を通じて積極的に委任します。デフォルトでは、読み取り専用のサブエージェントを3つ並行して起動します。

• テスト一覧： マニフェスト、テストランナーの設定、CI 定義、エンジニアリング関連ドキュメントを読みます。テストファイル、共通支援コード、テストの検出、ルーティング、コマンドを整理します。
• 本番コードの動作： テストが対象とする本番コードの所有箇所、エントリーポイント、呼び出し元、依存関係の契約を追跡します。
• テストの価値： アサーション、重複するテスト、保守コストを調べます。修正、統合、削除の候補について根拠を報告します。

各サブエージェントには、スコープ、適用される指示、ステップ3の基準を伝えます。ファイルへの参照、根拠、未解決の疑問を報告するよう求めます。親エージェントは結果を照合して単一の一覧と記録にまとめ、最終判断、編集、検証を担います。スコープが狭い場合や処理能力に制約がある場合は、サブエージェントの数を減らします。委任できない、または禁止されている場合は、/swarm が明示する代替手順に従い、順次作業してその旨を記録します。

実際に存在するユニット、コンポーネント、統合、契約、エンドツーエンド、ビジュアル、プロパティ、アーキテクチャ、ツールの各テストを特定します。ディレクトリ内のテストや、CI で実行される埋め込みサンプルも含めます。共通フィクスチャとパッケージをまたぐ利用箇所を記録します。生成ファイルやベンダー提供ファイルを除外する場合は、理由を明記します。関連する場合は、その生成元や管理対象のテストを調べます。

開始時のリビジョンと、取得可能な場合は作業ツリーの状態を記録します。編集前に、最終検証で使用する予定の環境と選択条件をそろえて、関連するベースラインコマンドを実行します。既存の失敗、フレーキーな結果、インフラの障害、スキップされたテスト、未実行のテストを区別します。意味のあるカバレッジを維持しながら、既存の失敗を調査します。実行できない場合も、静的な調査と独立して進められる作業は続行します。

調査結果を照合し、要求されたスコープについて、一覧、確認済みコマンド、ベースライン結果または明示的な実行制限をそろえた時点で完了です。

3. 判断基準を適用して記録する

調査の優先順位付けには、候補パターンを使用します。各テストのセットアップ、アサーション、パラメーター行、関連する本番コードの経路、重複するカバレッジを読みます。必要に応じて、呼び出し元、依存関係の契約、CI のルーティング、履歴を調査します。テスト品質の基準を定める /principle-test-behavior-not-implementation を適用し、以下の問いを検討します。各テストについて、次の点を判断します。

1. 契約： どのような観測可能な動作、不変条件、または独立した要件を保護していますか？
2. リグレッション： どのような、もっともらしい誤った実装によってテストが失敗しますか。また、その失敗をアサーションが検出できますか？
3. 独立性： 期待される結果は実装と異なる可能性がありますか。それとも、テストが両方を自ら作り出していますか？
4. 境界： 契約に適した公開インターフェースまたは安定した境界をテストしていますか？ 動作を保つどのような実装変更があっても、アサーションは通過すべきですか？
5. 固有の価値： 残りのテストでは得られない、どのような有用な障害検出、診断、または実行可能なドキュメントを追加していますか？
6. フィードバックとコスト： 意図と失敗は明確ですか？ 有用なフィードバックは、実行と保守のコストに見合っていますか？

要件、文書化されたインターフェース、バグの履歴、プロトコルのルール、実例、確立された呼び出し元の期待を、根拠として使用してください。形式仕様は有用な根拠ですが、有用なカバレッジの前提条件ではありません。ドキュメントや履歴がない場合は、不確実性が残ります。意図された動作を確定できない場合は、明確化までテストを保持し、未解決として記録してください。

失敗を明らかにできる、最もコストが低く安定した境界を優先してください。安定したインターフェースを通じて、純粋なルールは実装に近い位置でテストしてください。分離されたテストでは到達できない、配線、シリアライズ、ストレージ、ライフサイクル、トランスポートのリスクについては、統合テストを残してください。重要なワークフローはユーザー境界でテストしてください。契約ごとに主要な担当テストを1つ選びつつ、他のレイヤーにも固有の価値を残してください。契約が求める性質だけをアサートし、構築方法が変わる場合はテストのセットアップを調整できるようにしてください。

既存の依存関係の境界を使って、協調オブジェクトを制御してください。モックより、実用的な実装や保守されているフェイクを優先してください。テスト対象の依存関係の契約をダブルが守っていることを確認し、シミュレートされた動作について、統合テストまたは契約に関する根拠を明らかにしてください。テスト対象の本番動作をダブルで代替するのではなく、実際に実行してください。

アクセシブルなインタラクション、ワイヤーフォーマット、ビジュアルベースライン、アーキテクチャルール、パッケージの公開範囲、マイグレーションなど、意図された契約を独立して保護している場合は、スナップショット、ソースコードの検査、完全一致のテキスト、ジオメトリ、呼び出し順序、時間のかかるテスト、モックを残してください。公開されたエクスポート契約の検証と、現在のエクスポート一覧を機械的に複製することを区別してください。内部に呼び出し元がないというだけでは、公開エクスポートが古くなったとは判断できません。

編集の前に、価値、判断、根拠を簡潔に台帳へ記録してください。根拠と判断が一致する場合にのみケースをまとめ、異なる理由があるパラメータ行は分割してください。スキップまたは無効化された実行は、価値とは別に記録してください。

テストまたはパラメータケース	契約／もっともらしい失敗	判断	価値と維持される根拠	検証

次の判断を使用してください。

• KEEP： 正当なコストで、有用かつ固有のフィードバックを維持します。
• REPAIR： アサーション、セットアップ、決定性、明確さ、コスト、またはテスト対象の境界を修正し、契約を維持します。
• CONSOLIDATE： 重複を削除する前に、必要なケースを名前を付けた存続するテストスイートへ移します。
• DELETE： 意味のある契約が失われないこと、または特定済みの存続するテストがすでに保護していることを根拠で確認した後、正当な貢献がないテストを削除します。
• UNRESOLVED： 既存のカバレッジを維持し、不足している根拠または判断を明記します。

DELETE と CONSOLIDATE では、入力、否定ケース、アサーション、統合経路、CI での実行を比較し、正確な存続証明を特定してください。または、そのテストが意味のある契約を保護していない理由を説明してください。履歴が確認できる場合は調べ、その履歴がない場合は正直に記録してください。名前、セットアップ、実行行、パターンマッチの重複や、削除後にスイートが成功することだけでは、冗長性の根拠になりません。 REPAIR では、テストの欠陥、修復によって取り戻される有用なフィードバック、その修復に適した証拠を特定します。既存のアサーションは変更せずに残してもかまいません。

対象範囲内のすべてのテストまたは個別のケースグループについて判断と証拠が揃ったら完了です。監査モードでは推奨事項を添えてステップ 6 に進み、クリーンアップモードでは以下を続けます。

4. 振る舞いごとにクリーンアップを適用する

編集内容を、それらが属する振る舞いやサブシステムごとにまとめます。固有のケースは、元の配置場所から削除する前に移します。行数を減らすことだけを目的にせず、読みやすさと安定したセットアップを優先して、テーブル駆動のケースや共有フィクスチャを選びます。

記録したテストの欠陥を修正します。アサーションと意味のあるシナリオを維持しながら、根本原因で不安定さを解消します。再試行はその修正の代わりにはなりません。非同期のエンドツーエンドテストでは、ハーネスのタイムアウト付き待機を使って、必要な観測可能な状態になるまで待ちます。アクションが戻っただけでは、その後の処理が完了した証拠にはなりません。

新たに不要になったフィクスチャ、インポート、スナップショット、ヘルパー、セットアップを削除します。他のパッケージで使われているサポートは維持します。テストを移動する場合も、テストの検出と既存の CI ルーティングを正しく保ちます。結果をグリーンにするためにゲートを弱めたり、テストを隔離したりしてはいけません。

新規または書き換えたテストについては、ステップ 3 の価値に関する質問に答えます。バグの再発防止テストでは、可能であれば修正前の振る舞いで意図した理由により失敗し、修正後に成功することを示します。実行できない場合は、未検証であることを記録します。

許可されたすべての判断が適用済みまたは明示的にブロックされ、固有のケースに所有者が割り当てられ、共有利用者に影響を与えずに新たに不要になったサポートが削除されたら完了です。

5. 保全を検証する

検証中はファイルを変更しないでください。入力を編集する前に、関連する実行を完了するか停止します。無関係なプロセスや作業中の変更はそのまま保ちます。

1. 影響を受ける最小のスイートを実行し、次に関連する兄弟パッケージおよびパッケージ横断の利用者と、リポジトリで必須のゲートを実行します。プロジェクトから確認できるコマンドを使用します。
2. 移動したテストが検出・実行され、意味のあるパラメーターケースが引き続き網羅されていることを確認します。削除したソーススキャンや計画アサーションがスクリプトやコマンドを保護していた場合は、それを所有する実行可能ファイルまたはドライランを実行します。
3. /swarm を通じて、影響を受ける変更を提案していないサブエージェントに保全の比較を委任します。必要に応じてステップ 2 のフォールバックを使用します。元の契約とケースを、残存するアサーションと比較します。該当する場合は、固有の入力、エラー、境界ケース、セキュリティ、アクセシビリティ、順序、相互作用、統合パス、CI 環境を確認します。不足している契約は適切な所有者のもとに復元します。
4. 記録した欠陥に照らして修復を検証します。リスクが高いアサーションや曖昧なアサーションには、対象を絞ったネガティブコントロール、または小規模な一時的変更を使い、保持されたテストが意図した失敗を検出することを示します。独立した環境で作業し、その確認のために加えた変更のみを元に戻して、ユーザーの編集は維持します。通常のクリーンアップで網羅的なミューテーションテストを要求する必要はありません。
5. 該当するフォーマットチェック／静的チェックを実行し、最終差分を調べて、意図しないスコープの拡大、不要になったサポート、弱められたアサーション、設定変更がないか確認します。削除の一括処理を完了する前に、利用可能であればプロジェクト既存の未使用ファイル、エクスポート、依存関係のチェックを実行します。検出結果を共有利用者や公開されている契約に照らして確認し、実行できなかったチェックを報告します。本番コードや公開 API の削除は、別途提案します。

ベースラインと最終結果を照合します。コマンド、テストの選択、結果、利用できない環境を正確に報告します。キャッシュされた結果は、新たに編集したテストが実行された証拠にはなりません。具体的なリスクに対処し、必須ゲートを満たしたら、任意の検証は終了します。

影響を受けるすべての契約について、残存する証拠または記録済みの未解決事項があり、必須チェックすべてについて結果または明示的な実行上のブロッカーがある状態になったら完了です。

6. レポート

結果が読み取り専用の監査なのか、クリーンアップ完了なのか、部分的な作業なのかを明記してください。判断内容と代表的な所見を要約してください。網羅的なキャンペーンでは、すべての KEEP をチャットに貼り付けず、完全な台帳を提示してください。以下を含めます。

• 除外項目と未解決項目を含む、範囲とインベントリの照合。
• 削除または統合したテストと、それらの契約を現在どのように保護しているか。
• 修正したテストと、説明が必要なまま残る誤検知。
• ベースラインと最終検証、失敗、スキップまたは未実行のチェック。
• 別途対応が必要な製品の不具合や本番コードの簡素化。

レビュー範囲と実行結果は分けて報告してください。テスト数や行数の削減は、安全性の証明にはなりません。

ユーザーが完了した作業と未解決の判断、未検証の主張を区別できる状態になれば完了です。対象範囲内のすべてのテストをレビューし、許可されたすべての判断に対処した場合に限り、クリーンアップ完了と報告してください。未解決の判断がある場合、クリーンアップは部分的なものです。実行上の制約は別途明記してください。

候補となるパターン

以下の手がかりを検索してから、判断を下す前にステップ 3 を適用してください。

• テスト対象と同じコードで期待値を算出している。宣言とそのコピーを比較するアサーション。
• 本番コードの経路が生成すべき動作や結果を、モックやフィクスチャが与えている。
• 本番コードが書き込まない保存先パスに対して、永続化をアサートしている。
• 約束された配信や確認応答ではなく、機能フラグをアサートしている。
• 意味のある成功／失敗の契約がない、アサーションなしの実行。「例外が発生しない」などの暗黙のアサーションも考慮してください。
• 編集の検出はできても、どの契約が壊れたかを特定できないソーススキャン、スナップショット、オブジェクト全体の比較、カウント、プライベート呼び出し、偶発的なコピー。
• 独自の価値がない重複したケースやレイヤー。
• ヘルパーはテストしているものの、実際のエントリーポイントの配線を見落としているテスト。
• 無関係な先行ガードが入力を拒否することで合格している否定テスト。
• 意図した結果と実質的な失敗を区別できない広範なアサーション。
• タイミング調整のスリープ、共有された可変状態、テスト順序、制御されていない時計や乱数、解放されないリソース。
• テスト専用のエクスポートやフック、古くなったフィクスチャ、スキップされたスイート、無効化されたアサーション。
• 入力やアサーションでは実際に検証していない動作をうたう名前。
• 不透明なセットアップや失敗、高コストな実行、有用なフィードバックが乏しいにもかかわらず頻繁なメンテナンスを要するもの。

出典情報

OpenClaw のテスト監査とそのキャンペーンのワークフローをもとにしています。上流の資料や帰属を更新する前に、UPSTREAM.md を読み、ソースのリビジョン、ライセンス、ローカルでの適応内容を確認してください。