Codex でテストコードを書く｜単体テストから E2E まで

Codex がテストコードの生成に使われる理由

テストコードの作成は、実装コードと比べて「後回しにされやすい」性格を持つ作業だ。締め切りが迫ると最初に省略され、カバレッジが低いまま本番に出てしまうというパターンは多くのチームで繰り返されてきた。Codex に任せることで、この構造的な問題を変える余地が生まれる。実装コードと同じタイミングで、同じ指示からテストも生成できるからだ。

Codex がテストコードに特に有効な理由は、コードの文脈理解の深さにある。関数の引数の型・戻り値・例外処理のパス・依存する外部サービスの呼び出しパターンを読み取り、何をどの条件でアサートすべきかを推定してからテストを生成する。開発者がテストケースを一から考えるより、Codex が出した初稿を見てから「この条件が抜けている」と指摘するほうがはるかに速い。

手書きテストが抱えるコストと見落とし

テストを手書きで書くとき、最もコストがかかるのは「どのケースをカバーすべきか」の設計だ。正常系は書きやすいが、境界値・空値・タイムアウト・ネットワークエラーなどの異常系は書き漏れが起きやすい。コードレビューで気づかれないまま本番に到達し、本番でのみ再現するバグとして浮上するパターンは珍しくない。Codex はコードを静的に解析して条件分岐を列挙するため、異常系の見落としが構造的に減る。

Codex CLI 0.140.0 アルファ系での改善点

2026年6月12日時点で Codex CLI は 0.140.0-alpha.14 まで連続リリースが続いており（参照: https://github.com/openai/codex/releases）、安定版 0.140.0 への昇格準備が加速している。アルファ系ではファイル参照の精度とコンテキスト圧縮の効率が改善されており、大きなコードベースでも関係するテスト対象を正確に絞り込んでテストを生成できるようになった。安定版リリース後は、テスト生成のパイプラインをより堅牢に構築できる見込みだ。

単体テストを Codex で生成する

単体テストは、関数・メソッド単位で入力と出力の関係を検証するものだ。Codex に単体テストを生成させるときは、テスト対象のファイルとその関数の仕様をセットで渡すのが基本になる。指示が曖昧なほど生成されるテストも汎用的すぎて実用に欠けるため、要件の具体性がそのままテストの精度に直結する。

生成されたテストは必ず実行して確認する必要がある。Codex が生成したテストが最初の実行でパスするとは限らず、依存関係のモック設定が不完全だったり非同期処理のタイミングがずれたりすることがある。この「最初の実行での失敗を Codex に修正させる」フィードバックループを速く回すことが、Codex をテスト生成に組み込む上での実質的なコツだ。

Step 1: テスト対象ファイルと要件を伝える

単体テストを生成させるとき、次のような形式で指示を出すとテストの精度が上がる。

src/utils/calculate_discount.py の calculate_discount 関数に対して pytest の単体テストを書いてください。
この関数は通常価格と割引率を受け取り、割引後の価格を返します。
割引率が 0 以上 1 以下の範囲外のときは ValueError を発生させます。

テスト対象の仕様を「どんな値を受け取り、何を返し、どんな条件で例外を出すか」の3点で伝えることが重要だ。この3点が揃った指示からは、正常系・境界値・例外ケースが揃ったテストが生成されることが多い。

Step 2: 境界値・例外パスを明示して網羅性を高める

テストの初稿が生成されたあと、「割引率が 1.0 と 0.0 の境界値のテストも追加してください」や「None が渡されたときの挙動もテストしてください」と追加指示を出すと、エッジケースが補完される。Codex は既存のテストファイルを読み込んで重複しないように新しいテストケースを追加するため、既存テストを上書きする心配がない。

実際の開発では、カバレッジレポートを確認した後に「カバーされていない行 X〜Y をテストしてください」と指示するパターンも有効だ。Codex はカバレッジレポートの形式（pytest-cov の出力など）を理解できるため、未テストの行を特定してから的確にテストを追加できる。

Step 3: 既存テストとの整合性を保つ

既存のテストスイートに追加生成するときは、「tests/unit/ の既存のスタイルに合わせてください」という一行を加えるだけで、命名規則・フィクスチャの使い方・アサーションの形式が統一される。既存テストを最初に読み込んでから生成するため、一から規約を指示しなくても既存スタイルに自動で倣う（参照: OpenAI Codex 使い方ガイド）。

統合テストと E2E テスト

単体テストで関数の動作を個別に検証できたとしても、複数のモジュールが連携するときや、データベース・外部 API との境界での挙動は別途テストが必要だ。Codex は統合テストや E2E テストの生成にも対応しており、単体テストと同じ指示のスタイルで依存関係の範囲だけ広げて渡すと適切なテストを生成できる。

統合テストでは、データベースや外部サービスの呼び出しをどこまでモックするかの設計が先に決まっていると精度が上がる。「データベースは SQLite のインメモリで動かす」「外部 API は responses ライブラリでモックする」といった方針を AGENTS.md に記述しておくと、Codex が自動でその方針に従ったテストを生成する。

API の統合テスト生成パターン

REST API のエンドポイントに対して統合テストを生成させるときは、エンドポイントの仕様（メソッド・パス・リクエストボディ・レスポンスの形式）と、テストで想定する正常系・エラーレスポンスをセットで渡す。たとえば以下のような指示がベースになる。

routes/api/users.py の POST /api/users エンドポイントの統合テストを書いてください。
テストは pytest + httpx を使い、データベースは SQLite インメモリを使います。
正常系はユーザーが作成されて 201 が返ること、バリデーションエラーは email が無効なとき 422 が返ること、
重複エラーはすでに存在する email を登録しようとしたとき 409 が返ることを確認してください。

このようにシナリオを明示すると、Codex はそれぞれに対応するテスト関数を生成し、フィクスチャも含めたテストファイルとしてまとめてくれる。シナリオが多い場合は、複数回に分けて追加生成を指示するほうが一度の生成の精度が安定する。

E2E テスト ─ Playwright との組み合わせ

E2E テストでは、Playwright のテストコードを Codex に生成させるパターンが実用的だ。ログインからチェックアウトまでのユーザーフローを文章で伝えると、各ステップに対応する page.click()・page.fill()・expect(page.locator(...)) 呼び出しが含まれたテストスクリプトが生成される。

Playwright の codegen コマンドで録画したコードを渡して「このテストを読み取り、待機処理とエラーハンドリングを改善してください」という使い方も有効だ。録画コードはロケーターが冗長だったり sleep に依存した待機が含まれていたりすることが多いが、Codex に渡すとより堅牢なロケーター設計と適切な waitFor 系メソッドに置き換えられることが多い（参照: Playwright 公式ドキュメント）。

AGENTS.md でチームのテスト規約を徹底させる

複数の開発者が Codex を使ってテストを生成するとき、規約の統一が課題になる。AGENTS.md に次の項目を記述しておくと、誰が Codex に指示を出しても一貫したテストが生成される。リポジトリルートに置いた AGENTS.md はすべてのエージェント（エージェントモードで複数のサブエージェントが動くときも含む）が共通で参照するため、「テスト生成担当の worker エージェント」も「コードレビュー担当の explorer エージェント」も同一の規約に従って動く。

# テスト規約
- テストフレームワーク: pytest 8.x
- フィクスチャは conftest.py に定義する
- モックライブラリ: unittest.mock または pytest-mock
- テスト関数の命名: test_<関数名>_<シナリオ> (例: test_calculate_discount_zero_rate)
- 外部 API 呼び出しは必ずモックする。実際の HTTP リクエストをテスト内で送信しない
- データベースはテストごとにロールバックする
- 各テスト関数には最低3つのアサーションを含める

この AGENTS.md を起点にすることで、テストの追加生成・リファクタリング・カバレッジ拡張をそれぞれ別のタイミングで Codex に依頼しても、スタイルが崩れない。AGENTS.md の内容は、チームのテスト規約が変わるたびに更新することで、継続的に Codex の出力を正しい方向へ誘導できる（参照: Codex AGENTS.md ガイド）。

テストの品質を高めるプロンプト設計

Codex に渡す指示の質がテストの品質に直結する。いくつかのテクニックを押さえるだけで、生成されるテストのアサーション密度と網羅性が大きく変わる。

アサーション密度を上げる指定

生成されたテストがアサーションを一つしか持たない場合、「各テスト関数に最低3つのアサーションを含めてください」と追加指示を出す。戻り値の型・具体的な値・副作用の有無を3点同時にアサートすることで、テストが「通ったかどうか」だけでなく「期待どおりの状態になっているか」まで確認できる構成になる。

また「失敗メッセージを含めてください」と指示すると、アサーションが失敗したときに原因を特定しやすいカスタムメッセージが付与される。大規模なテストスイートで CI が失敗したとき、どのアサーションが何の理由で失敗したかがすぐにわかると、デバッグ時間が短縮される。

モックと依存注入の指定

テストが外部依存を持つとき、「〇〇クラスはモックし、実際のネットワーク呼び出しをしないようにしてください」と明示する必要がある。指示が曖昧だと、実際の外部サービスに接続するテストが生成される場合がある。特に Stripe・SendGrid・S3 などの外部サービスへの依存がある場合は、モック対象を明示してから生成を始めると、テストの独立性が担保される。

Codex は既存の @pytest.fixture デコレータが付いたフィクスチャを認識して活用するため、プロジェクトにすでにモック用フィクスチャが整備されている場合は、そのファイルを参照させてから生成するとフィクスチャの重複が防げる（参照: pytest フィクスチャドキュメント）。

よくある問題と対処

生成されたテストが最初の実行で失敗する: インポートエラーや依存関係の不足が原因のことが多い。エラーメッセージをそのまま Codex に渡すと、インポートの修正やフィクスチャの補完を行ってくれる。「このエラーが出ています。修正してください」という一言に加えてスタックトレース全文を貼るだけでよい。

テストの独立性が保たれていない: テスト間でグローバル状態が共有されていると、実行順序によって結果が変わる。「各テスト関数の前後に状態をリセットする処理を追加してください」と指示すると、setUp/tearDown または pytest の yield フィクスチャを使ったリセット処理が追加される。

E2E テストが特定の環境でのみ失敗する: ロケーターが DOM の特定の実装に依存している場合は、Playwright の data-testid 属性を使うように指示するとポータビリティが上がる。「ロケーターは data-testid を優先して使ってください」という一行を AGENTS.md に加えるだけで、以後 Codex が生成するすべての E2E テストがこの規約に従う。

モックが本番の動作と乖離する: モックの設定が不完全で本番と異なる挙動になるリスクは常にある。「モックのレスポンスは実際の API ドキュメント（URL を貼付）に基づいて設定してください」と指示すると、ドキュメントに記載されているフィールドと型をモックに反映したテストが生成され、本番との乖離が起きにくくなる。

2026年6月時点で Codex CLI のアルファ系は急ピッチで進化しており、テストコード生成の品質と安定性はまだ改善が続いている。安定版 0.140.0 がリリースされた後は、テスト生成の再現性がさらに高まる見込みだ。現在からテスト生成のプロンプト設計と AGENTS.md を育てておくことで、安定版移行後の開発サイクルを即座に最適化できる体制が整う。