Email Testing

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:

Property	Type	Description
`subject`	`string`	Email subject line
`text`	`string`	Plain text body
`html`	`string`	HTML body
`links`	`{ text?: string; href?: string }[]`	Links found in the email
`codes`	`string[]`	Verification codes extracted from the email

Options

Option	Type	Default	Description
`emailId`	`string`	Random	A specific email id to use instead of generating a random one
`timeout`	`number`	`30000`	Timeout in milliseconds to wait for the email

Getting Started

Platform

Features

Integrations

Trigger a test run

Usage

Dynamic email

Static email

Filtering emails

Email properties

Options

​Usage

​Dynamic email

​Static email

​Filtering emails

​Email properties

​Options

Usage

Dynamic email

Static email

Filtering emails

Email properties

Options