Codexでテスト失敗を解決する：エラーログと依頼例

要約： テスト失敗の解決依頼には実行コマンド、失敗ログ、期待動作、変更境界を含めてください。テストを成功させることと機能が正しく動くことは分ける必要があります。

1. テスト失敗を一種類と考えない

失敗画面には異なる問題が混ざる場合があります。値が期待と違う場合、モジュールを読み込めない場合、テストコマンド自体が実行されない場合は出発点が異なります。「赤い文字が出たから関数が誤っている」と断定すると、不要なコード修正をすることがあります。

まず実行がどこまで進んだか確認してください。テスト事例を実行して値の比較で失敗したか、その前にツールや設定が見つからなかったか分けます。ローカルだけで失敗するかCIでも同じか分かれば、文脈として併記します。未確認なら「CIでは正常」と推測せず、未確認と表示すれば十分です。

2. Codexに渡す最低限の情報

OpenAIの公式バグ修正案内は再現手順、制約、修正後の確認を含む依頼を説明しています。テスト問題にも実行コマンドと再現条件を伝える方法が有用です。以下はその原則をテスト失敗の調査に適用した独自のチェックリストです。

• プロジェクトで実行した正確なコマンドと作業フォルダー
• 失敗したテスト名と主要なエラーメッセージ
• 正しい動作に関する要件
• 最近の変更と保全する機能
• ローカルとCIの差を実際に確認したか

ログは最初のエラーに関係する部分から共有してください。トークン、パスワード、個人情報が混ざるか確認し、不要な秘密の値は削除します。最後の「失敗」だけでは原因を示す前の部分が抜ける場合があります。逆に数千行を説明なしで貼り付けると、関連情報を探す負担が増えます。

3. 架空の失敗用の依頼テンプレート

가격 합계 계산 테스트가 실패합니다.
실행 명령: [실제로 사용한 명령]
실패 테스트: [실제 테스트 이름]
핵심 로그: [민감정보를 제거한 오류 내용]
기대 동작: 수량이 0인 항목은 합계에 포함하지 않습니다.
최근 변경: 수량 입력 검증을 수정했습니다.

원인부터 조사하고 코드 오류와 환경 오류를 구분해 주세요.
공개 함수의 입력·반환 형식은 유지해 주세요.
통과만을 위해 기대값을 바꾸거나 테스트를 삭제하지 마세요.
수정 후 같은 명령과 관련 검증을 실행하고 결과를 보고해 주세요.
실행하지 못한 검증은 이유와 함께 표시해 주세요.

角括弧には実際の情報を入れる必要があります。価格計算の正常な規則が不明なら、要件文書や既存の呼び出し側を確認するよう依頼してください。テストの期待値も実装も常に正しいわけではありません。どちらを修正するか判断する基準が必要です。

4. 修正後は同じ失敗を再確認する

最初の検証は元の失敗コマンドに戻ることです。別のテストの成功だけで既存問題が解決したとは判断できません。失敗した事例が成功するか、関連する正常事例が維持されるかを確認する必要があります。変更の影響範囲に合わせて検証を追加してください。

例えば数量0の処理を変えたら、正常数量、複数項目の合計、不正数量の処理も確認対象に考えられます。必要事例はプロジェクトの要求で異なります。報告では「実行した」「成功した」「環境により実行できなかった」を明確に分ける必要があります。テストを新規作成した事実自体は実行結果と異なります。

5. 失敗が続く際に確認する質問

• 失敗箇所は変わったか？ 新しいエラーと既存エラーを分けて比較します。
• 環境は準備済みか？ 必要ツール、依存関係、ローカル設定を確認します。
• 外部サービスに依存するか？ 接続失敗と機能の誤りを区別します。
• ときどきだけ失敗するか？ 再現条件と実行記録を残し、原因を断定しません。
• テスト内容が弱まったか？ 期待値の変更や検証の削除が要求に合うか確認します。

PRの失敗した検査から作業を始める流れも、公式のコードレビュー文書が案内しています。診断は検査サービスによって異なり得るため、画面に失敗状態だけが出るか、実際のログまでつながるか区別してください。

6. エラーメッセージから次の調査箇所を選ぶ

長いログを最初から全て解釈しようとせず、どの段階でテストが止まったか探してください。コマンド開始、設定読み取り、依存関係の読み込み、テスト実行、結果比較に分けると調査箇所が変わります。以下のエラー表現は種類の説明用です。実ツールの表現と環境で異なるため、自分の最初のエラーを基準に判断する必要があります。

コマンドのエラーを関数修正で、値比較のエラーを再インストールだけで解決しようとすると、元の失敗を見失う場合があります。Codexの措置がログのどの段階につながるか尋ねてください。問題が複数あれば最初の実行を阻む原因を解決し、次の失敗を読み直します。ログの変化は必ずしも悪化ではなく、前の段階を通過して次の問題が見つかった可能性があります。

7. 架空の合計テストを再現情報に整理する

次は数量0の問題の説明用の架空事例で、実際のテスト実行記録ではありません。JavaScriptプロジェクトのnpm testがVitest実行に設定され、tests/total.test.jsがあると仮定します。その条件のないプロジェクトで下のファイル名やコマンドをそのまま使えません。

실행 폴더: C:\Projects\cart-demo
실행 명령: npm test -- tests/total.test.js
실패 사례: 수량 0 항목은 합계에서 제외
가상 비교 로그:
Expected: 0
Received: 1200
입력: [{ price: 1200, quantity: 0 }]

調査する関数が下のようなら、0が既定数量1に変わる部分が原因候補です。計算経路からそう説明できますが、実際の失敗と同じ原因か確認するにはテスト入力と呼び出し側をつなぐ必要があります。テストが別の関数を呼ぶ、または設定により別実装を使うなら、このコードだけ直しても元の失敗が残る場合があります。

function sumCart(items) {
  return items.reduce((total, item) => {
    const quantity = item.quantity || 1;
    return total + item.price * quantity;
  }, 0);
}

修正方針を定める際は値の省略に関する既存方針も見ます。「数量がなければ1」が意図なら、0と省略を区別する処理が必要です。負数や文字列をどの層で検査するかは別の要求です。今回の修正で任意の数値変換やデータ形式の変更まで追加しないよう範囲を定めてください。

실패 입력이 실제로 호출하는 함수를 찾아 주세요.
수량 0과 값 누락을 현재 코드가 어떻게 구분하는지 설명하세요.
기존 요구사항과 테스트의 기대값이 맞는지 먼저 확인하세요.
그 근거를 바탕으로 최소 수정하고 원래 실패 명령을 다시 실행하세요.
입력 형식이나 다른 수량 정책을 임의로 새로 정하지 마세요.

8. 失敗事例に近い正常動作まで確認する

一事例を成功させるため全数量を0にすれば、失敗テストは成功しても機能は壊れます。そのため修正後は元の失敗と近い正常事例を併せて見る必要があります。次の表は架空の合計要件に基づく検証設計です。未定の方針は答えを作るより要件確認項目に残します。

まず元の失敗事例を再実行し、関連検証を行います。その後は変更の影響に合わせてプロジェクトの必須検査を進めてください。小さな関数修正に無関係なツールを新規インストールするより、既存の検証手順に従う方がよいでしょう。逆に複数の呼び出し側が使う共通関数の変更なら、それらの期待動作も確認する必要があります。

テストコードを変えたら差分で変更を読んでください。入力条件の弱体化、検証文の削除、skip後の成功報告は元の問題の解決根拠になりません。要件自体が変わったなら根拠を残し、新方針を検証する変更は可能です。実装とテストのどちらが正しいかは製品規則で決めます。

9. ローカルとCIの差、ときどき失敗する問題の調査

ローカルでは成功しCIでは失敗するなら、実行環境を表で比較してください。実際に確認したバージョンとコマンドだけを書き、未確認のCI設定は未確認のまま残します。OS差でファイル名の大小文字やパス処理の問題が現れたり、時間帯・環境変数・サービス準備状態で結果が変わったりすることがあります。これらの可能性を全て原因と断定しないでください。

로컬 통과와 CI 실패를 비교해 주세요.
각 환경의 실제 실행 명령, 작업 폴더, 런타임 버전,
설정 파일, 필요한 서비스의 준비 조건을 근거와 함께 정리하세요.
첫 오류가 같은지 비교하고 차이와 실패 사이의 연결을 조사하세요.
확인되지 않은 환경 정보는 추측하지 마세요.

ときどき失敗する場合は成功と失敗の差を集めることが出発点です。実行順、同時実行テスト、共有データ、時間依存の入力などを記録してください。待ち時間を無条件に延ばすと症状を隠す場合があるため、何を待つかを先に説明させます。特定順だけで失敗するなら、前のテストの残存状態が次のテストへ影響するかも調査できます。

이 테스트는 가끔 실패합니다.
실패한 실행과 성공한 실행의 로그를 각각 제공합니다.
차이를 비교하고 재현 가능한 조건부터 좁혀 주세요.
대기 시간 증가나 무조건 재시도보다 실패 원인의 근거를 우선 찾으세요.
원인을 확정하지 못하면 추가로 수집할 정보와 다음 실험을 제안하세요.

最終結果には元のコマンドの結果、関連する正常事例、必要な後続検証を残してください。元の失敗を再現できずに修正した場合は、その制限を説明する必要があります。CIログを読んだことと、CIを再実行して成功したことは異なります。報告が区別されていれば次の担当者が同じ条件で調査を続けられます。

10. よくある質問

失敗テストだけ削除してもよいですか？ 何を保証していたテストか先に確認してください。製品規則が変われば根拠を残して検証を修正できますが、失敗を隠す削除では解決を証明できません。

一度成功すれば完了ですか？ 不定期の失敗では一度の成功だけで原因を確定しにくくなります。発生条件と修正根拠を併せて確認してください。

実行できない場合は？ 必要環境と未確認事項の報告を受け、実行可能な環境で同じ手順を続けてください。未実行のテストを成功と表現しないことが重要です。

公式の出典と確認日： OpenAI公式文書：プロンプト — バグを修正する · OpenAI公式文書：コードレビュー — 失敗した検査。2026年10月3日確認。例は自分のプロジェクトと現在の機能に合わせて調整してください。