test-audit

テスト監査

3 つのモードで、価値の基準は 1 つです。作成モードでは、新規または変更されたすべてのテストを作成時に審査します。監査モードでは、ソースコードをそのまま再確認するテスト、より強力な証拠を重複して示すテスト、動作を実装に結び付けるテスト、テスト専用の本番コード用シームを存続させるテストを対象に、絞り込んだ監査を実施します。保守担当者がテストスイート全体の削減を求めた場合は、キャンペーンモードで、テストごとの判定を付けながらすべてのテストファイルをレビューします。キャンペーンモードを参照してください。削除数ではなく、信頼性を高めることを優先します。プルリクエストごとに一貫性のあるまとまりを 1 つ取り込み、広範な監査は別のフォローアップとして続けます。

リポジトリ独自のルールは AGENTS.md の「Testing」セクションにあります。このスキルはそれらのルールを適用する手順です。両者が食い違う場合は AGENTS.md を優先し、このファイルを更新する必要があります。

作成ゲート

テストを追加する前に、4 つの質問に答えてください。答えが 1 つでもなければ、まだ追加してはいけません。

1. どのような観測可能な動作、不変条件、または独立した契約を保護しますか？
2. どのような信頼できる回帰によって失敗しますか？
3. 既存のカバレッジでは、その失敗をなぜ検出できないのですか？各契約には、最も強力な境界（通常はリポジトリやプライベートヘルパーではなく、サービスまたは MCP ツールハンドラー）に主担当を 1 つ設けます。別のレイヤーでテストするには、それぞれ異なるリスクが必要です。ほぼ重複したテストより、テーブル駆動のケースや共有ファクトリー（ga4-test-fixtures.ts、tool-test-support.ts）の拡張を優先し、同じ変更内で重複するセットアップをまとめてください。
4. 本番コード用シーム（エクスポート、フラグ、ラッパー、注入フック）が必要で、それを使う本番コードの呼び出し元が存在しませんか？必要な場合は、実際の境界でテストしてください。src/だけでなく、リポジトリ全体で呼び出し元を grep してください。scripts/も対象です。

次に、テストをすべての不要パターンに照らして確認します。保持基準にそのテストが独立して守る契約が明記されていない限り、パターンに該当すればゲートを通過できません。動作を保つリファクタリングで壊れるテストは、動作ではなく実装を検証しています。取り込む前に、担当する境界で検証するよう書き直してください。

バグの回帰テストは、修正前のコードでは意図した理由で失敗し、修正後には成功する必要があります。失敗することが実証されていない回帰テストが証明するのは、修正ではなくモックです。バグをカバーする回帰テストは担当境界に 1 つあれば十分です。バグが通過するすべてのレイヤーで繰り返しテストしないでください。

不適切なパターン

どちらのモードにも共通するチェックリストです。作成時のゲートでは、これに該当する新しいテストを却下します。監査では、これに該当する既存テストを探します。

リポジトリ固有（それぞれが AGENTS.md のルールです）：

• リセットが必要なモジュールレベルの状態について説明するコメントがない、テストごとの await import() または vi.resetModules()；
• 本番クラスをリーフモジュール（ga4Errors.ts、gscErrors.ts がパターン）からインポートせず、テスト内で再宣言する；
• beforeEach 内での mockReset／mockClear の儀式（Vitest の clearMocks はすでに有効です）；
• それを読み取るアサーションより長いフィクスチャ、またはすでにファクトリーがある形状のインラインコピー；
• テスト対象のモジュールを介して再テストされる Zod スキーマやサードパーティライブラリ；
• すべての正常系パスで繰り返される出力スキーマの往復検証；
• モック化された Drizzle のビルダーチェーン（vi.fn() による select().from().where() のチェーン）。リポジトリはサービス経由または実際の SQL を通じてテストします；
• 対応関係が契約ではない場合の、モックへの引数の転送を検証するテスト（請求パラメーターとテレメトリーイベントは契約ですが、内部ヘルパーの引数は契約ではありません）。

一般：

• アサーションのないカバレッジ確認；
• 自己比較、およびテスト対象のヘルパーやレンダラーが生成する期待値；
• コピーされたフィクスチャ、一覧、マニフェスト、エクスポート一覧；
• ソース、インポート、文字列の厳密な grep；
• 実際の境界で重複している、プライベートな述語や呼び出し形式のテスト；
• 同じ契約の重複呼び出し；
• テスト専用のエクスポートやラッパーを維持することだけが目的のテスト；
• 呼び出し元がテストしかない、本番コードのデッドコード；
• アサート対象の動作を実装するモック、または異なる API に対して同一のモックを使用すること；
• 別のガードによる拒否や、本番の処理経路が到達しない拒否など、無関係な理由で成功するネガティブコントロール；
• 入力で検証される範囲を超える約束をする名前やフィクスチャ。

価値基準

テストは、動作、起こりうる回帰、または独立して意味のある契約を保護することで、保守コストを正当化します。監査では、動作を変えないソースの再編成で変更が必要になる既存テストは疑わしいものですが、自動的に削除対象になるわけではありません。作成時のゲートでは、引き続き新しいテストを却下します。

候補を評価する前に、テスト全体と、その本番側の所有者、エントリーポイント、呼び出し元、呼び出し先、同種の実装、重複するテスト、関連する git の履歴を確認してください。テストが依存関係に基づく動作（DataForSEO のレスポンス形状、Autumn、Better Auth、Drizzle）を主張する場合は、依存関係のソースまたは型を直接確認してください。

検出

検出は読み取り専用で行い、編集前に根拠を報告してください。対象範囲が広い場合は、読み取り専用のレーンを並行して実行してください（Explore サブエージェントが有効です）。

• src/server/mcp/ と src/server/mcp/tools/；
• src/server/lib/、src/server/auth/、src/server/billing/、 src/server/workflows/、src/serverFunctions/；
• src/server/features/；
• src/client/、src/shared/、src/lib/、src/types/、scripts/、 web/tests/ に加え、上記のリポジトリ固有パターンを横断的に grep で調査する。

推測に基づく大量の候補より、確度の高い候補を少数選んでください。

キャンペーンモード

メンテナーがスイート全体の整理を明示的に依頼した場合にのみ使用してください。エージェントが同じファイルを編集しないよう、重複しないファイルの範囲に分けて、パイプラインを2つのフェーズで実行します。

1. レビュー、読み取り専用。 すべての *.test.ts を、行数のバランスを取り、ディレクトリごとにまとめた6〜8個の範囲に分割します。各範囲のレビュー担当者は、各テストファイルとその本番コード側の所有者をすべて読み、ファイルごとに次の項目を記載した表を含むレポートを作成します。テスト名、DELETE / MERGE / KEEP、失敗するコード変更またはすでにそのテストを担保しているテスト名を挙げた、根拠を示す1行の説明。レポートには、テスト専用の本番コードの境界部分（src/、scripts/、tests/badseo/、web/ 内の呼び出し元を確認）、使われなくなるテスト支援コード、削除するファイル全体、および「リスクのある呼び出し」セクションも記載します。レビュー担当者は編集しません。
2. 適用、範囲ごと。 各範囲に1人の適用担当者を割り当てます。操作の前に、各DELETEとMERGEをソースと照合して再確認し、根拠が成り立たないものはすべて残します。MERGEの行は、テーブル駆動型の同種テストに統合します。新たに使われなくなったフィクスチャとモックを削除し、リスクのある項目はすべてスキップしてメンテナーへの報告対象にします。削除の根拠に別の範囲のテストが記載されている場合、適用担当者は自分の作業終了時にもそのテストが存在することを確認します。

キャンペーン全体を通じて適用されるルール：

• テスト以外で許可される唯一の編集は、残る呼び出し元がすべてテストであるヘルパーから export キーワードを削除することです。そうしないと、孤立したエクスポートによりKnipが ci:check で失敗します。同じ変更で、パラメーターを削除したり、分岐を削除したり、動作を変更したりしてはいけません。テストがコードの存在理由に見える場合でも同様です。そのような項目はフォローアップとして報告してください。
• src/routes/ 以下のルートモジュールとバレルファイルのエクスポートは保持します。
• pnpm exec prettier --write <files> を使用してください。pnpm format:write は引数を無視し、リポジトリ全体をフォーマットします。
• すべての範囲の変更が反映されたら、通常の順序でスイート全体を実行し、さらに --sequence.shuffle.tests --sequence.seed=<n> を指定して2〜3回実行します。リセットの儀式を削除すると、潜在的な実行順序依存が表面化する場合があります。その場合は、儀式を復元するのではなく、beforeEach でモックのデフォルト値を設定して修正してください。

保持基準

パブリックAPI、MCPツールの契約、Zodの境界スキーマ、設定、マイグレーション、ストレージ（SQLiteとPostgresの両方）、課金、認証、セキュリティ、デフォルト値、プロンプトのバイト列、またはパッケージの契約を個別に担保するテストは保持してください。また、次のものも保持します。

• 呼び出し順が観測可能な動作である場合の呼び出し順。
• 信頼できる失敗モードを伴うリグレッション。
• 最も簡潔に独立した保護となるソース検査。契約が変更されたときに失敗し、識別子だけのリファクタリングでは失敗しないもの（ユーザーに表示されるキー、バイト列、パスなど）。samSkills.test.ts の固定されたSAMスキル一覧と src/db/schema-parity.test.ts のユニークインデックスの同等性チェックがこの種に該当します。
• ベースラインで失敗する保持対象のテスト。その場合は製品のバグの可能性があるものとして扱い、再現したうえで、テストを削除せずに所有側を修正します。

静的であることや遅いことは、削除理由になりません。実装に似ているテストでも、独立した契約を担保している場合があります。削除する前に、そうではないことを証明してください。

候補の根拠

編集前に、すべての項目を記録してください。項目が1つでも欠けている候補は、削除の準備ができていません。

• 正確なテスト名と場所。
• 実際に検出できる障害。
• 対象となる本番コードまたはテスト支援コードの、テスト以外の呼び出し元。scripts/、tests/badseo/、web/ 内のものも含みます（プロファイリング用スクリプトも呼び出し元です）。
• より強力な、残る所有境界による証明、または証明が不要な理由。
• 関連する履歴と、そのテストまたはコードの境界部分が存在する理由。
• 削除によって可能になる本番コードまたはテスト支援コードの削除。
• リスクと、対象を絞った検証コマンド。

編集範囲

一貫した所有境界に沿って、ひとまとまりの対象を選びます。不要になったテスト専用のエクスポート、ラッパー、使われていない本番コードの経路は、別名を残さず削除します（残存項目は pnpm ci:check で Knip に検出されます）。残す回帰テストは、それぞれの正式な所有先に移します。繰り返されるアサーションは、テーブル駆動のケースにまとめます。

本番コードの行数は純減を目指します。同じ実装を言い換えるだけのテストを追加したり、削除数を増やすために確実性の低い候補をクリーンアップ対象にしたりしないでください。

検証

チェックアウトで Vitest の実行中にテストを編集してはいけません。

1. 所有先と関連するテストを実行します：pnpm exec vitest run <path-or-filter>。
2. ソース内の文字列検索や静的アサーションを削除した場合は、実際の契約を担う実行可能ファイルを実行します（たとえば、プラグインのスキルのずれを検証する pnpm sync-plugin-skills）。
3. pnpm format:write の後、pnpm ci:check を実行します（prettier、knip、tsc、oxlint、plugin-skill sync）。使われなくなったエクスポートが原因で Knip が失敗した場合は、テストを再追加せず、そのエクスポートを削除します。
4. 全テストを一度実行します：pnpm test。
5. git diff --numstat を確認し、本番コード／ツール関連とテスト／テスト支援コードを分けて報告します。

取り込み

許可がある場合に限り、コミット、プッシュ、または PR の作成を行います。レビューと PR の手順には merge-ready スキルを使用します。検証済みの指摘から、.greptile/ に記載されていない繰り返し発生する不変条件が明らかになった場合は、maintain-greptile-rules を使用します。一度きりのクリーンアップを恒久的なルールに昇格させてはいけません。作業中に遭遇したリポジトリの摩擦は papercuts に記録します。

引き継ぎ

以下を報告します。

• 削除した価値の低い項目の分類と、その根本原因。
• 所有先となる本番コードの簡素化。
• 残した誤検知と、それが有用である理由。
• 実際に実行した、対象を絞った検証と全体検証、および実際の出力。
• 本番コードとテストコードの行数。
• PR とマージの状況。
• 担当者を明記した今後の対応。