email-testing

Quick Route

Discovery Questions

Check .agents/qa-project-context.md first — if it exists, use it and skip anything answered there.

• Where does the email need to be received? Local capture (Mailpit) covers most functional flows for free. A real, externally-deliverable address (staging, a third- party ESP, real DNS) means a hosted inbox (Mailosaur / MailSlurp). This is the single biggest tool-selection driver.
• How parallel is the suite? High parallelism makes "the latest email" ambiguous — you need per-test unique addresses or per-test inboxes, not a shared mailbox.
• Which flows? Signup confirmation, password reset, magic-link login, OTP/MFA, notification emails — they share one shape (capture, extract, complete) but differ in what you extract (link vs 6-digit code).
• Is deliverability in scope? "Lands in inbox / passes SPF, DKIM, DMARC" is a separate non-blocking suite, not part of the functional OTP test. Decide upfront.
• Local-only preview, or CI assertions? Previewing a template during dev is Ethereal; asserting in CI is Mailpit/Mailosaur/MailSlurp/ShazaMail. Don't confuse the two.

Core Principles

1. Capture the real email; never shortcut past it. Calling the reset endpoint directly or hardcoding a token skips the exact integration the test exists to cover — templating, recipient resolution, link generation, token signing. Submit on the UI, read the inbox.

2. Poll, never sleep. Email arrival is asynchronous. A fixed waitForTimeout is either too short (flake) or too slow (wasted minutes) and is the #1 cause of flaky email tests. Use expect.poll / .toPass against /api/v1/search?query=..., or a built-in waiter (messages.get, waitForLatestEmail) that already polls for you. Bound each HTTP call at the client, including response-body parsing; a provider wait budget alone does not protect against a stalled connection.

3. One unique recipient per test. Two parallel tests both reading "the latest signup email" grab each other's mail. Make every test's address unique (plus-addressing or a per-test inbox) and filter by recipient when reading. ShazaMail can instead isolate each test with a dedicated test inbox ID and received_after matcher. Clearing the inbox between tests does NOT survive parallelism.

4. Extract against the real template and reject ambiguity. Pull the OTP from the email body with a label-specific regex and require one distinct code. Parse HTML links with a DOM parser, then require the exact approved origin and the flow's path and token. A missing or ambiguous match fails; never navigate to a guessed URL.

5. Assert content, not existence. "An email arrived" is a weak assertion. Check the subject, the from address, and that links point to the right domain. Wrong-template and wrong-link bugs only surface if you assert on content.

6. Deliverability is a separate, non-blocking suite. SPF/DKIM/DMARC come from a real receiving server's authentication, never from the body text — and they must not block the functional flow tests.

Capture-inbox decision tree

Pick the cheapest tool that can actually receive your mail. Default to Mailpit for local + CI functional tests; reach for a hosted inbox only when you need real addresses or high-parallelism isolation.

For the budget signup-flow case (local + GitHub Actions, self-host fine): use Mailpit — a single binary / docker image with a free, open-source REST API at :8025. If you later need a real deliverable address, graduate that suite to Mailosaur or MailSlurp or ShazaMail (hosted inboxes with real addresses). Do not "just check the database instead of the email" — that proves the row was written, not that the email was sent, addressed, and linkable.

Avoid: MailHog — archived/unmaintained since 2020; Mailpit is its drop-in replacement (same ports, compatible API), verified mid-2026. Also skip smtp4dev / Papercut for new suites — Mailpit's API and full-text search are better for automated assertions.

See references/mailpit-playwright.md for the docker-compose, the polling helper, and the extraction utilities; references/hosted-inboxes.md for Mailosaur / MailSlurp / Ethereal.

Polling an inbox (Mailpit)

Read the search endpoint with Playwright's request fixture, find the message addressed to this test's recipient, then fetch the full body by ID. Use expect.poll with a timeout and intervals — it retries until a match appears, so fast inboxes resolve instantly and slow ones still pass.

// `request` is the Playwright APIRequestContext fixture; plain fetch() works too.
await expect.poll(async () => {
  const query = new URLSearchParams({ query: `to:${to}` });
  const res = await request.get(`http://localhost:8025/api/v1/search?${query}`);
  expect(res.ok(), `Mailpit search HTTP ${res.status()}`).toBe(true);
  const { messages } = await res.json();
  return messages.find((m) => m.To.some((t) => t.Address === to))?.ID ?? null;
}, { timeout: 30_000, intervals: [500, 1_000, 2_000] }).not.toBeNull();
// then: request.get(`http://localhost:8025/api/v1/message/${id}`) → { Text, HTML, Subject, From, To }

The search endpoint's query=to: filter plus the .find on the recipient is what makes parallel tests deterministic. Never take messages[0] / messages.at(-1) (newest overall) with no recipient filter. When asking for a second email to the same account, exclude IDs already seen; an old matching message must not satisfy a new request. Full helper in references/mailpit-playwright.md, including HTTP/schema failures and detail checks.

Extracting OTPs and links

Use the guarded helpers in references/mailpit-playwright.md against the email body:

const otp = extractOtp(message.Text, /\bcode:\s*(\d{6})\b/gi);
const resetUrl = await extractLink(page, message, new URL(baseURL).origin,
  url => url.pathname === '/reset' && Boolean(url.searchParams.get('token')));
await page.goto(resetUrl);

Do NOT slice by index (body.split(' ')[3], substring(0, 6), indexOf('code')) — those break the moment the template changes a word. Do NOT read innerText of the live page when you mean the email body. If a 6-digit code could collide with other numbers, anchor on the label and reject multiple distinct matches. A broad \S* URL regex can consume closing HTML tags and preserve & in query parameters. Hosted services expose structured message.html.links / message.html.codes — prefer those when available. See references/mailpit-playwright.md.

Deterministic addresses (parallel isolation)

The parallel-flake bug: two tests sign up at once and both poll for "the latest signup email," so they swap messages. Fixes, in order of preference:

• Per-test unique address — plus-addressing / sub-addressing: user+${randomUUID()}@example.test, created anew on every retry. Timestamps alone can collide across workers. Most providers route user+anything@ to user@, so one real mailbox yields infinite unique recipients.
• Filter every read by recipient — sentTo (Mailosaur) or a query=to: + .find match (Mailpit). Never take the newest message overall.
• Per-test dedicated inbox — MailSlurp createInbox() or ShazaMail POST /api/v1/test-inboxes gives each test its own inbox; Mailosaur gives each test a unique address on your server domain.

Clearing the inbox between tests is not sufficient under parallelism — two tests running at the same instant still collide. Unique address + recipient filter is the real fix. See references/hosted-inboxes.md.

Asserting subject / from / headers / links

After capture, assert on content:

• expect(message.subject).toBe('Welcome to Example') — catches wrong-template bugs.
• expect(message.from?.[0].email).toBe('hello@example.com') — catches misconfigured sender / reply-to. Pin the sender only when the product or its contract names one; if it names none, record the sender as unpinned rather than asserting a guessed address.
• Headers (List-Unsubscribe, custom X- headers) when your product sets them.
• Links point to the right domain: expect(new URL(link.href).origin).toBe('https://staging.example.com') before navigation. A hostname suffix check also accepts evil-staging.example.com; require an exact origin or a deliberately approved subdomain boundary.

Mailosaur example asserting subject, from, and link domain is in references/hosted-inboxes.md.

Deliverability: SPF / DKIM / DMARC

Keep this in its own non-blocking suite, separate from functional flow tests. SPF, DKIM, and DMARC pass/fail + alignment come from a real receiving server authenticating your sending domain — they are not strings in the body, so never body.includes('spf') or body.match(/dkim/). And Mailpit does not validate SPF/DKIM/DMARC alignment — it only does basic SpamAssassin content scoring, because nothing was sent over real DNS. Real alignment needs a hosted send-and-receive (Mailosaur deliverability report, or mail-tester.com for a one-off). Tag the suite @deliverability, run it as a non-required CI job (continue-on-error), and never assert deliverability inside the OTP / reset flow test. See references/deliverability.md.

Flaky email in CI

Tests pass locally but the email "hasn't arrived yet" when CI asserts. The four root causes — diagnose all of them, do not just bump the sleep:

1. A fixed sleep instead of polling. waitForTimeout / arbitrary delay races the email. Replace with expect.poll / .toPass / a built-in waitFor.
2. Timeout too short. CI mail delivery is slower than local. Once polling, increase the poll timeout (e.g. 30–60s) rather than adding a longer blind sleep.
3. No recipient filter. Reading the newest message overall picks up another test's mail under parallelism. Filter by sentTo / to: and use a unique address per test.
4. Stale messages from a previous run. An old matching email satisfies the assertion before the new one arrives. Clear the inbox in global setup and/or make the address unique per run so prior-run mail can't match.

Retrying the whole job, quarantining the test, or raising a global sleep to 30s treats the symptom and leaves the race in place.

Anti-Patterns

1. Fixed sleep before reading the inbox

page.waitForTimeout(5000) / setTimeout / sleep() then read. Too short flakes, too long wastes minutes. Poll with expect.poll against /api/v1/messages (or a built-in waiter).

2. Recommending a dead capture tool

MailHog is archived (2020). Papercut / smtp4dev are weaker for automation. Use Mailpit.

3. Checking the database instead of the email

A DB row proves the write happened, not that the email was sent, addressed, and linkable. Read the actual captured message.

4. Shortcutting past the email

Calling the reset endpoint directly or hardcoding a token skips templating, link generation, and token signing. Capture the email, extract the link, page.goto it.

5. Brittle index-based extraction

body.split(' ')[3], substring(0, 6), indexOf('code'). Use an anchored \d{6} regex with a null guard. And extract from the email body, not the live page's innerText.

6. Newest-message-overall with no recipient filter

messages[0] / messages.at(-1) collide under parallelism. Filter by recipient and use a unique per-test address; "delete all messages between tests" alone does not fix it.

7. Asserting only that an email exists

No subject / from / link checks misses wrong-template and wrong-link bugs. Assert content.

8. Regexing SPF/DKIM/DMARC out of the body, or trusting Mailpit for it

Auth results come from a real receiving server, not body text; Mailpit only does spam scoring. Use Mailosaur's deliverability report, in a separate non-blocking suite.

9. IMAP libraries against a real mailbox

imap-simple / node-imap / imapflow reinvent polling and lose isolation. Use MailSlurp createInbox + waitForLatestEmail, one inbox per test.

10. Ethereal in CI, or a paid service for a local preview

Ethereal delivers nothing — it's preview-only (createTestAccount + getTestMessageUrl). Don't assert on it in CI; equally, don't spin up a paid hosted service just to eyeball a template locally.

Verification

Prove the suite actually captures and asserts, smallest check first:

• Capture is wired: curl -s localhost:8025/api/v1/messages | jq '.total' returns a number (Mailpit up, API reachable). For a hosted inbox, a one-line messages.get / createInbox smoke script returns without auth error.
• No blind sleeps: grep -rE 'waitForTimeout|sleep\(|setTimeout' tests/ over the email specs prints nothing.
• The flow is green and real: run the signup/reset spec and confirm it fails when you temporarily break the template subject — if it still passes, you are not asserting content.
• Determinism holds: run the email specs with --workers=4 --repeat-each=3; a passing run proves the per-recipient filter survives parallelism.
• Deliverability is isolated: --grep @deliverability selects only the auth suite, and that CI job is continue-on-error / non-required.

Done When

• The capture tool is chosen against the decision tree and recorded in .agents/qa-project-context.md (Mailpit for local/CI, a hosted inbox only where a real address is needed).
• No email test contains waitForTimeout / sleep / setTimeout before reading the inbox — grep -rE 'waitForTimeout|sleep\(|setTimeout' tests/ over the email specs is clean; arrival is awaited via expect.poll / .toPass / a built-in waiter.
• Each email test uses a unique recipient (plus-address or per-test inbox) and filters reads by that recipient — no messages[0] / messages.at(-1) without a filter.
• OTP extraction uses a template label and rejects distinct competing codes; link extraction parses HTML anchors and requires one match for the exact approved origin, path, and token. Missing or ambiguous results fail before navigation.
• At least the signup-confirmation (or reset / magic-link) flow has a green E2E test that captures the real email and completes the flow through page.goto(link).
• Content assertions on subject, from, and link domain exist — not just existence.
• Deliverability (SPF/DKIM/DMARC) tests, if in scope, live in a separate @deliverability suite that is non-blocking in CI.

Related Skills

• playwright-automation — the browser-driving half of every email flow: forms, navigation, fixtures, and the poll helpers. This skill adds the inbox side.
• api-testing — go there to test the email provider's API directly or to test that your app sends mail; this skill is about receiving and asserting in an E2E flow.
• test-data-management — generating unique per-test addresses, factories, and seeded users that feed the recipient strategy here.
• qa-project-context — records the chosen capture tool, SMTP target, and credentials so every email test shares one configuration.

Reference Files (in references/)

• mailpit-playwright.md — docker-compose, the expect.poll Mailpit helper, OTP/link extraction utilities, and full password-reset / signup / OTP / magic-link E2E tests.
• hosted-inboxes.md — Mailosaur (messages.get auto-wait, real addresses, structured links/codes), MailSlurp (createInbox + waitForLatestEmail, per-test inbox), ShazaMail (per-test inbox with client deadlines for create/wait), and Ethereal (local preview via createTestAccount + getTestMessageUrl).
• deliverability.md — SPF/DKIM/DMARC as a separate non-blocking suite, why body-regex and Mailpit don't validate auth, and the Mailosaur deliverability assertion.