Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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 review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add petrkindlmann/qa-skills --skill email-testing

About this skill


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

SituationGo to
Pick a capture tool"Capture-inbox decision tree" below
Poll an inbox without a sleepreferences/mailpit-playwright.md (polling helper)
Pull an OTP / link out of the bodyreferences/mailpit-playwright.md (extraction)
Full password-reset / signup / magic-link E2Ereferences/mailpit-playwright.md
Real addresses on stagingreferences/hosted-inboxes.md (Mailosaur)
Per-test throwaway inboxreferences/hosted-inboxes.md (MailSlurp)
Just preview a template locallyreferences/hosted-inboxes.md (Ethereal)
Flag SPF/DKIM/DMARC problemsreferences/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

  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/messages, or a built-in waiter (messages.get, waitForLatestEmail) that already polls for you.

  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. Clearing the inbox between tests does NOT survive parallelism.

  4. 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 become undefined.

  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.

ToolHosting / costAddress typeUse when
MailpitSelf-host, single binary or docker, free / open sourceAny local SMTP recipientDefault. Local + GitHub Actions functional tests, tight budget. REST API at :8025 (/api/v1/messages).
MailosaurHosted (API key), paid*
Read the complete source ↗