Skip to main content
Empirical provides an EmailClient that lets you test email workflows in your application. It generates unique email addresses and waits for incoming emails, making it easy to test OTPs, invite flows, and notification emails. All test repositories managed by Empirical have this built-in — no additional setup is required.

​
Usage

​
Dynamic email

Generates a random email address that can be used for the test (e.g. invite a new user). 
import { EmailClient } from "@empiricalrun/playwright-utils";
import { expect } from "@playwright/test";

const client = new EmailClient();
const address = client.getAddress();

// Input the `address` in the application
// that sends the email.

// Wait for the email to arrive
const email = await client.waitForEmail();
expect(
  email.links.find((l) => l.text === "Join your team")
).toBeTruthy();

​
Static email

Uses a known (static) email address that can be used to login into an application. The email id is appended with a managed domain to get the full email address. 
import { EmailClient } from "@empiricalrun/playwright-utils";

const emailId = "test-login-user";

const client = new EmailClient({ emailId });
const address = client.getAddress(); // Returns full address with domain

// Wait for the email to arrive
const email = await client.waitForEmail();

// Get login OTP
const loginCode = email.codes[0];

​
Filtering emails

You can filter emails by sender, subject, or body content. The subject and body filters use substring matching, so you don’t need to provide the full value. The from filter requires the full email address. 
const email = await client.waitForEmail({
  from: "no-reply@example.com",
  subject: "Verify your email",
});

​
Email properties

The received email object has the following properties:
PropertyTypeDescription
subjectstringEmail subject line
textstringPlain text body
htmlstringHTML body
links{ text?: string; href?: string }[]Links found in the email
codesstring[]Verification codes extracted from the email

​
Options

OptionTypeDefaultDescription
emailIdstringRandomA specific email id to use instead of generating a random one
timeoutnumber30000Timeout in milliseconds to wait for the email