Claude Code e test API REST: come gestire i fallimenti

Il terzo fallimento prodotto durante il nostro esperimento con Claude Code è un test che verifica il comportamento dell'API quando due richieste concorrenti tentavano di creare ordini con lo stesso customerId e l'API deve garantire un limite massimo di ordini aperti per cliente.

Il caso non risolto: la race condition nei test di concorrenza

In questo caso Claude Code ha identificato correttamente che si trattava di un problema di timing nel test. Le due richieste non erano genuinamente concorrenti perché Jest le eseguiva in modo sequenziale e l'AI ha proposto di usare Promise.all per parallelizzarle. La modifica era corretta in teoria, ma nella pratica l'ambiente di test aveva un database SQLite in-memory che non gestiva transazioni concorrenti nel modo atteso. Il test continuava quindi a fallire in modo non deterministico.

Dopo due iterazioni di correzioni che non risolvevano il problema, Claude Code ha prodotto un messaggio che è stato il momento più "onesto" dell'intera sessione. Ha spiegato che il test richiedeva un database che supportasse la concorrenza reale e che SQLite in modalità WAL avrebbe potuto funzionare. Richiedeva però una modifica alla configurazione del database di test, e che la soluzione corretta era probabilmente mockare il layer di persistenza per questo specifico test invece di usare un database reale.

Ha poi proposto entrambe le opzioni, con i relativi trade-off.

Non ha risolto il problema autonomamente. Ha però prodotto un'analisi della situazione sufficientemente precisa da permettere a uno sviluppatore di prendere la decisione giusta in pochi minuti. Questo invece di passare un'ora a debuggare una race condition in un test.

Il ciclo di iterazione: interpretare i fallimenti di Claude Code come documentazione

Uno degli aspetti più interessanti dell'esperimento è stata la qualità del ciclo interpretazione-correzione che Claude Code ha eseguito autonomamente sulle prime iterazioni. Ogni volta che un test falliva, l'agente leggeva l'output completo di Jest, inclusi i diff tra valore atteso e valore ricevuto, e produceva non solo la correzione ma anche una spiegazione del perché il test stava fallendo.

Quella spiegazione era spesso più utile del fix stesso. Rivelava infatti delle discrepanze tra la specifica OpenAPI e l'implementazione reale che nessuno aveva notato.

Per esempio: un endpoint documentato come idempotente nella specifica restituiva un 201 alla prima chiamata e un 200 alla seconda. La specifica dichiarava invece 201 in entrambi i casi. L'API non era sbagliata nel senso comune del termine, il comportamento era ragionevole, ma era in contraddizione con la specifica. Il test generato dall'agente aveva reso quella contraddizione visibile e misurabile. Senza i test, quella discrepanza sarebbe rimasta invisibile finché un client non si fosse basato sul codice di stato per prendere decisioni.

È un effetto collaterale positivo che va oltre l'obiettivo originale dell'esperimento. Quello di generare test da una specifica OpenAPI con un agente produce, quasi gratuitamente, un audit della coerenza tra documentazione e implementazione.

Quando questo approccio ha senso e quando no

L'esperimento ha prodotto ventisette test funzionanti, ventisei al netto della race condition, in circa quaranta minuti di sessione agentica supervisionata. Scriverli a mano avrebbe richiesto probabilmente tre o quattro ore. Con una qualità comparabile per i casi standard e probabilmente superiore per i casi limite più complessi.

Questo rapporto è favorevole in un contesto specifico. Un'API con una specifica OpenAPI esistente, aggiornata e sufficientemente dettagliata, su cui non esiste ancora nessuna copertura di test. L'approccio agentico ha così senso perché il task è strutturalmente mappabile dalla specifica ai casi di test, e la supervisione richiesta è concentrata e prevedibile.

Il rapporto diventa meno favorevole in scenari diversi. Se la specifica è incompleta o non allineata con l'implementazione, l'agente genererà test che falliscono per ragioni che non hanno a che fare con bug nell'API ma con imprecisioni nella documentazione, distinguere i due casi richiede inoltre tempo. Se l'API ha logica di business complessa con molte dipendenze esterne da mockare, la fase di setup dei test diventa rapidamente il collo di bottiglia, e l'agente tende a fare assunzioni sul sistema di mocking che non sempre sono corrette. Se il progetto non ha già una configurazione di test minimale, nessun Jest, nessuna struttura di cartelle per i test, nessun modo di avviare l'applicazione in modalità test, l'agente passa la prima metà della sessione a costruire quella infrastruttura. Con risultati meno prevedibili.

Il valore residuo: test con Claude Code come documentazione eseguibile

C'è un ultimo aspetto dell'esperimento che vale la pena nominare, perché emerge solo guardando il risultato finale nel suo insieme. La suite di test prodotta dall'agente, quella che ha richiesto quaranta minuti di sessione supervisionata invece di quattro ore di scrittura manuale, è diventata immediatamente la documentazione più affidabile del comportamento dell'API.

Non la specifica OpenAPI, che descrive il comportamento atteso ma non può essere eseguita. Non i commenti nel codice, che non si aggiornano automaticamente quando l'implementazione cambia. I test, che falliscono quando il comportamento documentato diverge da quello effettivo, e che ogni sviluppatore può eseguire in locale in trenta secondi per capire cosa fa davvero ogni endpoint.

Questo non è un merito esclusivo dell'approccio agentico, infatti qualsiasi suite di test ben scritta produce lo stesso effetto. Ma il fatto che un agente possa costruire quella suite partendo da una specifica esistente, in un tempo sufficientemente breve da risultare praticabile anche sotto pressione di delivery, cambia il calcolo su quando investire nella copertura di test. Non è più una questione di trovare il tempo per farlo bene. È una questione di trovare quaranta minuti per supervisionare un agente che lo fa in modo accettabile.

E "accettabile" con supervisione, con review critica dell'output e con la consapevolezza dei casi limite che l'agente non gestisce autonomamente. Nella maggior parte dei progetti reali è però già molto meglio di niente.