Skip to content
nofeb

Receive verification codes in Playwright tests

In each test, create a nofeb inbox with a short time to live, type its address into the form, then call waitForEmail with has_otp and the time you submitted. It returns as soon as the email lands, with the code in otps[0].code and any verify or magic-login link in links. No regex, no sleep.

Checked against the engine on .

What do you need?

  • @playwright/test
  • @nofeb/sdk and a NOFEB_API_KEY in the test environment

Steps

  1. 1. Install the SDK

    Add the TypeScript SDK as a dev dependency and expose NOFEB_API_KEY to the test runner (a CI secret).

    Install
    npm install --save-dev @nofeb/sdk
  2. 2. Write the test

    One inbox per test keeps parallel workers from reading each other's mail. Record since before submitting, so a fast email is not missed.

    tests/signup.spec.ts
    import { test, expect } from "@playwright/test";
    import { Nofeb } from "@nofeb/sdk";
    
    const nf = new Nofeb(); // NOFEB_API_KEY
    
    test("sign-up emails a working code", async ({ page }) => {
      const inbox = await nf.inboxes.create({ ttl_seconds: 900 }); // removes itself
      const since = new Date();
    
      await page.goto("/signup");
      await page.getByLabel("Email").fill(inbox.address);
      await page.getByRole("button", { name: "Create account" }).click();
    
      const { message, timed_out } = await nf.inboxes.waitForEmail(inbox.id, { has_otp: true, timeout: 60, since });
      expect(timed_out, "verification email arrived").toBe(false);
    
      await page.getByLabel("Code").fill(message!.otps[0].code);
      await page.getByRole("button", { name: "Verify" }).click();
      await expect(page.getByText("Welcome")).toBeVisible();
    });
  3. 3. Magic links instead of codes

    Read links: each has a kind of verify, magic_login, password_reset, unsubscribe or other.

    Follow a magic link
    const { message } = await nf.inboxes.waitForEmail(inbox.id, { subject: "Sign in", timeout: 60, since });
    const link = message!.links.find((l) => l.kind === "magic_login" || l.kind === "verify");
    await page.goto(link!.url);
  4. 4. Run it in CI

    Nothing else to run: no mail server, no SMTP container. Inboxes with a time to live clean themselves up, and an inbox.expired event says so.

Why does the test pass "since"?

By default a wait matches only mail that arrives after the call starts. Fast senders can deliver before Playwright reaches the wait, so record the time before submitting the form and pass it as since.

Why not one shared inbox with plus-addresses?

You can: mail to qa+run-114@ reaches qa@, and a subject or sender filter picks the right message. A fresh inbox per test is simpler when workers run in parallel, and some forms reject the plus sign.

Frequently asked questions

How do I test an email OTP in Playwright?

Create an inbox, fill its address into the form, then await nf.inboxes.waitForEmail(id, { has_otp: true, since }) and use message.otps[0].code. The call blocks until the email arrives, up to the timeout.

How long can the test wait?

The server holds each poll for up to 60 seconds; the SDK chains polls for longer timeouts.

Does this work for real external email, not only my staging server?

Yes. The inbox is a real address on the internet, so third-party senders such as identity providers can deliver to it.

Status of everything on this page

Every capability named above, with its status as reconciled against the engine.

CapabilityWhat it doesStatus
Disposable inboxes with a time to live Give an inbox a lifetime in seconds; it and its mail are removed when it expires, and an event says so. Shipped
Wait for an email Long-poll an inbox for up to a minute until a message matching sender, subject or has-a-code arrives. Shipped
One-time code and link extraction Verification codes and classified links are pulled out of every message and returned as fields. Shipped
Unlimited inboxes Create as many inboxes as the work needs, with a generated or chosen address and an idempotent client reference. Shipped
Plus-addressing Mail to name+tag@ reaches the name@ inbox. Shipped
TypeScript and Python SDKs Official clients generated from the OpenAPI document: @nofeb/sdk for Node, Deno, Bun and edge runtimes, and nofeb for Python with sync and asyncio clients. Both chain long polls for waitForEmail, retry idempotent requests, page through lists and verify webhook signatures. Shipped