開発者のためのメールテスト完全ガイド

自動テストでカバーするのが最も難しいもののひとつがメールです。認証リンク、OTP、パスワードリセットメールといった肝心のステップが、アプリの外へ出て、テストからは見えない受信トレイに着地してしまうからです。本ガイドは、それを安定してテストするための開発者向けの地図です。フレームワーク別・シナリオ別のより詳しいチュートリアルへのリンクも添えています。

なぜメールはテストしにくいのか

メールは非同期で、SMTP を経由して届くため、到着まで数秒かかることがあります。一方でテストは、速く決定的な結果を期待します。ひとつの受信トレイを複数の実行で共用すると、混線や古いメッセージの問題が起きます。メールテストという営みは、結局のところ、この不安定さをいかに取り除くかに尽きます。

パターン：テストごとにひとつの受信トレイ

解決策は、テスト実行のたびに新しくルーティング可能な受信トレイを払い出し、それをプログラムから読むことです。使い捨てメール API は、まさにこれを実現します。アドレスを作り、UI をメールのステップまで進め、メッセージを取得してリンクやコードを抽出する、という流れです。作成・ポーリング・読み取りの基本要素については使い捨てメール API ガイドを、全体像についてはメール認証テスト自動化の概要をご覧ください。

ポーリング vs webhook

メッセージが届くまで受信トレイをポーリングする方法と、メールが着地した瞬間にサービスから通知を push してもらう方法があります。webhook なら遅延も無駄なリクエストもなくなります。webhook で受信メールを受け取るをご覧ください。CI ではタイムアウトを短めに設定しましょう。テスト環境のトランザクションメールは 5 秒以内に届くはずなので、ポーリングの上限は 20〜30 秒もあれば十分です。

フレームワーク別

パターンはどこでも同じで、違うのは配管の部分だけです。まずは専用の Playwright メールテストチュートリアルから始め、続いて Cypress と Selenium のガイドへ。どれも要点は同じで、「作成・待機・抽出」をひとつの再利用可能なヘルパーにまとめ、個々のテストを読みやすく保つことです。

シナリオ別

現実のフローのほとんどは、3 つのパターンのバリエーションです。OTP と 2FA ログイン、パスワードリセット、そしてマジックリンクサインインです。いずれも同じ「受信トレイを読む」ステップに加えて、適切なトークンを抽出する手段が必要になります。

言語別、そして CI で

Node.js から受信しようと、Python からだろうと、GitHub Actions パイプラインの中だろうと、受信トレイ API の HTTP インターフェースは同じです。キーで認証し、受信トレイを作り、メッセージを読むだけ。PR ごとに使い捨ての受信トレイを用意すれば、CI の実行を互いに隔離できます。

MoeMail はどう役立つか

MoeMail は API キー認証と webhook を備えた完全な OpenAPI を公開しているので、どんな言語や CI ランナーからでも、メールボックスを作り、メッセージをポーリングし、受信メールに反応できます。オープンソースでセルフホストも可能なので、独自ドメインを使いたい、外部のクォータに縛られたくない、という場合にも対応できます。プロフィールからキーを取得して OpenAPI ドキュメントを読むか、メールボックスを作成してデータの形を確かめてみてください。