gjalla-test-audit

テスト監査

テストスイートの品質を詳しく確認し、誤った安心感を与えるテスト、バグを仕様として固定するテスト、カバレッジが重複するテスト、またはモックに依存しすぎて実際のリグレッションを検出できないテストを見つけます。

プロセス

大まかには、以下の手順に沿って調査し、その後、重要な役割を担うコードとテストからのインポートを相互参照します。重要度は、本番環境への影響範囲（最も依存されているコードはどれか。gjalla を使う場合は、影響範囲と変更履歴から判断できます）、最近のバグ履歴、そして障害の発生条件がどれほど決定的かを基準に順位付けできます。

フェーズ 1：全体像を把握する

詳しく調べる前に、プロジェクトのテスト基盤を理解します。

1. テスト構造を把握する：すべてのテストディレクトリを見つけ、ディレクトリごとのファイル数を数え、命名規則（.test.ts、.pglite.test.ts、.integration.test.ts など）を特定します
2. テストレイヤーを特定する：実データベース（PGlite、SQLite）を使うテストはどれですか？ORM をモックするテストはどれですか？サービス境界でモックするテストはどれですか？また、どれが @vitest-environment node を使い、どれが jsdom を使いますか？
3. 重要なコンポーネントを特定する：セキュリティ境界、データアクセスレイヤー、コアビジネスロジックはどこですか？誤った安心感が最も危険なのはこれらの箇所です。

フェーズ 2：アンチパターンを探す

テストレイヤーごとに並行して調査します。各テストファイルについて、テストと、テスト対象とされるソースコードの両方を読みます。見つけるべきアンチパターンは以下のとおりです。

アンチパターン 1：ロジックを再実装したテスト

実際のコードを一切インポートせず、ロジックをその場で再定義して、自分で書いたコードをテストするテストです。兆候：

• コンポーネントやフックのインポートがない @vitest-environment node
• ソースコードを模倣した simulate* や handle* という名前のローカル関数
• src/ またはソースディレクトリからのインポートが一切ないテストファイル

これらのテストでは実際のコードが実行されないため、リグレッションを検出することは決してできません。

アンチパターン 2：同語反復的なモックテスト

データベース／ORM の呼び出しチェーン全体を固定値でモックし、その同じ固定値をアサートするテストです。兆候：

• db.select().from().where() チェーンでの mockReturnValue／mockResolvedValue
• キューベースのモック基盤（_setSelectQueue、pushSelectResult）
• expect(result).toEqual(mockReturnValue) のようなアサーション。ここでの mockReturnValue は、モックに設定した値です
• .from()、.where()、.innerJoin() がすべて引数を無視するビルダーパターンのモック

重要な確認事項：実際のコードにバグ（誤ったテーブル、誤ったカラム、誤った WHERE 句、誤った JOIN など）があった場合、このテストは失敗しますか？失敗しないなら、そのテストは同語反復的です。

アンチパターン 3：誤った動作を固定するテスト

ソースコードのバグとたまたま一致する、誤った動作をアサーションで検証するテストです。兆候：

• ソースと一致しないフィールド名を使ったテストフィクスチャ（例：テストでは assignedTier を使う一方、ソースでは subscriptionTier を参照している）
• 個別にテストされるサービス間でしきい値に一貫性がない
• テストが検証すると主張するロジックを覆い隠すモックの戻り値
• 名前に書かれた内容と異なるアサーション（例：「403 を返す」とあるのに toBe(404) をアサートする）

重要な確認事項：テストのモックデータは、実際の上流コードが生成するデータと一致していますか？それとも、（バグがある可能性のある）テスト対象の関数に合わせて手作業で作られたものですか？

アンチパターン 4：重複する補完テスト

より厳密な別のテストファイルですでに完全にカバーされているテストです。兆候：

• 同じクラスの実 SQL をテストする .pglite.test.ts ファイルと並行して、DB をモックする .test.ts ファイルがある
• 「統合」テストが「単体」テストと同じレベルでモックしている
• 同じソースファイルに対して、重複する describe／it ブロックを含むテストファイルが複数ある

アンチパターン 5：プレースホルダーテスト

• expect(true).toBe(true)
• 説明的な名前が付いているが、実質的なアサーションがないテスト
• モックを呼び出した後、そのモックが呼び出されたことをアサートするテスト（同語反復）

フェーズ 3：調査結果を分類する

調査結果を次の段階に分類します。

段階	説明	対応
段階 1	実際のコードをまったく実行しないテスト（ロジックの再実装、インラインのモックハンドラー）	ファイル全体を削除
段階 2	有用なテストと同語反復的なテストが混在するファイル	同語反復的な部分を削除し、ロジックのテストは残す
段階 3	実際の代替テスト（PGlite、統合テスト）がある同語反復的なテスト	冗長なモック版を削除
段階 4	実際の代替テストがない同語反復的なテスト	危険な誤った安心感をもたらすものとしてフラグを立てる。実際のテストを作成する必要があります。
バグ	ソースコード内の誤った動作を正しいものとして扱うテスト	ソースコードとテストの両方を修正

フェーズ 4：報告する

調査結果を次の項目を含む構造化されたレポートとして提示します。

1. バグを正しいものとして扱うテスト（最優先） - 実際の本番環境の問題を覆い隠しています
2. 段階 1〜3 の削除対象（ファイルパスと行数を記載）
3. 段階 4 の不足箇所 - カバレッジが正直に低下し、実際のテストが必要となる領域
4. 影響分析：より堅牢になる箇所、表面化する可能性のあるバグ、カバレッジへの影響

フェーズ 5：クリーンアップする（承認された場合）

各段階の間にテストを実行しながら、次の順に進めます。

1. 段階 1 のファイルを削除する（実際のコードをまったくテストしていないもの）
2. 段階 2 の同語反復的な部分を削除する
3. 段階 3 の冗長なテストを削除する（代替テストがある場合）
4. 誤った動作を正しいものとして扱うテストを修正し、ソースコードのバグも修正する
5. カバレッジを実行して、正直に評価した不足箇所を特定する
6. 段階 4 の不足箇所を補う実際のテストを作成する（DB 依存コードには PGlite を使用）

原則

• 失敗しないテストは、テストがないよりも悪いです。 保護を提供せずに、安心感だけを高めます。
• モックは内部ではなく境界に配置します。 外部サービス（Supabase、Stripe、GitHub API）をモックします。PGlite を使える場合は、自分たちのデータベースレイヤーをモックしません。
• 往復テストはキーの不一致を検出します。 関数 A が書き込んだデータを関数 B が読み取る場合、A の実際の出力を B の入力として使い、両者を一緒にテストします。手作業で作ったフィクスチャには、気づかないうちにバグが入り込むことがあります。
• テストが同語反復的な場合、カバレッジの数値は当てになりません。 モックが意味のある操作をすべて横取りしているなら、その行は「カバー済み」ではありません。正直なカバレッジは、実際のコードパスを実行するテストから得られます。
• 書く前に削除します。 まず誤った安心感を取り除き、カバレッジレポートを、強みとリスクがある領域を正直に示すものにします。その後、不足を補います。