TypeScript Email Fixtures That Fail Clearly

Email verification tests often fail in the least helpful way: a button is clicked, a test waits, and then the runner reports a timeout. The product may be fine. The test may have created the wrong inbox. An old message may have won the race. Or the polling helper simply forgot to record what it saw.

I like solving this at the fixture boundary. If a test needs to generate disposable email, the returned value should be more than a string. It should carry the inbox identity, the trigger time, and enough evidence to explain a miss. That makes a use and throw email address useful for a controlled test run without making the rest of the suite guess what happened.

Why email fixtures become confusing

A basic helper usually looks harmless:

const inbox = await createInbox(); await page.getByLabel("Email").fill(inbox.address); await page.getByRole("button", { name: "Create account" }).click(); await waitForEmail(inbox.address); 

The trouble starts when waitForEmail returns only a link or throws only TimeoutError. A retry can pass with a different message, while the original cause disappears. In a busy test suite, that is very hard to triage.

The fixture needs a small contract:

• an address that belongs to this test attempt
• a triggeredAt boundary for filtering old messages
• an explicit subject or message predicate
• a bounded polling deadline
• evidence for every rejected candidate

This is the same idea as keeping a state ledger for OAuth callback tests: record the state that lets a person reconstruct the decision later.

The typed fixture contract

TypeScript is helpful here because the diagnostic data is part of the interface, not an afterthought. I use a result type that distinguishes a successful message from an exhausted poll.

type MailCandidate = { id: string; subject: string; receivedAt: string; text: string; }; type InboxEvidence = { address: string; triggeredAt: string; observed: Array<Pick<MailCandidate, "id" | "subject" | "receivedAt">>; rejected: string[]; }; type VerificationResult = { link: string; messageId: string; evidence: InboxEvidence; }; 

The observed list stays deliberately small. Do not save an entire email body in every CI log if it might contain a token or personal data. A message id, subject, and timestamp is often enough to find the next clue. That boundary keeps the fixture safer and the output more readable.

A small TypeScript implementation

Here is the core polling shape. mail.list is an application-specific client, but the contract is portable across providers.

async function waitForVerification( mail: { list: (address: string, since: Date) => Promise<MailCandidate[]> }, address: string, timeoutMs = 30_000, ): Promise<VerificationResult> { const triggeredAt = new Date(); const deadline = Date.now() + timeoutMs; const evidence: InboxEvidence = { address, triggeredAt: triggeredAt.toISOString(), observed: [], rejected: [], }; while (Date.now() < deadline) { const messages = await mail.list(address, triggeredAt); for (const message of messages) { if (!evidence.observed.some((item) => item.id === message.id)) { evidence.observed.push({ id: message.id, subject: message.subject, receivedAt: message.receivedAt, }); } if (!message.subject.includes("Verify your email")) { evidence.rejected.push(`${message.id}: subject mismatch`); continue; } const link = message.text.match(/https?:\/\/[^\s]+/)?.[0]; if (!link) { evidence.rejected.push(`${message.id}: verification link missing`); continue; } return { link, messageId: message.id, evidence }; } await new Promise((resolve) => setTimeout(resolve, 1_000)); } throw new Error(`Verification email not found: ${JSON.stringify(evidence)}`); } 

Two details do most of the work. The poll uses the action time as its lower boundary, and duplicate messages are not added to evidence on every pass. Without the first rule, an earlier verification mail can look fresh. Without the second, a slow inbox can produce a noisy report that no one wants to read.

Using the fixture from a React test

The React test should focus on the user-visible flow and ask the fixture for the result. It should not know how inbox polling works.

test("activates an account from its verification email", async ({ page }) => { const inbox = await createInbox(); await page.getByLabel("Email").fill(inbox.address); await page.getByRole("button", { name: "Create account" }).click(); const verification = await waitForVerification(mail, inbox.address); await page.goto(verification.link); await expect(page.getByText("Your account is ready")).toBeVisible(); }); 

The test stays short, but a failure now includes the address, the timing boundary, and rejected message ids. If a teammate writes dummy e mail in a scratch note while investigating, the fixture can replace that guesswork with evidence.

Failure output and practical tradeoffs

There is a tradeoff between detailed evidence and sensitive output. Keep message bodies out of normal logs, redact links before exporting artifacts, and store only the fields needed to identify the failure. For CI, the Docker checks for email workflows in CI pattern is useful: isolate the run and make its artifacts easy to inspect.

Also, do not make the polling deadline infinite. A long wait can make a slow provider look reliable while turning every failure into a ten-minute mystery. Thirty seconds is a starting point, not a law; tune it against real delivery behavior and your test budget.

One more small improvement is to attach the evidence to the test report, not only the thrown error. That way a passed retry does not erase the first attempt’s context. Retries should give the system another chance, not delete the story.

A short checklist

Before sharing an email fixture across React tests, check that it:

1. creates or receives a unique address per attempt
2. records the action timestamp
3. filters messages by time and intent
4. reports rejected candidates without leaking full bodies
5. bounds polling and keeps retry evidence
6. returns a typed result that the test can use directly

This is a modest amount of TypeScript, but it changes the developer experience. When verification fails, the next action becomes obvious: inspect the inbox wiring, delivery timing, subject rule, or link extraction. Clear failures help teams ship cleaner features with less confusion, which is exactly what a test fixture should do.