Guide: Testing Emails in Playwright

To test email verification in Playwright, give each test its own inbox with a fixture, let the page trigger the email, then call waitForOtp() for a code or waitFor() for a link and continue in the browser.

How to Test Email Verification in Playwright

Create the inbox in a Playwright fixture so every test (and every parallel worker) gets a unique address. Type that address into your sign-up form, wait for the code from the inbox's createdAt, and fill it in. The wait returns within about two seconds of the email arriving, so there are no sleeps and no stale codes from earlier runs.

bash
npm install --save-dev @playwright/test @receiverdotemail/sdk
export RECEIVER_API_KEY="recv_live_..."
tests/fixtures.ts
import { test as base, expect } from "@playwright/test";
import { ReceiverClient, type Inbox } from "@receiverdotemail/sdk";

type TestFixtures = { inbox: Inbox };
type WorkerFixtures = { receiver: ReceiverClient };

export const test = base.extend<TestFixtures, WorkerFixtures>({
  // One client per worker (reads RECEIVER_API_KEY)
  receiver: [
    async ({}, use) => {
      await use(new ReceiverClient());
    },
    { scope: "worker" },
  ],

  // A fresh, unique address for every test
  inbox: async ({ receiver }, use) => {
    await use(await receiver.inboxes.create({ prefix: "pw" }));
  },
});

export { expect };
tests/signup.spec.ts
import { test, expect } from "./fixtures";

test("sign-up with an emailed verification code", async ({ page, inbox, receiver }) => {
  // 1. Trigger the email from the UI
  await page.goto("/signup");
  await page.getByLabel("Email").fill(inbox.address);
  await page.getByRole("button", { name: "Send code" }).click();

  // 2. Wait for the code (throws ReceiverTimeoutError if it never arrives)
  const otp = await receiver.emails.waitForOtp({
    recipient: inbox.address,
    since: inbox.createdAt,
    codeLength: 6,
    timeout: 60,
  });

  // 3. Submit it and assert
  await page.getByLabel("Verification code").fill(otp.code);
  await page.getByRole("button", { name: "Verify" }).click();
  await expect(page).toHaveURL(/\/dashboard/);
});

Testing a Magic Link or Verification Link

For links, use waitFor(). The returned email has a parsed links array; pick the one that points at your app and open it with page.goto(), so the session cookie lands in the test's browser context.

tests/magic-link.spec.ts
import { test, expect } from "./fixtures";

test("log in with a magic link", async ({ page, inbox, receiver }) => {
  await page.goto("/login");
  await page.getByLabel("Email").fill(inbox.address);
  await page.getByRole("button", { name: "Email me a link" }).click();

  const email = await receiver.emails.waitFor({
    recipient: inbox.address,
    since: inbox.createdAt,
    subject: "sign in",
    timeout: 60,
  });

  // Skip unsubscribe, logo and footer links: match your app's login path
  const magicLink = email.links.find((link) => new URL(link).pathname.startsWith("/auth/magic"));
  expect(magicLink, "magic link in email").toBeDefined();

  await page.goto(magicLink!);
  await expect(page.getByText(`Signed in as ${inbox.address}`)).toBeVisible();
});

The same pattern covers email verification links, password resets and invitations. The magic link guide has more on choosing the right link.

Timeouts

Playwright's default test timeout is 30 seconds. Give email tests more room than the timeout you pass to waitFor():

playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  timeout: 90_000,
  use: { baseURL: "http://localhost:3000" },
});

Python: pytest-playwright

The Python SDK is async, so use Playwright's async API with the pytest-playwright-asyncio plugin, which provides an async page fixture:

bash
pip install receiverdotemail pytest-playwright-asyncio
playwright install chromium
pytest.ini
[pytest]
asyncio_default_fixture_loop_scope = session
asyncio_default_test_loop_scope = session
test_signup.py
import re
import pytest
from playwright.async_api import Page, expect
from receiverdotemail import ReceiverClient


@pytest.mark.asyncio(loop_scope="session")
async def test_signup_with_code(page: Page):
    async with ReceiverClient() as receiver:  # reads RECEIVER_API_KEY
        inbox = await receiver.inboxes.create(prefix="pw")

        await page.goto("https://your-app.com/signup")
        await page.get_by_label("Email").fill(inbox.address)
        await page.get_by_role("button", name="Send code").click()

        otp = await receiver.emails.wait_for_otp(
            recipient=inbox.address,
            since=inbox.created_at,
            code_length=6,
            timeout=60,
        )

        await page.get_by_label("Verification code").fill(otp.code)
        await page.get_by_role("button", name="Verify").click()
        await expect(page).to_have_url(re.compile(r"/dashboard"))

For a link, call receiver.emails.wait_for(...) and pick from email.links the same way, then await page.goto(link).

Tips

  • Parallel workers: the inbox fixture mints a new address per test, so fullyParallel: true and sharding are safe.
  • Resend flows: wait again with since set to the first email's receivedAt so only the new email matches.
  • Several codes: otp.candidates lists every code found, newest first. Pass codeLength to skip years and order numbers.
  • CI: store RECEIVER_API_KEY as a secret. See CI/CD Integration.

Next Steps