A Tiny Email Fixture Factory for CI

Description and use

Email fixtures in CI provide unique, traceable addresses, bounded wait for messages, guaranteed cleanup, and redacted artifacts, making tests deterministic and debugging easier.

Problem

Tests that rely on email verification become hard to reproduce and interfere with each other when each test creates its own disposable email address, leading to flaky CI runs.

Outcome

Tests become deterministic, failures are categorized (message missing, link invalid, address rejected), and debugging focuses on contract steps rather than generic email receipt.

Workflow

• Create a unique fixture key using runId and testId
• Call createMailFixture to obtain address, key, waitFor, and dispose functions
• Use waitFor(subject, timeoutMs) to poll for the expected email within a deadline
• Extract the verification link from the returned message object
• Perform the test action (e.g., click link, verify account state)
• Wrap test logic in try/finally to ensure dispose() is called
• Record timeout evidence as a test artifact, redacting sensitive data
• If cleanup fails, report separately from the test assertion

Evidence

Every test gets a unique address or inbox key.

Source

The factory can expose only three operations: create, wait, and dispose.

Source

Wrap the fixture in a try/finally block, and make disposal idempotent.

Source