Tre test rossi, e due copie del runner

Scritta agosto 2026

Dal costruire da solo una piattaforma gestionale multi-tenant — una di quattro note su ciò che il lavoro ha insegnato davvero.

Tre test su duemilasettecentoquarantatré hanno cominciato a fallire con un messaggio sullo stato dello snapshot non trovato. Nient'altro falliva. I tre non avevano niente in comune se non essere gli unici a usare snapshot.

La mossa allettante, a quel punto, è cancellare gli snapshot e rigenerarli. Avrebbe funzionato, e avrebbe funzionato per ragioni che nessuno aveva capito, fino alla install successiva.

Cosa stava succedendo davvero

Il repository è un monorepo. Il file di setup dei test sta alla radice, perché la libreria di asserzioni che carica è una dipendenza della radice — quindi il setup risolve la copia del runner della radice, qualunque sia il workspace in esecuzione.

Il package manager tiene una directory per risoluzione dei peer, non una per versione. La radice non dichiarava @types/node; ogni workspace sì. Quella singola differenza ha fatto sì che la radice risolvesse il runner verso una seconda installazione distinta della versione identica — due directory, stesso numero di versione, due istanze di modulo separate.

Stessa versione, due copie, e la libreria di asserzioni condivisa fra le due.

La libreria di asserzioni era hoistata e condivisa. Il confronto degli snapshot vi si registra come metodo, legato all'istanza di runner che si è registrata per ultima. Così il runner inizializzava il proprio client di snapshot su una copia mentre l'asserzione leggeva l'altra — e gli unici test che potessero accorgersene erano i tre che chiamano un matcher di snapshot. Tutto il resto della suite non tocca né l'una né l'altra istanza in un modo capace di distinguerle.

La correzione e la guardia

La correzione è stata dichiarare @types/node anche alla radice, dal catalogo condiviso, così che ogni importatore risolva i peer verso una sola copia. Tre righe di manifest per un guasto che si leggeva come un bug del framework di test.

La guardia conta di più. Adesso un gate fa fallire la build se una seconda installazione del runner torna a essere raggiungibile, perché la prossima persona che ci sbatte contro — me compreso, fra un anno — vedrà tre snapshot rossi e nessuna ragione al mondo per sospettare la risoluzione delle dipendenze.

Quel che ne ricavo: quando un guasto è stranamente specifico, la specificità è la prova. Tre test, una funzionalità sola, tutto il resto a posto, non è una suite instabile. È una domanda stretta su cosa facciano quei tre che nessun altro fa — e rispondere a quella domanda è molto più rapido dell'alternativa a pallettoni, cioè aggiornare cose finché il rosso non se ne va.

Da dove nascono

Nascono da un progetto solo: una piattaforma gestionale multi-tenant per studi professionali, dove clienti, commesse, ore, preventivi e fatture sono collegati dall’inizio alla fine invece di essere venduti come cinque strumenti che condividono un login. Attorno le stanno i siti pubblici, la documentazione e gli strumenti di sviluppo con cui è costruita: sette applicazioni in produzione e un solo database Postgres, in un unico repository.

È costruita e mantenuta da una persona sola, fuori dall’orario di un lavoro a tempo pieno. È un dato di contesto, non un vanto, ed è la ragione per cui queste note suonano così: da solo non puoi rimediare a un errore lavorando di più, e quindi conta la leva — cosa automatizzare, cosa rifiutarsi di dichiarare, e quali controlli restituiscono più tempo di quanto ne costino.

Il codice è privato e qui non se ne regala niente. Quello che queste pagine descrivono è un metodo: come una cosa è stata misurata, cosa la misura ha smentito, e cosa è cambiato di conseguenza. Un metodo vale più letto che tenuto per sé — ed è la parte che nessuno può copiare senza prima averla capita.