email-testing
End-to-end testing of email-dependent flows — signup confirmation, password reset, magic-link login, OTP/MFA codes, and notification emails. Covers the capture-inbox decision tree (Mailpit, Mailosaur, MailSlurp, Ethereal), Playwright polling without fixed sleeps, regex extraction of links/OTPs from the email body, deterministic per-test addresses (plus-addressing, per-inbox), subject/from/header/link assertions, and SPF/DKIM/DMARC deliverability checks as a separate suite. Use when: "test the signup confirmation email," "password reset email test," "magic-link login test," "capture OTP from email," "Mailpit," "Mailosaur," "MailSlurp," "email arrives flaky in CI," "assert email subject/from/links." Not for: Sending transactional email from your app code, or API-only contract tests of an email provider — those are api-testing / app concerns. Email HTML rendering across clients (Outlook/Gmail dark mode) is out of scope (note it as a gap; use visual-testing or Litmus). Related: playwright-
petrkindlmann · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add petrkindlmann/qa-skills --skill email-testing技能说明
name: email-testing description: >- End-to-end testing of email-dependent flows — signup confirmation, password reset, magic-link login, OTP/MFA codes, and notification emails. Covers the capture-inbox decision tree (Mailpit, Mailosaur, MailSlurp, Ethereal), Playwright polling without fixed sleeps, regex extraction of links/OTPs from the email body, deterministic per-test addresses (plus-addressing, per-inbox), subject/from/header/link assertions, and SPF/DKIM/DMARC deliverability checks as a separate suite. Use when: "test the signup confirmation email," "password reset email test," "magic-link login test," "capture OTP from email," "Mailpit," "Mailosaur," "MailSlurp," "email arrives flaky in CI," "assert email subject/from/links." Not for: Sending transactional email from your app code, or API-only contract tests of an email provider — those are api-testing / app concerns. Email HTML rendering across clients (Outlook/Gmail dark mode) is out of scope (note it as a gap; use visual-testing or Litmus). Related: playwright-automation, api-testing, test-data-management, qa-project-context. license: MIT metadata: author: kindlmann version: "1.0" category: specialized
Quick Route
| Situation | Go to |
|---|---|
| Pick a capture tool | "Capture-inbox decision tree" below |
| Poll an inbox without a sleep | references/mailpit-playwright.md (polling helper) |
| Pull an OTP / link out of the body | references/mailpit-playwright.md (extraction) |
| Full password-reset / signup / magic-link E2E | references/mailpit-playwright.md |
| Real addresses on staging | references/hosted-inboxes.md (Mailosaur) |
| Per-test throwaway inbox | references/hosted-inboxes.md (MailSlurp) |
| Just preview a template locally | references/hosted-inboxes.md (Ethereal) |
| Flag SPF/DKIM/DMARC problems | references/deliverability.md |
| Tests pass locally, "no email yet" in CI | "Flaky email in CI" below |
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. Don't confuse the two.
Core Principles
-
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.
-
Poll, never sleep. Email arrival is asynchronous. A fixed
waitForTimeoutis either too short (flake) or too slow (wasted minutes) and is the #1 cause of flaky email tests. Useexpect.poll/.toPassagainst/api/v1/messages, or a built-in waiter (messages.get,waitForLatestEmail) that already polls for you. -
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. Clearing the inbox between tests does NOT survive parallelism.
-
Extract from the body with an anchored regex, guarded. Pull the OTP / link from the email body (
message.Text/message.HTML), not the live page. Use\d{6}/.match(and assert the match is not null — a missing code must fail loudly, not becomeundefined. -
Assert content, not existence. "An email arrived" is a weak assertion. Check the
subject, thefromaddress, and that links point to the right domain. Wrong-template and wrong-link bugs only surface if you assert on content. -
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.
| Tool | Hosting / cost | Address type | Use when |
|---|---|---|---|
| Mailpit | Self-host, single binary or docker, free / open source | Any local SMTP recipient | Default. Local + GitHub Actions functional tests, tight budget. REST API at :8025 (/api/v1/messages). |
| Mailosaur | Hosted (API key), paid | * |