Mailosaur Ltd Mailosaur logo
Mailosaur LtdMailosaur logo
Mailosaur Ltd Mailosaur logo
Frameworks and toolsCypressEmail testing

Email testing for Cypress

Learn how to integrate Mailosaur email testing into Cypress

What you'll find in this guide

  • How to test various aspects of emails
  • Testing links and codes
  • Managing email tests

What you'll need

  • An understanding of how to use Cypress.
  • A Mailosaur account. Start a free trial if you don't have one.
  • A Cypress project with Mailosaur's API client configured. See our short guide to get started.

Basic usage

To use Cypress for email testing, you need to:

  1. Send an email message to your Mailosaur inbox (e.g. by requesting a password reset)
  2. Connect to the Mailosaur API using our official client library.
  3. Search for the email sent in step 1.
  4. Perform assertions in the same way as any other test.

To learn about Server IDs, and what to replace SERVER_ID with, see sending test emails to Mailosaur.

// Search for the message
cy.mailosaurGetMessage("SERVER_ID", {
  sentTo: "my-test@SERVER_ID.mailosaur.net",
}).then((message) => {
  // Perform test assertions
  expect(message.from[0].name).to.equal("Support");
  expect(message.from[0].email).to.equal("noreply@acme.com");
});

This example searches for the email address that a message was sent to. You can also search using any of the below criteria:

Parameter Description
sentTo The full email address to which the target message was sent
sentFrom The full email address from which the target message was sent
subject Finds messages where the subject line contains this text
body Finds messages where the message body contains this text

Test email addresses

Each inbox in your account (known as a server) has an identifier, referred to as a Server ID. Use this ID to give your inbox a domain name like this: SERVER_ID.mailosaur.net.

This domain supports a wildcard email pattern, meaning any email address ending @SERVER_ID.mailosaur.net works immediately.

You don't need to create email addresses before using them. If you need support creating unique email address, you can use this method:

cy.mailosaurGenerateEmailAddress("SERVER_ID").then((emailAddress) => {
  cy.log(emailAddress); // "bgwqj@SERVER_ID.mailosaur.net"
});

Find an email

Search for a specific message within your inbox. We recommend using cy.mailosaurGetMessage(), as it will automatically wait for messages to arrive, and will return the full message result.

cy.mailosaurGetMessage("SERVER_ID", {
  sentTo: "test123@SERVER_ID.mailosaur.net",
}).then((message) => {
  cy.log(message.html.body);
});

Time range for searching

By default searches only look for messages received in the last hour. To look back further in your message history, If you want to look further back than this, just set the 'received after' parameter.

// Calculate a datetime for yesterday
const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);

// Use this timestamp in the search
cy.mailosaurGetMessage("SERVER_ID", {
  sentTo: "test123@SERVER_ID.mailosaur.net",
}, {
  receivedAfter: yesterday
}).then((message) => {
  
});

"No matching messages" troubleshooting

If you see the error "No matching messages found in time" when searching for messages:

  • Ensure that target email or SMS message is visible in the Mailosaur Dashboard, as it may not have arrived at all.
  • Check when the message arrived. By default, searches only include messages received within the last hour. See "time range for searching" above on how to override this.
  • Check you have correctly set the sent to parameter in your search criteria.

Alternate ways to fetch emails

It is often preferable to use cy.mailosaurGetMessage()

The mailosaurListMessages and mailosaurSearchMessages methods will only return basic summaries, meaning properties like the message body are not included. To get this data, you need to use cy.mailosaurGetMessageById().

We recommend using cy.mailosaurGetMessage() as it automatically waits for a matching result and returns the message.

List current inbox contents

See a full list of everything currently in your inbox.

// List the most recent messages
cy.mailosaurListMessages("SERVER_ID")
  .then((result) => {
    // Get the most recent message (the first one in the list)
    const latestMessage = result.items[0];

    // Get the full message object
    return cy.mailosaurGetMessageById(latestMessage.id);
  })
  .then((message) => {
    cy.log(message.html.body);
  });

Searching for multiple messages

Identify if multiple messages meet the same criteria.

// Search for all messages sent to someone@SERVER_ID.mailosaur.net.
// Limit results to the first 10 matches only.
cy.mailosaurSearchMessages(
  "SERVER_ID",
  {
    sentTo: "someone@SERVER_ID.mailosaur.net",
  },
  {
    page: 0,
    itemsPerPage: 10,
  }
)
  .then((result) => {
    // Get the most recent message (the first one in the list)
    const latestMessage = result.items[0];

    // Get the full message object
    return cy.mailosaurGetMessageById(latestMessage.id);
  })
  .then((message) => {
    cy.log(message.html.body);
  });

Common test scenarios

Testing basic properties

Once you have an email (e.g. using messages.get), you can test the properties of that email:

// Test the email subject line
expect(message.subject).to.equal("Password reset");

// Test sender information
expect(message.from[0].name).to.equal("Support");
expect(message.from[0].email).to.equal("noreply@acme.com");

// Test recipient information
expect(message.to[0].name).to.equal("John Smith");
expect(message.to[0].email).to.equal("john@SERVER.mailosaur.net");

Testing carbon-copy recipients

// Carbon copy (CC) recipients
expect(message.cc[0].name).to.equal("Jane Smith");
expect(message.cc[0].email).to.equal("jane@SERVER.mailosaur.net");

// Blind carbon copy (BCC) recipients
expect(message.bcc[0].name).to.equal("Jill Smith");
expect(message.bcc[0].email).to.equal("jill@SERVER.mailosaur.net");

Testing email contents

Most emails will contain separate HTML and plain text content. Here�s how to test each type:

Plain text content

// Check that the email contains some text
cy.log(message.text.body); // "Hi Jason, ..."

HTML content

With HTML, you can perform basic contains or equals assertions in the same way as plain text content:

// Check that raw HTML contains some expected content
cy.log(message.html.body); // "<span>Hello world</span>"

Testing links

Any links in the content of your email are instantly available via the html.links or text.links arrays, depending on which content the link was found in:

// Working with links in HTML content
const linkInHtml = message.html.links[0];
expect(linkInHtml.text).to.equal("Google Search");
expect(linkInHtml.href).to.equal("https://www.google.com/");

// Working with links in plain text content
const linkInPlainText = message.text.links[0];
expect(linkInPlainText.href).to.equal("https://www.google.com/");

Clicking a link

To simulate a link being clicked, without needing to do anything on the target page, use HttpClient:

const https = require("https");

// ...

const href = message.html.links[0].href;

// Make an HTTP call to simulate someone clicking a link
https.get(href, (r) => cy.log(r.statusCode)); // 200

Testing verification codes

Codes are automatically extracted from the content of your message and made available via the html.codes or text.codes arrays:

// Working with codes in HTML content
const codeInHtml = message.html.codes[0];
expect(codeInHtml.value).to.equal("456812");

// Working with codes in plain text content
const codeInText = message.text.codes[0];
expect(codeInText.value).to.equal("456812");

Testing attachments

Any email attachments are made available via the attachments array:

// Number of attachments found
cy.log(message.attachments.length); // 2

// Get the first attachment
const attachment = message.attachments[0];

// Check attachment attributes
expect(attachment.fileName).to.equal("example.pdf");
expect(attachment.contentType).to.equal("application/pdf");

expect(attachment.length).to.equal(4028);

Save an attachment to disk

You can download and save attachments using the files.getAttachment and fs methods:

const firstAttachment = message.attachments[0];
const file = await mailosaur.files.getAttachment(firstAttachment.id);
fs.writeFileSync(firstAttachment.fileName, file);

Encoding attachments

In some scenarios you may need a base64-encoded copy of an attachment:

const firstAttachment = message.attachments[0];
const file = await mailosaur.files.getAttachment(firstAttachment.id);
const base64 = file.toString("base64");
console.log(base64);

Testing images and web beacons

Any images found within the HTML content of an email are made available via the html.images array:

// Number of images found
cy.log(message.html.images.length);

// Get the first image
const image = message.html.images[0];

// Check image attributes
expect(image.src).to.equal("https://example.com/balloon.png");
expect(image.alt).to.equal("A hot air balloon");

To test whether an image is accessible online, or that a web beacon is working correctly, you can perform an HTTP request:

const https = require("https");

// ...

const image = message.html.images[0];
cy.log(image.src); // "https://example.com/s.png?abc123"

// Make an HTTP call to trigger the web beacon
https.get(image.src, (r) => cy.log(r.statusCode)); // 200

Sending an email

If your product is capable of handling inbound emails, use Mailosaur�s sending feature to trigger this functionality in your product.

The messages.create command creates and sends an email to a verified external email address:

cy.mailosaurCreateMessage("SERVER_ID", {
  to: "verified-address@example.com",
  send: true,
  subject: "Request",
  text: "Please can you give us a call back?",
});

The options available to use with this method are:

Parameter Description
send This must be set to true if you are sending an outbound email
to The email address to which the email will be sent. Must be a verified email address.
subject The email subject line
text The plain text body of the email.
html The HTML body of the email.
attachments Optional attachments (see 'include attachments' below)

Include attachments

You can include attachments in emails sent via the API, by including an array of base64-encoded attachment objects:

const attachments = [
  {
    fileName: "cat.png",
    contentType: "image/png",
    content: "{BASE64_ENCODED_FILE}",
  },
];

cy.mailosaurCreateMessage("SERVER_ID", {
  to: "verified-address@example.com",
  send: true,
  subject: "Email from Mailosaur",
  html: "<p>Hello world.</p>",
  attachments: attachments,
});

Replying to an email

If your product is capable of handling customer replies, Mailosaur�s reply feature can simulate this. Any replyis sent back to the address it was originally sent from:

cy.mailosaurReplyToMessage("MESSAGE_ID", {
  text: "FYI",
});
Parameter Description
text Any additional text content to include in the reply
html Any additional HTML content to include in the reply
subject Optionally override the default subject line
attachments Optional attachments (see 'include attachments' above)

Forwarding a message to email

You can forward messages from your Mailosaur account to external email addresses one-by-one, or via the creation of automated forwarding rules. Before you do this, you must set up a verified external email address:

cy.mailosaurForwardMessage("MESSAGE_ID", {
  to: "verified-address@example.com",
  text: "FYI",
});
Parameter Description
to The email address to which the message will be sent. Must be a verified email address
text Any additional text content to forward the message with
html Any additional HTML content to forward the message with
subject Optionally override the default subject line

Deleting messages

Deleting an individual message

Permanently deletes a single message and associated attachments. This operation cannot be undone:

cy.mailosaurDeleteMessage("MESSAGE_ID");

Delete all messages

Permanently deletes all messages and attachments held in the specified server/inbox. This operation cannot be undone:

cy.mailosaurDeleteAllMessages("SERVER_ID");

See also