Rendere diagnostiche le attese nei test email con Playwright

Timeout 30000ms exceeded, la pagina è giusta, l’email arriva più tardi, il report non spiega perché. Il test non dice se l’app non ha spedito, se l’indirizzo è sbagliato, se il provider è lento o se l’assert ha guardato un messaggio vecchio¹.

Il primo draft tipico è pulito ma muto sulle cause: click su Create account, attesa su waitForMessage, verifica su “Account verified”. In quell’attesa convivono operazioni diverse: allocazione di una casella, polling, filtri per oggetto o mittente, estrazione del link. Se tutto condivide un solo timeout, il fallimento non ha confini utili per la diagnosi¹.

Serve un flusso osservabile, a stati chiari. Prima si alloca un indirizzo univoco. Poi si registra il momento in cui l’app accetta la richiesta di signup. Si osservano i messaggi effettivamente rientrati in casella. Si verifica l’allineamento tra mittente, oggetto e token di correlazione. Infine si consuma il link una volta sola. Ogni passaggio ha timestamp e un piccolo payload diagnostico. Se il run arriva a “osservato” ma non a “corrispondente”, il problema sta in filtri o contenuto generato dall’app. Se non arriva a “osservato”, si indaga consegna, mittente o provider. Questo sposta l’attenzione dal “come cerco la casella temporanea” al “quale messaggio ho davvero visto”¹.

Il cuore è una sonda con limiti chiari: polling a intervallo fisso, deadline esplicita, ritorno dell’elenco dei soggetti visti. Niente retry senza fine. La deadline diventa parte visibile del design del test. Nell’esempio, la sonda raccoglie i subject durante il polling e termina appena trova nel testo il token atteso. In caso positivo, restituisce stato matched e l’ID del messaggio. In caso di scadenza, torna timed-out insieme ai subject raccolti. Un timeout con lista vuota porta a verificare consegna e reachability. Un timeout con tre email non pertinenti porta a rivedere filtri, token o selezione del messaggio¹.

Queste prove vanno attaccate al test Playwright: indirizzo allocato, token, timestamp del trigger, risultato della sonda. Il corpo del messaggio resta fuori dai log ordinari se contiene dati utente. Di solito bastano oggetto, ID e un estratto redatto. In CI conviene salvare un JSON piccolo come artefatto, con address, triggeredAt, state, seenSubjects e un requestId dell’app. Un esempio mostrato usa address “run-1842@example.test”, triggeredAt “2026-10-31T11:20:00Z”, state “timed-out”, seenSubjects ["Welcome"], requestId “signup-7f2a”¹.

L’integrazione nel test è diretta: si alloca una mailbox per worker, si genera un token con crypto.randomUUID, si compila Email e Signup token, si clicca Create account, poi si avvia la sonda. L’output viene allegato come email-probe.json. L’assert finale rende esplicito il confine del fallimento e riporta i subject visti: questo testo entra nel messaggio dell’expect e guida l’analisi senza rieseguire alla cieca¹.

Quando più test possono colpire la stessa casella, meglio accodare i controlli invece di duplicarli. Un lease univoco per test resta la via semplice. La coda aiuta se il provider impone limiti stretti¹.

Per l’analisi dei fallimenti si parte dall’evidenza raccolta: nessun messaggio osservato porta a controllare accettazione lato sender, correttezza dell’indirizzo e reachability del provider dalla CI; messaggi osservati ma nessuna corrispondenza spinge a rivedere filtri sul subject, generazione del token o la scelta di messaggi vecchi; match trovato ma link non valido fa indagare ambiente dell’URL, scadenza e consumo del link da un retry; problemi solo in parallelo suggeriscono riuso di indirizzi, filtri condivisi o race in cleanup; flakiness richiede di confrontare latenza di consegna e deadline del polling prima di aggiungere retry¹.

Questo approccio conserva una catena minima di prove tra browser, server e inbox. E riduce le riesecuzioni, perché l’attesa lascia tracce utili al primo colpo¹.