Make CI Email Checks Explain Their Failures

说明与用途

CI 邮件验证测试经常出现模糊错误。通过记录结构化证据（runId、inbox、requestId、时间戳、消息计数、失败原因）并将其附加到 CI 日志中，失败变得自解释，能够快速定位问题是出在浏览器、API、工作者还是邮箱。

问题

Email verification tests are hard to debug because failures often hide the real issue behind generic timeouts, making it unclear whether the problem lies in the browser, API, worker, or inbox.

结果

CI email checks now produce actionable evidence that distinguishes between submission, delivery, matching, and link issues, turning flaky failures into clear engineering problems.

工作流

• Generate a unique runId and inbox address for the test
• Submit signup form and capture requestId from response
• Start polling the inbox with a deadline and interval
• On each poll, record messagesSeen and match by requestId
• If message found, record matchedMessageId and exit loop
• If timeout, set failureReason based on whether any messages were seen
• Attach the evidence JSON to CI logs and throw an informative error

证据

A test can say “verification email not found” while the real problem is a delayed worker, the wrong inbox, a stale message, or a request that never reached the mail service.

来源

Once CI can answer which inbox, which request, which messages, and how long it waited, a flaky-looking test becomes a normal engineering problem.

来源