email-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<objective> Email-dependent flows fail silently: a test that "signs up and clicks confirm" by calling the confirm endpoint directly never proves the email was generated, addressed, templated, and linkable. This skill captures the real email, waits for it without a fixed sleep, extracts the OTP or link from the body with an anchored regex, and completes the flow — so a broken template, an unsigned token, or a wrong-recipient bug actually fails the test. It also keeps deliverability (SPF/DKIM/DMARC) in a separate non-blocking suite so a DNS problem never reds your functional gate. </objective>

<objective> 依赖邮件的流程会静默失败：直接调用确认端点来「完成注册并点击确认」的测试，永远无法证明邮件已生成、正确寻址、完成模板渲染且链接可用。本技能会捕获真实邮件，无需固定等待即可等待邮件送达，使用锚定正则从正文中提取OTP或链接，并完成整个流程——这样一来，模板损坏、令牌签名错误或收件人错误等问题都会导致测试失败。此外，它还将可送达性（SPF/DKIM/DMARC）检查放在独立的非阻塞套件中，确保DNS问题不会导致功能测试关卡变红。 </objective>

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

场景	查看内容
选择捕获工具	下方的「捕获收件箱决策树」
无需等待即可轮询收件箱	`references/mailpit-playwright.md` （轮询辅助工具）
从正文中提取OTP/链接	`references/mailpit-playwright.md` （提取方法）
完整的密码重置/注册/魔法链接端到端测试	`references/mailpit-playwright.md`
预发布环境使用真实地址	`references/hosted-inboxes.md` （Mailosaur）
每个测试使用一次性收件箱	`references/hosted-inboxes.md` （MailSlurp）
仅在本地预览模板	`references/hosted-inboxes.md` （Ethereal）
标记SPF/DKIM/DMARC问题	`references/deliverability.md`
本地测试通过，但CI环境提示「邮件未送达」	下方的「CI环境中邮件不稳定」

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.

首先查看

.agents/qa-project-context.md

——如果存在，使用其中信息并跳过已解答的问题。

邮件需要接收至何处？ 本地捕获工具（Mailpit）可免费覆盖大多数功能流程。需要真实、可外部送达的地址（预发布环境、第三方ESP、真实DNS）时，需使用托管收件箱（Mailosaur/MailSlurp）。这是工具选择的核心决定因素。
测试套件的并行度如何？ 高并行度会导致「最新邮件」的定义模糊——你需要每个测试专属的唯一地址或收件箱，而非共享邮箱。
需要测试哪些流程？** 注册确认、密码重置、魔法链接登录、OTP/MFA、通知邮件——它们的流程形态一致（捕获、提取、完成），但提取内容不同（链接 vs 6位验证码）。
可送达性是否在测试范围内？ 「邮件送达收件箱/通过SPF、DKIM、DMARC校验」属于独立的非阻塞套件，不属于功能OTP测试的一部分。需提前确定。
仅本地预览，还是CI环境断言？ 开发期间预览模板使用Ethereal；CI环境中断言使用Mailpit/Mailosaur/MailSlurp。请勿混淆两者。

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

捕获真实邮件，绝不走捷径。 直接调用重置端点或硬编码令牌会跳过测试本应覆盖的集成环节——模板渲染、收件人解析、链接生成、令牌签名。通过UI提交请求，读取收件箱内容。
轮询，绝不固定等待。 邮件送达是异步的。固定的
```
waitForTimeout
```
要么时间过短（导致测试不稳定），要么时间过长（浪费时间），是邮件测试不稳定的头号原因。使用
```
expect.poll
```
/
```
.toPass
```
调用
```
/api/v1/messages
```
，或使用内置等待器（
```
messages.get
```
、
```
waitForLatestEmail
```
），这些工具已内置轮询逻辑。
每个测试对应唯一收件人。 两个并行测试都读取「最新注册邮件」时，会互相获取对方的邮件。为每个测试生成唯一地址（加号寻址或专属收件箱），并在读取时按收件人过滤。测试间清空收件箱无法解决并行问题。
使用带防护的锚定正则从正文中提取内容。 从邮件正文（
```
message.Text
```
/
```
message.HTML
```
）提取OTP/链接，而非从实时页面提取。使用
```
\d{6}
```
/
```
.match()
```
并断言匹配结果不为空——缺失的验证码必须直接导致测试失败，而非变为
```
undefined
```
。
断言内容，而非仅存在性。 「邮件已送达」是弱断言。需检查
```
subject
```
、
```
from
```
地址，以及链接指向的域名是否正确。只有断言内容，才能发现模板错误和链接错误的问题。
可送达性检查是独立的非阻塞套件。 SPF/DKIM/DMARC校验结果来自真实接收服务器的认证，而非正文文本——且这些检查不得阻塞功能流程测试。

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	Real `*.mailosaur.net` addresses	Staging/prod-like flows needing a real deliverable address; auto-waiting `messages.get(serverId, { sentTo })` ; structured links/codes; real SPF/DKIM/DMARC.
MailSlurp	Hosted (API key), paid	Real, per-inbox	Per-test throwaway inboxes via `createInbox()` + `waitForLatestEmail` ; strong parallel isolation.
Ethereal	Hosted throwaway, free	Captures, delivers nothing	Local-dev template preview only ( `createTestAccount` + `getTestMessageUrl` ). NOT for CI assertions.

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 (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.

选择能够接收邮件的最低成本工具。默认使用Mailpit进行本地+CI功能测试；仅当需要真实地址或高并行隔离时，才使用托管收件箱。

工具	托管方式/成本	地址类型	适用场景
Mailpit	自托管，单二进制文件或Docker镜像，免费/开源	任意本地SMTP收件人	默认选项。本地+GitHub Actions功能测试、预算有限场景。REST API地址为 `:8025` （ `/api/v1/messages` ）。
Mailosaur	托管（需API密钥），付费	真实 `*.mailosaur.net` 地址	需要真实可送达地址的预发布/生产类流程；内置自动等待的 `messages.get(serverId, { sentTo })` ；结构化链接/验证码；真实SPF/DKIM/DMARC校验。
MailSlurp	托管（需API密钥），付费	真实专属收件箱	通过 `createInbox()` + `waitForLatestEmail` 为每个测试生成一次性收件箱；并行隔离性强。
Ethereal	托管一次性收件箱，免费	仅捕获，不实际送达	仅用于本地开发时的模板预览（ `createTestAccount` + `getTestMessageUrl` ）。不可用于CI环境断言。

对于预算有限的注册流程场景（本地+GitHub Actions，自托管即可）：使用Mailpit——单二进制文件/Docker镜像，免费开源，REST API地址为

:8025

。如果后续需要真实可送达地址，可将套件升级为Mailosaur或MailSlurp（带真实地址的托管收件箱）。请勿「仅检查数据库而非邮件」——这只能证明数据库行已写入，无法证明邮件已发送、正确寻址且链接可用。

避免使用：MailHog——自2020年起已归档/停止维护；Mailpit是其无缝替代工具（相同端口、兼容API），已在2026年年中验证。新套件也请跳过smtp4dev/Papercut——Mailpit的API和全文搜索更适合自动化断言。

查看

references/mailpit-playwright.md

获取Docker Compose配置、轮询辅助工具和提取工具；查看

references/hosted-inboxes.md

获取Mailosaur/MailSlurp/Ethereal的相关内容。

Polling an inbox (Mailpit)

轮询收件箱（Mailpit）

Read the list 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 res = await request.get(`http://localhost:8025/api/v1/messages?query=to:${encodeURIComponent(to)}`);
  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

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. Full helper in

references/mailpit-playwright.md

使用Playwright的

request

fixture读取列表端点，找到发送至当前测试收件人的邮件，然后通过ID获取完整正文。使用带

timeout

和

intervals

的

expect.poll

——它会重试直到找到匹配项，因此快速收件箱可立即返回结果，慢收件箱也能通过测试。

// `request`是Playwright的APIRequestContext fixture；使用普通fetch()也可。
await expect.poll(async () => {
  const res = await request.get(`http://localhost:8025/api/v1/messages?query=to:${encodeURIComponent(to)}`);
  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();
// 后续：request.get(`http://localhost:8025/api/v1/message/${id}`) → { Text, HTML, Subject, From, To }

query=to:

过滤器加上按收件人

.find

匹配，是确保并行测试确定性的关键。绝不要无收件人过滤就取

messages[0]

messages.at(-1)

（全局最新邮件）。完整辅助工具见

references/mailpit-playwright.md

。

Extracting OTPs and links

提取OTP和链接

Match against the email body, anchored, with a null guard:

const otp = body.match(/\b(\d{6})\b/)?.[1];
expect(otp, 'no OTP in email body').toBeTruthy();   // throw / fail if null

const link = body.match(/https?:\/\/\S*(?:verify|confirm|reset|token=)\S*/i)?.[0];
if (!link) throw new Error('no verification link in email body');

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:

body.match(/code[:\s]+(\d{6})/i)

. Hosted services expose structured

message.html.links

message.html.codes

— prefer those when available. See

references/mailpit-playwright.md

针对邮件正文进行锚定匹配，并添加空值防护：

const otp = body.match(/\b(\d{6})\b/)?.[1];
expect(otp, '邮件正文中无OTP').toBeTruthy();   // 为空时抛出错误/测试失败

const link = body.match(/https?:\/\/\S*(?:verify|confirm|reset|token=)\S*/i)?.[0];
if (!link) throw new Error('邮件正文中无验证链接');

请勿使用索引切片（

body.split(' ')[3]

、

substring(0, 6)

、

indexOf('code')

）——模板稍有改动就会失效。请勿误将实时页面的

innerText

当作邮件正文读取。如果6位验证码可能与其他数字冲突，可锚定标签：

body.match(/code[:\s]+(\d{6})/i)

。托管服务会暴露结构化的

message.html.links

message.html.codes

——如有可用请优先使用。详见

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.com
```
, or
```
signup.${Date.now()}@...
```
. 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()
```
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

并行测试不稳定的问题：两个测试同时注册，都轮询「最新注册邮件」，导致邮件被互相获取。修复方案按优先级排序：

每个测试使用唯一地址——加号寻址/子寻址：
```
user+${randomUUID()}@example.com
```
，或
```
signup.${Date.now()}@...
```
。大多数邮件提供商都会将
```
user+anything@
```
路由至
```
user@
```
，因此一个真实邮箱可生成无限个唯一收件人。
每次读取都按收件人过滤——使用Mailosaur的
```
sentTo
```
或Mailpit的
```
query=to:
```
+
```
.find
```
匹配。绝不要直接取全局最新邮件。
每个测试使用专属收件箱——MailSlurp的
```
createInbox()
```
可为每个测试生成专属收件箱；Mailosaur可为每个测试在你的服务器域名下生成唯一地址。

测试间清空收件箱不足以解决并行问题——同时运行的两个测试仍会冲突。唯一地址+收件人过滤才是根本解决方法。详见

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.

Headers (
```
List-Unsubscribe
```
, custom
```
X-
```
headers) when your product sets them.

Links point to the right domain:

expect(links.every((l) => new URL(l.href).hostname.endsWith('staging.example.com'))).toBe(true)

Mailosaur example asserting

subject

from

, and link domain is in

references/hosted-inboxes.md

捕获邮件后，对内容进行断言：

expect(message.subject).toBe('Welcome to Example')

——捕获模板错误问题。

expect(message.from?.[0].email).toBe('hello@example.com')

——捕获发件人/回复地址配置错误问题。

当产品设置了特定头部（
```
List-Unsubscribe
```
、自定义
```
X-
```
头部）时，也需断言这些头部。

链接指向正确域名：

expect(links.every((l) => new URL(l.href).hostname.endsWith('staging.example.com'))).toBe(true)

。

Mailosaur断言

subject

、

from

和链接域名的示例见

references/hosted-inboxes.md

。

Deliverability: SPF / DKIM / DMARC

可送达性：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')

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

将此检查放在独立的非阻塞套件中，与功能流程测试分离。SPF、DKIM和DMARC的

pass

fail

+对齐结果来自真实接收服务器对发送域名的认证——它们不是正文中的字符串，因此绝不要使用

body.includes('spf')

或

body.match(/dkim/)

。此外，Mailpit不验证SPF/DKIM/DMARC对齐——它仅进行基础的SpamAssassin内容评分，因为邮件并未通过真实DNS发送。真实对齐检查需要托管的发送-接收服务（Mailosaur的可送达性报告，或一次性使用mail-tester.com）。为套件标记

@deliverability

，将其作为CI的非必填任务（

continue-on-error

），绝不要在OTP/重置流程测试中断言可送达性。详见

references/deliverability.md

。

Flaky email in CI

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:

A fixed sleep instead of polling.
```
waitForTimeout
```
/ arbitrary delay races the email. Replace with
```
expect.poll
```
/
```
.toPass
```
/ a built-in
```
waitFor
```
.
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.
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.
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.

本地测试通过，但CI环境中断言时提示「邮件未送达」。四个根本原因——需全部排查，不要仅增加等待时间：

使用固定等待而非轮询。
```
waitForTimeout
```
/任意延迟会与邮件送达竞速。替换为
```
expect.poll
```
/
```
.toPass
```
/内置
```
waitFor
```
。
超时时间过短。 CI环境中的邮件送达比本地慢。使用轮询后，增加轮询
```
timeout
```
（如30–60秒），而非增加更长的盲目等待。
无收件人过滤。 读取全局最新邮件会在并行测试时获取其他测试的邮件。按
```
sentTo
```
/
```
to:
```
过滤，并为每个测试使用唯一地址。
前一次运行的陈旧邮件。 旧的匹配邮件会在新邮件到达前满足断言。在全局设置中清空收件箱，或为每次运行生成唯一地址，确保前一次运行的邮件无法匹配。

重试整个任务、隔离测试或全局等待时间增加至30秒只是治标不治本，仍会存在竞速问题。

Anti-Patterns

反模式

1. Fixed sleep before reading the inbox

1. 读取收件箱前使用固定等待

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).

page.waitForTimeout(5000)

setTimeout

sleep()

后再读取。时间过短会导致测试不稳定，时间过长会浪费时间。使用

expect.poll

轮询

/api/v1/messages

（或内置等待器）。

2. Recommending a dead capture tool

2. 推荐已废弃的捕获工具

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

MailHog已归档（2020年）。Papercut/smtp4dev的自动化能力较弱。请使用Mailpit。

3. Checking the database instead of the email

3. 检查数据库而非邮件

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

4. 跳过邮件环节

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.

直接调用重置端点或硬编码令牌会跳过模板渲染、链接生成和令牌签名环节。请捕获邮件、提取链接、调用

page.goto

访问链接。

5. Brittle index-based extraction

5. 使用脆弱的索引提取方式

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

body.split(' ')[3]

、

substring(0, 6)

、

indexOf('code')

。请使用带空值防护的锚定

\d{6}

正则。且从邮件正文提取，而非实时页面的

innerText

。

6. Newest-message-overall with no recipient filter

6. 无收件人过滤直接取全局最新邮件

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.

messages[0]

messages.at(-1)

会在并行测试时冲突。按收件人过滤并为每个测试使用唯一地址；仅「测试间删除所有邮件」无法解决问题。

7. Asserting only that an email exists

7. 仅断言邮件存在

subject

from

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

不检查

subject

from

/链接会遗漏模板错误和链接错误问题。请断言内容。

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

8. 从正文中正则匹配SPF/DKIM/DMARC，或信任Mailpit的结果

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.

认证结果来自真实接收服务器，而非正文文本；Mailpit仅进行垃圾邮件评分。请使用Mailosaur的可送达性报告，并放在独立的非阻塞套件中。

9. IMAP libraries against a real mailbox

9. 在真实邮箱中使用IMAP库

imap-simple

node-imap

imapflow

reinvent polling and lose isolation. Use MailSlurp

createInbox

waitForLatestEmail

, one inbox per test.

imap-simple

node-imap

imapflow

会重复造轮询的轮子，且缺乏隔离性。请使用MailSlurp的

createInbox

waitForLatestEmail

，为每个测试生成一个收件箱。

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

10. 在CI环境中使用Ethereal，或为本地预览使用付费服务

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.

Ethereal不实际送达邮件——仅用于预览（

createTestAccount

getTestMessageUrl

）。请勿在CI环境中断言；同样，不要为了本地查看模板就启用付费托管服务。

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.

证明套件确实能捕获并断言内容，从最小检查项开始：

捕获已配置完成：
```
curl -s localhost:8025/api/v1/messages | jq '.total'
```
返回数字（Mailpit已启动，API可访问）。对于托管收件箱，单行
```
messages.get
```
/
```
createInbox
```
冒烟脚本可正常返回且无认证错误。
无盲目等待： 在邮件测试文件中执行
```
grep -rE 'waitForTimeout|sleep\(|setTimeout' tests/
```
无输出。
流程正常且真实： 运行注册/重置测试，并确认临时修改模板主题时测试会失败——如果仍通过，说明未断言内容。
确定性达标： 使用
```
--workers=4 --repeat-each=3
```
运行邮件测试；测试通过证明按收件人过滤可应对并行场景。
可送达性检查已隔离：
```
--grep @deliverability
```
仅选中认证套件，且该CI任务为
```
continue-on-error
```
/非必填。

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/link extraction uses an anchored regex (
```
\d{6}
```
,
```
https?://...
```
) with a null guard that fails the test on no match.
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.

根据决策树选择捕获工具，并记录在
```
.agents/qa-project-context.md
```
中（本地/CI使用Mailpit，仅在需要真实地址时使用托管收件箱）。
所有邮件测试在读取收件箱前均未使用
```
waitForTimeout
```
/
```
sleep
```
/
```
setTimeout
```
——在邮件测试文件中执行
```
grep -rE 'waitForTimeout|sleep\(|setTimeout' tests/
```
无输出；通过
```
expect.poll
```
/
```
.toPass
```
/内置等待器等待邮件送达。
每个邮件测试使用唯一收件人（加号寻址或专属收件箱），并按该收件人过滤读取内容——无过滤时绝不使用
```
messages[0]
```
/
```
messages.at(-1)
```
。
OTP/链接提取使用锚定正则（
```
\d{6}
```
、
```
https?://...
```
），并添加空值防护，无匹配时测试失败。
至少注册确认（或重置/魔法链接）流程有一个通过的端到端测试，可捕获真实邮件并通过
```
page.goto(link)
```
完成流程。
存在对
```
subject
```
、
```
from
```
和链接域名的内容断言——而非仅断言存在性。
如果可送达性（SPF/DKIM/DMARC）测试在范围内，它们位于独立的
```
@deliverability
```
套件中，且在CI环境中为非阻塞。