Playwright でメール認証とログインコードをテストする

Playwright でサインアップメールをテストする

Playwright でメール認証をテストするには、テストごとに新しいアドレスを用意してサインアップし、コードまたはリンクを待ってフローを完了します。proxymail-qa パッケージを使えば、呼び出しは 2 回で済みます。フームの前に createAddress、後に waitForCode または waitForLink です。Free プランで、ローカルでも CI でも動作します。

更新日：2026年10月17日

セットアップ

proxymail-qa パッケージをインストールし、API キーを PROXYMAIL_QA_API_KEY に設定します。シェル、Git から除外した .env ファイル、または CI のシークレットに設定できます。Free プランで十分です。

npm install --save-dev proxymail-qa

テスト

proxymail-qa/playwright から test と expect をインポートします。すべてのテストで qa フィクスチャを使えます。これはクライアントで、後述のレポートのために各呼び出しでテスト名も伝えます。

import { test, expect } from 'proxymail-qa/playwright';

test('sign-up sends a working code', async ({ page, qa }) => {
  const { address, password } = await qa.createAddress({ persona: true, password: true });
  const submitted = new Date();

  await page.goto('/signup');
  await page.getByLabel('Email').fill(address);
  await page.getByLabel('Password').fill(password);
  await page.getByRole('button', { name: 'Sign up' }).click();

  const { value } = await qa.waitForCode(address, { since: submitted });
  await page.getByLabel('Code').fill(value);
  await expect(page).toHaveURL(/welcome/);

  await qa.deleteAddress(address);
});

コードではなくリンクの場合:

const { value: link } = await qa.waitForLink(address, { type: 'verify', since: submitted });
await page.goto(link);

type は verify、magic_signin、invite、reset、any のいずれかです。ラベルとルートはここからコピーせず、アプリに合わせてください。

コードだけでなくメールもチェックする

サインアップのテストが成功しても、メールに問題が隠れていることがあります。よくある問題は次の方法で見つけられます:

// Exactly one verification email, not two.
await new Promise((resolve) => setTimeout(resolve, 10_000)); // time for a duplicate
expect((await qa.countEmails(address, { since: submitted, type: 'link' })).count).toBe(1);

// Its link goes to staging, not localhost or production, and it passes SPF, DKIM and DMARC.
const result = await qa.checkEmail(address, { since: submitted, type: 'link', expectHost: 'staging.example.com' });
expect(result.failed).toEqual([]);

checkEmail は、コードの有効期限が書かれていないメールや、スマートフォンの画面に収まらない可能性があるメールも警告します。expectText と expectLanguage を使えば、必要な文言の欠落や言語の誤りも警告します。返すのは判定結果だけで、メール自体は返しません。

CI で実行し、プルリクエストにレポートを表示する

テストの前に GitHub Action を追加し、Playwright の設定にレポーターを追加します。プルリクエストのレポートには、届いたメールとその速さ、各メールの送信元のテスト、失敗したテストと失敗したステップが表示されます。

      - uses: aaquib90/proxymail-qa-action@v1
        with:
          api-key: ${{ secrets.PROXYMAIL_QA_API_KEY }}
      - run: npx playwright test
        env:
          PROXYMAIL_QA_API_KEY: ${{ secrets.PROXYMAIL_QA_API_KEY }}

export default defineConfig({
  reporter: [['list'], ['proxymail-qa/playwright/reporter']],
});

各レポートは同じ名前の直近の実行と比較されます。そのため、メールが遅くなった場合、テストでメールが 2 通届くようになった場合、テストがときどき失敗する場合にもわかります。

詳しくは Playwright ドキュメント、Node.js クライアント、CI での実行を参照してください。

次のサインアップテストで試してみてください

無料プラン、クレジットカード不要。アドレスを作成して、コードやリンクが届くのを確かめてください。

無料アカウントを作成アプリを開く

よくある質問

Playwright テストで認証コードを取得するには?

フォームを送信する直前の時刻を記録し、qa.waitForCode(address, { since }) を呼び出します。最大 30 秒間メールを待ち、コードだけを返すので、テスト内でメールを解析する必要はありません。リンクの場合は、waitForLink が URL を返すので、page.goto で開きます。

テストで古いコードを拾ってしまうことがあるのはなぜですか?

since を指定しないと、以前のステップやテスト実行のメールに一致することがあります。フォームを送信した時刻を渡し、テストごとに専用のアドレスを用意してください。

メールが届かない場合はどうなりますか?

待機は失敗し、Proxy Mail QA で判断できる範囲で理由をメッセージに表示します。最も多いのは、アプリのメールプロバイダーがサンドボックスモードやテストモードになっていて、確認済みのアドレスにしか送信しないケースです。この場合、タイムアウトを延ばしても解決しません。送信側を修正してください。

テストを並列実行できますか?

はい。テストごとに専用のアドレスを用意するか、実行ごとに 1 つのアドレスを使い、テストごとにプラスタグを付けてください(name+worker1@ は name@ に届き、待機は自分のタグにのみ一致します)。待機は、どれだけ長く続いても 1 リクエストとして数えられます。