Email testing with Playwright and Mailosaur

What is Playwright?

Playwright is a Node.js library that lets you automate modern web browsers. Playwright is made by Microsoft and is used as part of the Quality Assurance testing of Microsoft’s own service.

At this stage, we assume that you already know how to test with Playwright, however if you’re just getting started, check out the official Playwright guide, then come back here to start testing email and SMS!

What is Mailosaur?

Mailosaur is a service that captures email and SMS messages and lets you test them, both via it’s web dashboard and via the Mailosaur testing API.

If you don’t already have one, create a free account trial now, and send an email into Mailosaur first. Once you have this working, you’re ready to start testing!

Create a Playwright project

It only takes a few minutes to create a simple Playwright project to work with, but if you have an existing project you can skip this step.

First, initialise a new project with:

npm init playwright@latest

When prompted, select the following options:

Getting started with writing end-to-end tests with Playwright:
Initializing project in '.'
✔ Do you want to use TypeScript or JavaScript? · TypeScript
✔ Where to put your end-to-end tests? · tests
✔ Add a GitHub Actions workflow? (y/N) · false
✔ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n) · true

A simple Playwright project is created for you, with some example tests included within the file tests/example.spec.ts:

import { test, expect } from "@playwright/test";

test("has title", async ({ page }) => {
  await page.goto("https://playwright.dev/");

  // Expect a title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
});

test("get started link", async ({ page }) => {
  await page.goto("https://playwright.dev/");

  // Click the get started link.
  await page.getByRole("link", { name: "Get started" }).click();

  // Expects page to have a heading with the name of Installation.
  await expect(
    page.getByRole("heading", { name: "Installation" })
  ).toBeVisible();
});

You can now run these tests using:

$ npx playwright test

The output looking something like this, with all tests passing:

Running 6 tests using 5 workers
  6 passed (5.1s)

Install the Mailosaur API client

To allow you to easily test email in Playwright, Mailosaur provides an official Node.js library with everything you need to easily automate email testing.

Install the Mailosaur Node.js library via npm

npm install mailosaur

Import Mailosaur into your project

In order to connect to Mailosaur, you need an API key. You access your API key via in the account settings area.

In your tests, simply import the Mailosaur library, using your API key, at the top of your spec file:

import { test, expect } from "@playwright/test";
import MailosaurClient from "mailosaur";

const mailosaur = new MailosaurClient("YOUR_API_KEY_HERE");

Basic usage

The messages.get method automatically waits for the first email to arrive that matches the search criteria you provide.

test("password reset", async ({ page }) => {
  const serverId = "YOUR_SERVER_ID_HERE";
  const testEmailAddress = `some-test-run123@${serverId}.mailosaur.net`;

  // Navigate to a password reset page, and submit the form to trigger an email
  await page.goto("https://example.mailosaur.com/password-reset");
  await page.fill("#email", testEmailAddress);
  await page.click('button[type="submit"]');

  // Connect to Mailosaur, and wait for that email to arrive
  const email = await mailosaur.messages.get(serverId, {
    sentTo: testEmailAddress,
  });

  expect(email.subject).toBe("Password reset");
});

Testing email with Playwright

Playwright users should use the official Node.js library for Mailosaur. Head over to our email testing guide for Node.js for examples on everyhing you could possibly want to test with Playwright, including: