TDD con Codex: fai scrivere prima il test all'IA e poi porta tutto al verde

Nel terminale vedi Codex scrivere “tutti i test sono passati”. Ma guardando meglio c’è solo la conclusione. Non c’è il comando, non c’è l’elenco dei test eseguiti. Apri il diff e scopri che è cambiato anche il file di test: l’assertion passa da toEqual(42) a toBeTruthy(). Il punto non è diffidare di Codex. Il punto è non fidarsi di un “verde” senza prove. Questa guida offre un modello operativo riutilizzabile, una checklist di verifica e guardrail contro i falsi verdi, così “fidarsi dell’IA” diventa “controllare prove riproducibili”.

Perché test-first conta di più con Codex

Test-first non significa solo “scrivere test prima del codice”. Con Codex, i test diventano criteri di accettazione eseguibili dalla macchina. Codex può eseguire comandi, leggere output e modificare file, ma il criterio di “finito” va definito prima.

La documentazione ufficiale di OpenAI Codex indica che Codex lavora meglio quando può verificare il risultato. Quindi, se gli dici come verificare, quale comando eseguire e quale risultato aspettarsi, è più probabile che faccia la modifica corretta. I task vaghi vengono trattati in modo vago. I task piccoli sono più facili da testare e da rivedere.

Il ciclo red-green-refactor ha tre fasi:

Questi tre passaggi non vanno saltati. Se salti il red, non sai se il test verifica davvero il nuovo comportamento. Se salti il refactor, è facile lasciare codice rattoppato. Per le basi di Codex, parti dalla guida completa per iniziare con Codex.

Red Phase: far scrivere a Codex un test che possa fallire

La Red phase è soprattutto una questione di vincoli: modificare solo file di test e non scrivere codice di implementazione. Fai prima elencare a Codex i casi di test, poi generali uno per volta e infine esegui i test per confermare il rosso.

Template di prompt

Modifica solo i file di test. Non modificare il codice di implementazione.
Scrivi test per [nome funzionalità] coprendo:
1. [comportamento minimo]
2. [caso limite]
3. [percorso di errore]
Alla fine esegui `npm test` e incolla il nome del test fallito e l'assertion.

Questo prompt deve contenere “Non modificare il codice di implementazione”. Senza quella frase, Codex può scrivere il test e implementare il comportamento nello stesso passaggio, distruggendo la verifica rossa.

Confermare il rosso

Quando Codex finisce, chiedi l’output completo dei test. Il rosso deve fallire sull’assertion attesa, non su un errore di compilazione o di import. Se vedi questo:

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

il test sta verificando il comportamento con input negativi e fallisce nel punto previsto. Se vedi solo TypeError: Cannot find module 'calculator', quello è un errore di compilazione, non un fallimento utile del test.

Ordinare la lista dei test

Non chiedere a Codex di generare decine di test in una volta sola. Parti da comportamento minimo, casi limite, bug di regressione e percorsi di errore. Avanza un caso alla volta. La lista può stare in AGENTS.md o in un documento separato, così Codex la segue in ordine.

Railway - Piattaforma di deploy moderna, senza operazioni complesse, online in pochi minuti

Inizia ora →Pubbl.

Per le basi dei test unitari, vedi Vitest, test unitari e TDD e la guida pratica a Vitest.

Green Phase: minima implementazione fino al verde

Il guardrail rigido della Green phase è semplice: i file di test non si toccano. Se un test fallisce, Codex può modificare solo l’implementazione. Non deve adattare il test al codice.

Template di prompt

Modifica solo i file di implementazione. Non modificare i file di test.
Fai la modifica minima necessaria per far passare i test.
Alla fine esegui `npm test` e incolla il riepilogo dei test passati.

Questo prompt deve contenere “Non modificare i file di test”. Senza quella frase, Codex può cambiare assertion, eliminare test o saltare casi per far sembrare verde l’esecuzione.

Controllare riepilogo e diff

Dopo il lavoro di Codex, chiedi numero di test, test passati e durata:

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

Poi controlla il diff. Se un file di test compare nella lista dei cambiamenti, rifiuta quella Green phase.

Guardrail contro i falsi verdi

Il falso verde è il rischio principale nel TDD. Fai attenzione a questi sei segnali:

Codex non applica questi guardrail al posto tuo. Devi verificarli durante la review. I team più automatizzati possono spostarne una parte in CI o in un pre-commit hook.

Refactor Phase: ripulire solo dopo il verde

La Refactor phase inizia solo dopo il verde. Se i test non passano, non fare refactoring. Dopo il refactor i test vanno eseguiti di nuovo; non basta guardare il diff.

Template di prompt

Tutti i test passano. Ora fai solo refactoring:
- Rinomina variabili per rendere più chiara l'intenzione
- Rimuovi codice duplicato
- Estrai funzioni
Non modificare i file di test. Alla fine riesegui `npm test`.

In questa fase Codex cambia struttura, non comportamento. Se il refactor introduce nuova logica, non è più refactor: è una nuova Green phase per un nuovo comportamento.

Rieseguire i test per verificare

Dopo il refactor, Codex deve eseguire di nuovo lo stesso set di test. Se restano verdi, il refactor non ha rotto il comportamento esistente. Se un test fallisce, il refactor ha cambiato comportamento e va revertito o corretto.

Controlla anche il diff: i file di test non dovrebbero comparire nella lista dei cambiamenti. Se compaiono, il refactor ha superato il limite.

Per un esempio di refactoring, vedi Refactoring con IA e rete di sicurezza dei test.

Pacchetto di prove: far consegnare a Codex evidenza verificabile

Prima di chiudere ogni fase, Codex deve consegnare queste prove:

Checklist di accettazione prima della chiusura

• Comando di test ed exit code
• Riepilogo di fallimento o successo
• Lista dei file modificati
• Se i file di test sono stati modificati
• CI status checks, se presenti

Template di risposta finale

Fai rispondere Codex in questo formato:

### Risultato dei test
- Comando: `npm test`
- Exit code: 0
- Passati: 42 test
- Falliti: 0
- Durata: 1.2s

### File modificati
- src/utils/calculator.ts
- (i file di test non sono stati modificati)

### Rischio residuo
- Caso limite non coperto: input negativo

Questo formato rende le prove leggibili, confrontabili e facili da archiviare. Se Codex risponde solo “i test passano”, non puoi sapere se li ha davvero eseguiti, se ha modificato file di test o se ha saltato un caso limite.

Vultr - Cloud server NVMe ad alte prestazioni, 32 location globali, deploy Docker con un clic

Vedi prezzi →Pubbl.

Scegliere il livello di test e i comandi

Ogni livello di test verifica un rischio diverso. Non partire subito con E2E completo e non affidarti solo agli snapshot test.

Tabella decisionale dei livelli di test

Questi comandi sono esempi: sostituiscili con i comandi reali del tuo progetto. Ogni stack può usare Jest, Vitest, Pytest, Playwright o GitHub Actions. Per più contesto, leggi la guida ai test Jest con Next.js.

I test unitari sono spesso il primo livello di verifica per Codex. Sono veloci, producono errori chiari e sono facili da documentare in AGENTS.md. I test di integrazione ed E2E sono più adatti a interazioni tra moduli e flussi utente, ma i fallimenti sono più difficili da diagnosticare. Typecheck e lint completano la verifica intercettando errori di compilazione e problemi di stile. La CI è l’ultimo gate del team: anche se tutto passa in locale, i CI status checks devono passare prima del merge.

Fissare le regole in AGENTS.md e nei prompt

Scrivi le regole TDD in AGENTS.md, così Codex le legge prima di ogni attività. Eviti di ripetere lo stesso prompt ogni volta.

Piccolo esempio di AGENTS.md

Metti qualcosa del genere nella root del progetto o in una directory locale:

## 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

Questo file dice a Codex quali comandi di test esistono, cosa può cambiare ogni fase e cosa conta come completato. Per altri dettagli su AGENTS.md, vedi l’articolo sulle regole di progetto Codex in questa serie.

Le directory locali possono avere regole più specifiche. Per esempio, src/utils/AGENTS.md può elencare scenari di test, casi limite e bug noti per src/utils/.

Non mettere secret, token o configurazioni sensibili in AGENTS.md. Codex legge questo file, ma non filtra automaticamente le informazioni sensibili.

Dal locale al team: gate CI

Test verdi in locale non significano che la modifica sia mergeabile. In un team c’è un gate CI: i required status checks devono passare e la PR review deve essere completa.

Checklist del flusso

1. Test locali verdi: Codex completa le tre fasi e consegna il pacchetto di prove
2. Controllo del diff nel review pane: verificare se sono stati modificati file di test
3. Creare il PR: push su una feature branch
4. Required status checks obbligatori: CI esegue test completi, typecheck e lint
5. Review umana: controllare diff, pacchetto di prove e rischi residui

Test verdi non significano merge automatico

GitHub Docs spiega che i required status checks devono passare prima di fare merge in una protected branch. C’è però un rischio: un job skipped viene segnalato come success e non blocca il merge del PR, anche se è un required check. Quindi un PR può sembrare mergeabile anche se alcuni check non sono davvero stati eseguiti.

Per evitare falsi verdi da workflow saltati, apri la pagina GitHub Checks e conferma che tutti i required checks siano stati eseguiti davvero, invece di risultare skipped.

Usare il review pane

Il review pane della Codex app permette di vedere se il diff include modifiche ai file di test. Puoi fare stage, unstage o revert per file o hunk. Se un file di test è stato cambiato, fai revert di quella modifica e mantieni solo la modifica di implementazione.

Per più contesto sulla CI, leggi GitHub Actions CI e le basi dei workflow GitHub Actions. Il flusso di PR review è trattato nell’articolo su code review con Codex AI di questa serie.

🔥 Non sprecare mesi su prodotti senza domanda! Valida i punti di forza del tuo SaaS con Adsterra e un piccolo budget →

Testa ora →Pubbl.

Limiti per correggere automaticamente i fallimenti CI

codex exec e Codex GitHub Action possono aiutare con test CI falliti, ma servono confini di sicurezza.

Flusso di correzione automatica

Secondo la documentazione Codex non-interactive, un flusso per correggere un fallimento CI è questo:

1. Eseguire prima il test per riprodurre il fallimento
2. Far fare a Codex la minima correzione
3. Generare un patch artifact
4. Aprire un PR separato per il fix

Con npm test 2>&1 | codex exec "riassumi la causa del fallimento e suggerisci la minima correzione" puoi passare l’output del test a Codex, così riassume il problema e propone una riparazione minima.

Principi di sicurezza

Non dare a Codex nello stesso job sia accesso in scrittura al repository sia accesso ai secret. Usa il sandbox con il privilegio minimo: read-only di default, workspace-write solo per la directory di lavoro, danger-full-access solo in ambienti controllati.

Separa la generazione del patch artifact dalla creazione del PR, così le API key non vengono esposte a codice non affidabile.

Non serve espandere qui un intero YAML di GitHub Actions. Il principio è semplice: minimo privilegio, patch separato, merge umano. L’automazione con codex exec è trattata in un altro articolo della serie.

Riepilogo

Il test-driven development con Codex si riduce a un modello in tre fasi: Red scrive solo test, Green modifica solo l’implementazione, Refactor ripulisce dopo aver rieseguito i test. Ogni fase deve produrre prove verificabili: comando, riepilogo di fallimento o successo e lista dei file modificati.

I guardrail contro i falsi verdi sono la parte decisiva: controllare se sono stati modificati file di test, se le assertion sono state indebolite, se i test sono stati saltati, se le fixture sono cambiate, se sono stati eseguiti solo unit test quando serviva integrazione, o se il workflow CI è stato skipped.

In team, il verde locale non basta. CI status checks, PR review e regole di protected branch decidono se la modifica può essere mergiata.

La prossima volta che chiedi a Codex di cambiare codice, fagli scrivere prima il test, conferma il rosso e poi guarda le prove. Non fermarti alle parole “i test passano”.