Test email in Cypress: tracciare la causa, non solo il timeout

Trenta secondi di attesa in un test di signup Cypress: il link “Verify your email” non si trova, resta solo un timeout. Il log non dice se il messaggio è in ritardo, se la ricerca ha interrogato l’inbox sbagliata o se l’app non ha mai richiesto l’invio. Serve una traccia causale che colleghi azione utente, evento di backend, osservazioni in inbox e click finale¹.

Il fallimento che al retry passa non è una diagnosi. Possibili cause: la prima richiesta non è mai entrata in coda, l’email è arrivata prima del polling ed è stata filtrata, un messaggio precedente con lo stesso subject ha confuso la ricerca, l’API dell’inbox ha dato un errore temporaneo, il browser ha usato un account diverso. Il solo “email non trovata” rende questi scenari indistinguibili. Il retry cambia tempi, stato della casella e spesso i dati di test, quindi nasconde le differenze utili all’analisi¹.

Per rendere il test affidabile, ogni asserzione email diventa una piccola indagine. Bastano quattro timestamp e pochi identificatori: actionAt, quando Cypress invia il form; requestId, se l’app espone un ID di correlazione; pollStartedAt, quando parte la query all’inbox; messageId, il messaggio accettato. Si aggiungono indirizzo dell’inbox, ID della run, subject osservati e il motivo di ogni scarto. La timeline risulta leggibile: 14:02:11.204 actionAt signup submitted 14:02:11.260 requestId req_7f2c 14:02:11.310 pollStartedAt inbox polling started 14:02:12.018 observed msg_91, subject="Welcome" 14:02:13.477 accepted msg_92, subject="Verify your email" 14:02:14.006 clicked verification link Il provider conta poco: casella temporanea, mail server locale o generatore usa e getta funzionano se esiste un chiaro contratto di evidenza attorno alla casella¹.

In Cypress, conviene accorpare polling e raccolta prove in un unico task. Una struttura come EmailTrace memorizza inbox, actionAt, pollStartedAt, observed, rejected e l’ID accettato. Una funzione di esempio, waitForVerification, avvia il polling a partire da actionAt, registra per ogni messaggio id, subject, receivedAt, scarta i subject non coerenti con la verifica e restituisce messaggio e traccia. In assenza di corrispondenze, lancia un errore con la traccia serializzata. Lo spec cattura actionAt subito prima dell’invio e allega la traccia come artefatto del test¹.

type EmailTrace = { inbox: string; actionAt: string; pollStartedAt?: string; observed: Array<{ id: string; subject: string; receivedAt: string }>; rejected: string[]; acceptedId?: string; };

function waitForVerification(inbox: string, actionAt: Date) { const trace: EmailTrace = { inbox, actionAt: actionAt.toISOString(), observed: [], rejected: [], }; return cy.task('pollInbox', { inbox, since: actionAt.toISOString() }) .then((messages: MailMessage[]) => { trace.pollStartedAt = new Date().toISOString(); for (const message of messages) { trace.observed.push({ id: message.id, subject: message.subject, receivedAt: message.receivedAt, }); if (!message.subject.includes('Verify your email')) { trace.rejected.push(${message.id}: subject mismatch); continue; } trace.acceptedId = message.id; return { message, trace }; } throw new Error(No verification message; trace=${JSON.stringify(trace)}); }); }

La prudenza sui dati è parte del debug: niente corpi completi né token nei log CI, solo artefatti redatti. Registrare anche i candidati scartati fa risparmiare tempo: senza lista si vede “nessuna corrispondenza”, con la lista si scoprono due “Welcome” respinti per proprietà errata, indizio per isolare i fixture¹.

Dopo un fallimento, prima di toccare i timeout, si classifica la traccia in quattro categorie: Application, nessuna richiesta dopo l’azione del browser; Delivery, richiesta presente ma nessun messaggio entro la finestra concordata; Fixture, messaggio presente ma di un’altra run o destinatario; Assertion, messaggio giusto ma parsing o validazione link errati. La categoria guida la correzione minima, senza allargare a caso il polling¹.

Checklist pronta per il merge:

• creare o prendere in leasing l’inbox per la run;
• registrare actionAt prima dell’invio;
• filtrare i messaggi più nuovi di actionAt;
• loggare i candidati scartati senza contenuti sensibili;
• verificare proprietà del destinatario o della run;
• salvare una traccia redatta come artefatto del test¹.

Questa disciplina aiuta anche quando la UI non espone stati espliciti come “in coda” o “consegnata”: la traccia fornisce il contesto che la pagina non mostra e rende confrontabili passaggi e fallimenti tra suite diverse¹.