How to test email and SMS with Cypress

Before you begin

This guide assumes that you already know how to test with Cypress, however if you’re just getting started, check out the official Cypress documentation.

If you don’t already have one, create a Mailosaur account.

Make sure you know how to send email to Mailosaur first. Once you have this working, you’re ready to start testing!

Install the Mailosaur plugin

Mailosaur provides an official set of custom commands, that allow you to test email and SMS seamlessly in Cypress.

Extend Cypress, by installing Mailosaur’s custom commands package cypress-mailosaur.

Install via npm or yarn

cd your/project/path

npm i -D cypress-mailosaur
# or
yarn add -D cypress-mailosaur

Once installed, register the commands by appending an import statement to the cypress/support/e2e.js file (or cypress/support/index.js in older versions of Cypress), within your project folder:

echo "import 'cypress-mailosaur'" >> cypress/support/e2e.js

Authenticating with Mailosaur

In order to connect to Mailosaur, you need to add your API key to your tests. You access your API key via the account settings screen.

Add API key to cypress.config.js

module.exports = defineConfig({
  env: {
    MAILOSAUR_API_KEY: "your-key-here",
  },

  // ...
});

Alternatively, set API key via a system environment variable

To set the environment variable on your machine, it needs to be prefixed with either CYPRESS_ or cypress_.

export CYPRESS_MAILOSAUR_API_KEY=your-key-here

Writing your first test

In this example, we’ll navigate to a password reset page, request a new password link (sent via email) and get that email.

touch cypress/e2e/password-reset.cy.js

Now edit the file to something like this:

describe('Password reset', () => {
  const serverId = 'SERVER_ID'; // Replace SERVER_ID with an actual Mailosaur Server ID
  const testEmail = `something@${serverId}.mailosaur.net`

  it('Makes a Password Reset request', () => {
    cy.visit('https://github.com/password_reset')
    cy.title().should('equal', 'Forgot your password?')
    cy.get('#email_field').type(testEmail)
  })

  it('Gets a Password Reset email', () => {
    cy.mailosaurGetMessage(serverId, {
      sentTo: testEmail
    }).then(email => {
      expect(email.subject).to.equal('Reset your password');
      passwordResetLink = email.text.links[0].href;
    })
  })

  it('Follows the link from the email', () => {
    const validPassword = 'delighted cheese jolly cloud'

    cy.visit(passwordResetLink)
    cy.title().should('contain', 'Change your password')
    cy.get('#password').type(validPassword)
    cy.get('#password_confirmation').type(validPassword)
    cy.get('form').submit()
  })
})

Narrowing your search results

Only find messages received after a certain time

By default, searchs include messages received in the last hour, but you can customise the search window with the receivedAfter option.

This example shows you how to only include emails received after your test started:

const testStart = new Date()

// Perform the steps that send a message here

cy.mailosaurGetMessage('SERVER_ID', {
  sentTo: '...'
}, {
  receivedAfter: testStart
}).then(message => {
  cy.log(message.subject)
})

Search criteria

As you can see in the examples so far, you can search for the email address or phone number a message was sent to, but you can also search using this criteria too:

PARAMETER	DESCRIPTION
sentFrom	The full email address from which the target message was sent.
sentTo	The full email address to which the target message was sent.
subject	Find emails where the subject line contains this text.
body	Finds messages where the message body contains this text.

Email not found in time?

By default, the mailosaurGetMessage command only looks for emails that were received by Mailosaur within the last hour.

You can override this by setting receivedAfter, like so:

cy.mailosaurGetMessage(serverId, {
  sentTo: testEmail
}, {
  // Find messages received since Jan 1st 2020. This will be slow!
  receivedAfter: new Date('2020-01-01T00:00:00Z')
})

Common test cases

Now that you have a working project that fetches an email, you can use this to begin writing tests for various pieces of functionality.

Check out these guides on the most common test cases:

How to test the text content of email or SMS

Learn how to test the text content of email or SMS with Mailosaur.

HTML content of an email

Learn how to work with the HTML content found within your emails.

Extracting codes from email and SMS

Learn how to test verification codes found in email and SMS messages with Mailosaur.

Extracting links from email and SMS

Learn how to test hyperlinks found in email and SMS messages with Mailosaur.

Email attachments

Learn how to test the email attachments with Mailosaur.

Images and web beacons

Learn how to work with images, including web beacons, within an HTML email.

Message properties

Learn how to test the common properties of an email or SMS message with Mailosaur.

How to test email spam score

Learn how to test the SpamAssassin score of an email with Mailosaur.

SMS Testing

You can test SMS messages in much the same way as email. Take a look at our guide on testing SMS messages for more information.

Library reference

Messages

Messages is the collective name given to the email and/or SMS messages that are sent into Mailosaur for testing. The message object contains everything you need to perform in-depth automated testing.

cy.mailosaurGetMessage(server, criteria, options)

Waits for a message to be found. Returns as soon as a message matching the specified search criteria is found.

Recommended: This is the most efficient method of looking up a message, therefore we recommend using it wherever possible.

cy.mailosaurGetMessage('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
}).then((message) => {
  cy.log('Message subject:', message.subject);
});

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

Criteria

PARAMETER	DESCRIPTION
sentFrom	The full email address from which the target message was sent.
sentTo	The full email address to which the target message was sent.
subject	The subject line of the target email.
body	Search for part of the message body.
match	If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.

Options

PARAMETER	DESCRIPTION
timeout	Specify how long to wait for a matching result (in milliseconds, default value is 10 seconds).
receivedAfter	Limits results to only messages received after this date/time (default 1 hour ago).

cy.mailosaurGetMessage('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
}, {
  // Search all messages received after midnight 5th Feb 2020
  receivedAfter: new Date(2020, 1, 5)
});

cy.mailosaurListMessages(server, options)

Returns a list of your messages in summary form. The summaries are returned sorted by received date, with the most recently-received messages appearing first.

Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call mailosaurGetMessageById. Alternatively, we recommend using the mailosaurGetMessage method, which is a far more efficient approach.

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

  cy.log('Subject:', message.subject);
});

Options

receivedAfter Allows you to customise how far back to look for messages.
page Used alongside itemsPerPage to paginate through results. This is zero-based, meaning 0 is the first page of results.
itemsPerPage A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50.
dir Optionally limits results based on the direction (Sent or Received), with the default being Received.

// List all results received after midnight on 3rd Feb 2020
cy.mailosaurListMessages('SERVER_ID', {
  page: 0,
  itemsPerPage: 10,
  receivedAfter: new Date(2020, 1, 3)
});

cy.mailosaurSearchMessages(server, criteria, options)

Returns a list of messages matching the specified search criteria, in summary form. The messages are returned sorted by received date, with the most recently-received messages appearing first.

Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call mailosaurGetMessageById. Alternatively, we recommend using the mailosaurGetMessage method, which is a far more efficient approach.

cy.mailosaurSearchMessages('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
}).then((result) => {
  // Get the most recent match
  const message = result.items[0];

  cy.log('Subject:', message.subject);
});

Criteria

PARAMETER	DESCRIPTION
sentFrom	The full email address from which the target message was sent.
sentTo	The full email address to which the target message was sent.
subject	The subject line of the target email.
body	Search for part of the message body.
match	If set to `ALL` (default), then only results that match all specified criteria will be returned. If set to `ANY`, results that match any of the specified criteria will be returned.

Options

PARAMETER	DESCRIPTION
timeout	If provided, determines how long to wait for a matching result (provided in milliseconds).
errorOnTimeout	When set to `false`, an error will not be throw if timeout is reached (default: `true`).
receivedAfter	Allows you to customise how far back to look for messages.
page	Used alongside `itemsPerPage` to paginate through results. This is zero-based, meaning `0` is the first page of results.
itemsPerPage	A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50.
dir	Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`.

// Search for all messages sent to someone@SERVER_ID.mailosaur.net,
// received after midnight on 3rd Feb 2020. Limit results to
// the first 10 matches only.
cy.mailosaurSearchMessages('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
}, {
  page: 0,
  itemsPerPage: 10,
  receivedAfter: new Date(2020, 1, 3)
});

cy.mailosaurGetMessagesBySubject(server, subject)

Shorthand for a mailosaurSearchMessages query on message subject. Returns a list of messages matching the specified search criteria, in summary form. The messages are returned sorted by received date, with the most recently-received messages appearing first.

cy.mailosaurGetMessagesBySubject('SERVER_ID', 'Password reset');

cy.mailosaurGetMessagesBySentFrom(server, emailAddress)

Shorthand for a mailosaurSearchMessages query on message sender. Returns a list of messages matching the specified search criteria, in summary form. The messages are returned sorted by received date, with the most recently-received messages appearing first.

cy.mailosaurGetMessagesBySentFrom('SERVER_ID', 'someone@SERVER_ID.mailosaur.net');

cy.mailosaurGetMessagesBySentTo(server, emailAddress)

Shorthand for a mailosaurSearchMessages query on message recipient. Returns a list of messages matching the specified search criteria, in summary form. The messages are returned sorted by received date, with the most recently-received messages appearing first.

cy.mailosaurGetMessagesBySentTo('SERVER_ID', 'someone@SERVER_ID.mailosaur.net');

cy.mailosaurGetMessagesByBody(server, text)

Shorthand for a mailosaurSearchMessages query on message body. Returns a list of messages matching the specified search criteria, in summary form. The messages are returned sorted by received date, with the most recently-received messages appearing first.

cy.mailosaurGetMessagesBySubject('SERVER_ID', 'Hey there');

cy.mailosaurGetMessageById(id)

Retrieves the detail for a single email message. Must be used in conjunction with either mailosaurListMessages or mailosaurSearchMessages in order to get the unique identifier for the required message. We always recommend using the mailosaurGetMessage method instead.

cy.mailosaurListMessages('SERVER_ID').then((result) => {
  const messageId = result.items[0].id;

  cy.mailosaurGetMessageById(messageId).then((message) => {
    cy.log('Subject:', message.subject);
  });
});

cy.mailosaurDeleteMessage(id)

Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.

cy.mailosaurDeleteMessage(messageId)

cy.mailosaurDeleteAllMessages(server)

Permanently deletes all messages held by the specified server. Also deletes any attachments related to each message. This operation cannot be undone.

cy.mailosaurDeleteAllMessages('SERVER_ID')

cy.mailosaurCreateMessage(server, messageCreateOptions)

Creates a new message that can be sent to a verified email address. This is useful in scenarios where you want an email to trigger a workflow in your product.

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

Options

to The email address to which the email will be sent. Must be a verified email address.
send If true, email will be sent upon creation.
subject The email subject line.
text The plain text body of the email.
html The HTML body of the email.

cy.mailosaurForwardMessage(messageId, messageForwardOptions)

Forwards the specified email to a verified email address.

cy.mailosaurForwardMessage('MESSAGE_ID', {
  to: 'verified-address@example.com',
  text: 'FYI'
});

Options

to The email address to which the email will be sent. Must be a verified email address.
text Any additional HTML content to forward the email with.
html Any additional plain text content to forward the email with.

cy.mailosaurReplyToMessage(messageId, messageReplyOptions)

Sends a reply to the specified email. This is useful for when simulating a user replying to one of your emails.

cy.mailosaurReplyToMessage('MESSAGE_ID', {
  text: 'FYI'
});

Options

text Any additional plain text content to include in the reply.
html Any additional HTML content to include in the reply.

Servers

Servers contain all the configuration and set up for.

cy.mailosaurListServers()

Returns a list of your virtual servers. Servers are returned sorted in alphabetical order.

cy.mailosaurListServers().then((result) => {
  cy.log('You have a server called:', result.items[0].name);
});

cy.mailosaurCreateServer(server)

Creates a new virtual server. Only the name property is required to create a new server via the API.

cy.mailosaurCreateServer({
  name: 'My email tests'
});

cy.mailosaurGetServer(id)

Retrieves the detail for a single server. Simply supply the unique identifier for the required server.

cy.mailosaurGetServer('SERVER_ID').then((server) => {
  cy.log(server.name);
});

cy.mailosaurGetServerPassword(id)

Retrieves the password, for use with SMTP and POP3, for a single server. Simply supply the unique identifier for the required server.

cy.mailosaurGetServerPassword('SERVER_ID').then((password) => {
  cy.log(password);
});

cy.mailosaurUpdateServer(server)

Updates a single server.

retrievedServer.name = 'Updated server name';

cy.mailosaurUpdateServer(retrievedServer);

cy.mailosaurDeleteServer(id)

Permanently deletes a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone.

cy.mailosaurDeleteServer('SERVER_ID');

cy.mailosaurGenerateEmailAddress(id)

Utility method to help you generate a random email address for a given server.

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

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