TDD avec Codex : faire écrire le test à l'IA avant de passer au vert

Vous voyez Codex afficher “tous les tests sont passés” dans le terminal. En regardant de plus près, il n’a donné que la conclusion. Pas de commande, pas de liste des tests exécutés. Puis vous ouvrez le diff et vous voyez que le fichier de test a changé lui aussi : l’assertion est passée de toEqual(42) à toBeTruthy(). Le problème n’est pas de ne pas faire confiance à Codex. Le problème est de faire confiance à un “vert” sans preuve. Ce guide propose un modèle d’opération reproductible, une checklist de preuves et des garde-fous contre les faux verts, pour remplacer “faire confiance à l’IA” par “vérifier des preuves reproductibles”.

Pourquoi le test-first compte davantage avec Codex

Le test-first ne se résume pas à “écrire le test avant le code”. Avec Codex, le test devient un critère d’acceptation exécutable par la machine. Codex peut lancer des commandes, lire la sortie et modifier des fichiers, mais c’est à vous de définir à l’avance ce que “terminé” veut dire.

La documentation OpenAI Codex indique que Codex produit de meilleurs résultats quand le travail peut être vérifié. Autrement dit, si vous lui dites comment vérifier, quelle commande exécuter et quel résultat attendre, il a plus de chances de faire la bonne modification. Une tâche vague sera traitée de façon vague. Une petite tâche est plus facile à tester et à relire.

La boucle red-green-refactor se déroule en trois phases :

Ces trois étapes ne sont pas optionnelles. Si vous sautez le rouge, vous ne savez pas si le test vérifie vraiment le nouveau comportement. Si vous sautez le refactor, vous risquez de garder du code bricolé. Pour les bases de Codex, consultez le guide complet pour débuter avec Codex.

Red Phase : faire écrire à Codex un test capable d’échouer

La Red phase repose sur une contrainte simple : modifier uniquement les fichiers de test, sans écrire de code d’implémentation. Demandez d’abord à Codex de lister les cas, puis de les générer un par un, et enfin de lancer les tests pour confirmer le rouge.

Modèle de prompt

Modifie uniquement les fichiers de test. Ne modifie pas le code d'implémentation.
Écris des tests pour [nom de la fonctionnalité] couvrant :
1. [comportement minimal]
2. [cas limite]
3. [chemin d'erreur]
Une fois terminé, exécute `npm test` et colle le nom du test en échec ainsi que l'assertion.

Ce prompt doit contenir “Ne modifie pas le code d’implémentation”. Sans cette phrase, Codex peut écrire le test et glisser l’implémentation en même temps, ce qui détruit la vérification rouge.

Confirmer le rouge

Quand Codex a terminé, demandez la sortie complète du test. Le rouge doit venir de l’assertion attendue, pas d’une erreur de compilation ou d’import. Si vous voyez :

FAIL src/utils/calculator.test.ts > add > should handle negative numbers
AssertionError: expected -1 to be 42

le test vérifie le comportement des entrées négatives et échoue au bon endroit. Si vous ne voyez que TypeError: Cannot find module 'calculator', c’est une erreur de compilation, pas un échec de test utile.

Trier la liste de tests

Ne demandez pas à Codex de générer des dizaines de tests d’un coup. Commencez par le comportement minimal, les cas limites, les bugs de régression et les chemins d’erreur, puis avancez un cas à la fois. La liste peut vivre dans AGENTS.md ou dans un document séparé, afin que Codex la traite dans l’ordre.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

Pour les bases des tests unitaires, voyez Vitest, tests unitaires et TDD et le guide pratique Vitest.

Green Phase : la plus petite implémentation jusqu’au vert

Le garde-fou de la Green phase est strict : les fichiers de test sont interdits. Si le test échoue, Codex ne peut modifier que l’implémentation. Il ne doit pas adapter le test au code existant.

Modèle de prompt

Modifie uniquement les fichiers d'implémentation. Ne modifie pas les fichiers de test.
Fais la plus petite modification nécessaire pour faire passer les tests.
Une fois terminé, exécute `npm test` et colle le résumé des tests passés.

Ce prompt doit contenir “Ne modifie pas les fichiers de test”. Sinon, Codex peut modifier les assertions, supprimer des tests ou skipper des cas pour donner l’impression que tout est vert.

Vérifier le résumé et le diff

Après le passage de Codex, demandez le nombre de tests, le nombre de tests passés et la durée :

PASS src/utils/calculator.test.ts (1.2s)
  add
    ✓ should add two numbers (5ms)
    ✓ should handle negative numbers (3ms)
  2 tests passed

Puis inspectez le diff. Si un fichier de test apparaît dans la liste des modifications, refusez cette Green phase.

Garde-fous contre les faux verts

Le faux vert est le plus gros risque du TDD. Surveillez ces six signaux :

Codex ne fait pas respecter ces garde-fous pour vous. C’est à vous de les vérifier pendant la review. Les équipes plus automatisées peuvent en déplacer une partie vers la CI ou un pre-commit hook.

Refactor Phase : nettoyer uniquement après le vert

La Refactor phase ne commence qu’après le vert. Si les tests ne passent pas, ne refactorez pas. Après le refactor, les tests doivent être relancés. Ne vous contentez pas du diff.

Modèle de prompt

Tous les tests passent. Maintenant, fais uniquement du refactoring :
- Renommer les variables pour clarifier l'intention
- Supprimer le code dupliqué
- Extraire des fonctions
Ne modifie pas les fichiers de test. Relance ensuite `npm test`.

À cette étape, Codex change la structure, pas le comportement. Si le refactor introduit une nouvelle logique, ce n’est plus un refactor : c’est une nouvelle Green phase pour un nouveau comportement.

Relancer les tests pour vérifier

Après le refactor, Codex doit relancer le même ensemble de tests. S’ils restent verts, la structure n’a pas cassé le comportement existant. Si un test échoue, le refactor a changé le comportement et doit être annulé ou corrigé.

Vérifiez aussi le diff : les fichiers de test ne doivent pas apparaître dans la liste des changements. Sinon, la phase de refactor a dépassé sa limite.

Pour un exemple de refactoring, voyez Refactoring IA avec filet de sécurité de tests.

Paquet de preuves : faire livrer à Codex des éléments relisibles

Avant la fin de chaque phase, Codex doit fournir les preuves suivantes :

Checklist d’acceptation avant clôture

• Commande de test et exit code
• Résumé d’échec ou de réussite
• Liste des fichiers modifiés
• Indication sur les fichiers de test modifiés ou non
• CI status checks, s’il y en a

Modèle de réponse finale

Demandez à Codex de répondre ainsi :

### Résultat des tests
- Commande : `npm test`
- Exit code : 0
- Passés : 42 tests
- Échoués : 0
- Durée : 1.2s

### Fichiers modifiés
- src/utils/calculator.ts
- (les fichiers de test n'ont pas été modifiés)

### Risque restant
- Cas limite non couvert : entrée négative

Ce modèle rend les preuves lisibles, comparables et archivables. Si Codex répond seulement “les tests passent”, vous ne pouvez pas savoir s’il les a vraiment lancés, s’il a modifié les tests ou s’il a oublié un cas limite.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Choisir la couche de test et les commandes

Chaque couche de test vérifie un type de risque différent. Ne commencez pas automatiquement par du E2E complet, et ne vous reposez pas seulement sur les snapshots.

Tableau de décision des couches de test

Ces commandes sont des exemples à remplacer par celles de votre projet. Les stacks varient : Jest, Vitest, Pytest, Playwright, GitHub Actions. Pour plus de contexte sur les frameworks de test, voyez le guide de test Jest pour Next.js.

Les tests unitaires sont souvent la meilleure première couche de vérification pour Codex. Ils sont rapides, les échecs sont lisibles et les commandes se documentent facilement dans AGENTS.md. Les tests d’intégration et E2E conviennent mieux aux interactions entre modules et aux parcours utilisateur, mais leurs échecs sont plus difficiles à diagnostiquer. Le typecheck et le lint complètent la vérification en détectant erreurs de compilation et problèmes de style. La CI est le dernier gate d’équipe : même si tout passe en local, les CI status checks doivent passer avant le merge.

Figer les règles dans AGENTS.md et les prompts

Mettez les règles TDD dans AGENTS.md pour que Codex les lise avant chaque tâche. Vous évitez ainsi de répéter le même prompt.

Petit exemple de AGENTS.md

Placez ce bloc à la racine du projet ou dans un répertoire local :

## Test commands
- Run tests: `npm test`
- Run unit tests: `npm run test:unit`
- Run typecheck: `npm run typecheck`

## TDD rules
- Red phase: only modify test files
- Green phase: only modify implementation files
- Refactor phase: must re-run tests after cleanup

## Done when
- All tests pass
- Test files are not modified in green/refactor phase
- Diff contains only expected changes

Ce fichier indique à Codex les commandes de test du projet, ce que chaque phase peut modifier et ce qui compte comme terminé. Pour les détails sur AGENTS.md, voyez l’article de cette série consacré aux règles de projet Codex.

Un répertoire local peut porter des règles plus précises. Par exemple, src/utils/AGENTS.md peut lister les scénarios de test, les cas limites et les bugs connus de src/utils/.

Ne mettez pas de secrets, de tokens ou de configuration sensible dans AGENTS.md. Codex lit ce fichier, mais il ne filtre pas automatiquement les informations sensibles.

Du local à l’équipe : les gates CI

Des tests verts en local ne rendent pas un changement mergeable. En équipe, la CI fait office de gate : les required status checks doivent passer, et la PR review doit être terminée.

Checklist du flux

1. Tests locaux verts : Codex termine les trois phases et fournit le paquet de preuves
2. Vérification du diff dans le review pane : contrôler si des fichiers de test ont été modifiés
3. Création du PR : pousser sur une feature branch
4. Required status checks obligatoires : la CI lance les tests complets, typecheck et lint
5. Review humaine : examiner le diff, le paquet de preuves et les risques restants

Des tests verts ne signifient pas merge automatique

GitHub Docs indique que les required status checks doivent passer avant un merge vers une protected branch. Il existe toutefois un risque : un job skipped est signalé comme success et ne bloque pas le merge du PR, même s’il est required. Un PR peut donc être mergeable alors que certains checks n’ont pas réellement tourné.

Pour éviter ce faux vert, ouvrez la page GitHub Checks et confirmez que tous les required checks ont effectivement été exécutés, au lieu d’être skipped.

Utiliser le review pane

Le review pane de la Codex app permet de vérifier si le diff contient des changements de fichiers de test. Vous pouvez stage, unstage ou revert au niveau du fichier ou du hunk. Si un fichier de test a été modifié, revert ce changement et gardez seulement la modification d’implémentation.

Pour le contexte CI, voyez GitHub Actions CI et les bases des workflows GitHub Actions. Le flux de PR review est traité dans l’article Codex AI code review de cette série.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Limites de la correction automatique des échecs CI

codex exec et la Codex GitHub Action peuvent traiter des tests CI en échec, mais il faut poser des limites de sécurité.

Flux de correction automatique

D’après la documentation Codex non-interactive, un flux de correction d’échec CI ressemble à ceci :

1. Exécuter d’abord le test pour reproduire l’échec
2. Demander à Codex de faire la plus petite correction
3. Générer un patch artifact
4. Ouvrir un PR séparant le correctif du job d’origine

Avec npm test 2>&1 | codex exec "résume la cause de l'échec et propose la plus petite correction", vous pouvez transmettre la sortie du test à Codex pour obtenir un résumé et une correction minimale.

Principes de sécurité

Ne donnez pas à Codex, dans le même job, à la fois l’accès en écriture au dépôt et l’accès aux secrets. Utilisez le sandbox le moins permissif possible : read-only par défaut, workspace-write limité au répertoire de travail si nécessaire, et danger-full-access uniquement dans un environnement contrôlé.

Séparez la génération du patch artifact de la création du PR afin d’éviter d’exposer les API keys à du code non fiable.

Pas besoin de dérouler un YAML GitHub Actions complet ici. Le principe suffit : moindres privilèges, patch séparé, merge humain. L’automatisation avec codex exec est traitée dans un autre article de cette série.

Résumé

Le TDD avec Codex tient dans un modèle en trois phases : Red écrit seulement le test, Green modifie seulement l’implémentation, Refactor nettoie après les tests et les relance. Chaque phase doit produire des preuves relisibles : commande, résumé d’échec ou de réussite, liste des fichiers modifiés.

Les garde-fous contre les faux verts font la vraie différence : vérifier si des fichiers de test ont changé, si les assertions ont été affaiblies, si des tests ont été skippés, si les fixtures ont été modifiées, si seuls les tests unitaires ont été lancés alors que l’intégration comptait, ou si le workflow CI a été skipped.

En équipe, le vert local ne suffit pas. Les CI status checks, la PR review et les règles de protected branch décident si le changement peut être mergé.

La prochaine fois que vous demandez à Codex de changer du code, faites-lui écrire le test d’abord, confirmez le rouge, puis regardez les preuves. Ne vous arrêtez pas aux mots “les tests passent”.