Testing with Cypress JS and on-demand email accounts

MailSlurp is a free Javascript plugin for Cypress JS that lets you create real email addresses in tests then send and receive emails from them. This can be really helpful when testing applications or software. Cypress can be used to test user login and app notifications using real email addresses and phone numbers.

browser testing

What is CypressJS

Cypress is a browser testing tool that lets you automate end-to-end testing of your website. You can write test cases in Javascript using the Cypress NPM package. Make assertions about the state of a website or app and Cypress will run the tests in a browser environment for real browser testing.

Quick links

Cypress has many abilities so try one of these links to get started:

Why test email in Cypress JS?

Many applications today use email. Either for user sign-up, password verification, transactional email, newsletters, and more.

But testing with real email addresses is hard. That's why MailSlurp was created. It lets you generate test email accounts that can send and receive emails. It has an official NPM integration and works well with Cypress async.

See it in action!

happy robot

Cypress integration test example

We write Cypress tests in NodeJS and configure our browser and capabilities using a config file:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  defaultCommandTimeout: 30000,
  requestTimeout: 30000,
  viewportHeight: 800,
  viewportWidth: 800,
  videoCompression: false,
  e2e: {
    setupNodeEvents(on, config) {},
  },
})

Write your first test

Using the cy commands we can write tests that make claims about our application and then verify the results. One such test might be to sign up and login to your application and check that a welcome email is sent. The login methods might look like this:

it('can log in with confirmed account', () => {
  cy.contains('Sign in to your account');
  // fill out username (email) and password
  cy.get('[data-test="username-input"]').type(emailAddress);
  cy.get('[data-test="sign-in-password-input"]').type(password);
  // submit
  cy.get('[data-test="sign-in-sign-in-button"]').click();
});

Using email accounts in tests

You can create email inboxes on demand with throwaway email addresses using the MailSlurp cypress plugin or by adding commands ourselves to the Cypress client.

const { MailSlurp } = require('mailslurp-client');
// set your api key with an environment variable `CYPRESS_API_KEY` or configure using `env` property in config file
// (cypress prefixes environment variables with CYPRESS)
const apiKey = Cypress.env('API_KEY')
const mailslurp = new MailSlurp({ apiKey });

Cypress.Commands.add("createInbox", () => {
  return mailslurp.createInbox();
});

Cypress.Commands.add("waitForLatestEmail", (inboxId) => {
  // how long we should hold connection waiting for an email to arrive
  const timeoutMillis = 30_000;
  return mailslurp.waitForLatestEmail(inboxId, timeoutMillis)
});

Then we can use the commands in our tests to generate real email accounts and use those to sign up users:

const password = "test-password";
let inboxId;
let emailAddress;
it('can generate a new email address and sign up', () => {
  // see commands.js custom commands
  cy.createInbox().then(inbox => {
    // verify a new inbox was created
    assert.isDefined(inbox)

    // save the inboxId for later checking the emails
    inboxId = inbox.id
    emailAddress = inbox.emailAddress;

    // sign up with inbox email address and the password
    cy.get('input[name=email]').type(emailAddress);
    cy.get('input[name=password]').type(password);
    cy.get('[data-test="sign-up-create-account-button"]').click();
  });
});

Testing Email with Cypress JS and MailSlurp throwaway mail boxes

Table of contents