What do you need?
- @playwright/test
- @nofeb/sdk and a NOFEB_API_KEY in the test environment
Steps
-
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. Write the test
One inbox per test keeps parallel workers from reading each other's mail. Record
sincebefore 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. Magic links instead of codes
Read
links: each has akindof 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. 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.
| Capability | What it does | Status |
|---|---|---|
| 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 |