How to test that an email is received using Cypress JS.

Use Cypress JS to test emails are received and validated during end-to-end testing.

Cypress JS is a powerful browser testing tool, like Selenium and Playwright, that can be used to test applications end to end. But did you know it can also test email received events that take place during application sign up and login? In this post we will demonstrate how to setup Cypress automated email testing in your test suite and how to use it when testing application sign up and login.

What is Cypress JS?

CypressJS is a popular browser automation tool that can be used to test web apps end-to-end. Most web-apps send emails containing OTP/one time passwords allow users to sign-up and log into an application. We can use a free email testing platform like MailSlurp to create disposable test email accounts during testing and receive emails in code and verify their results or extract login codes.

Email testing setup

In order to test email received actions with Cypress we should generate throwaway email accounts during each test run and then wait for the email to arrive. For this we can use MailSlurp's free plans with the Cypress email plugin. Let's see how it all fits together with an example.

Example email testing scenario

Say we have an application that allows users to create an account using a form. This form requires the user verify their email address by receiving a code and entered it into the form. This code is an OTP one-time password in a way and verifies a user's email address by sending a random code to the user that must be presented back to the server.

Create a new NodeJS project

CypressJS is a Node package so we can install CypressJS and MailSlurp like so:

npm install --save cypress cypress-mailslurp

Your package.json should look something like this:

{
  "name": "javascript-cypress-mailslurp-plugin",
  "version": "1.0.0",
  "description": "Example cypress-mailslurp plugin usage",
  "scripts": {
    "test": "cypress run",
    "dev": "cypress open"
  },
  "author": "",
  "license": "MIT",
  "dependencies": {
    "cypress": "^10.5.0",
    "cypress-mailslurp": "^1.5.0",
    "typescript": "^4.4.4"
  },
  "devDependencies": {
    "debug": "^4.3.2"
  }
}

Next we need to configure the plugin with our MailSlurp API Key. This allows us to authenticate with the MailSlurp mailserver when creating inboxes.

Environment variable

You can configure the api key in Mac/Linux environments using the CYPRESS_MAILSLURP_API_KEY environment variable.

CYPRESS_MAILSLURP_API_KEY=your-api-key cypress run

For Windows environments:

$env:CYPRESS_MAILSLURP_API_KEY=your-api-key; cypress run;

Create email addresses during testing

To create an email address for each test use the MailSlurp plugin createInbox method:

// use cypress-mailslurp plugin to create an email address before test
before(function () {
    cy.log("Wrap inbox before test")
    return cy.mailslurp()
        .then(mailslurp => mailslurp.createInbox())
        .then(inbox => {
            cy.log(`Inbox id ${inbox.id}`)
            // save inbox id and email address to this (make sure you use function and not arrow syntax)
            cy.wrap(inbox.id).as('inboxId')
            cy.wrap(inbox.emailAddress).as('emailAddress')
        })
});

Filling a form

Say we have an application with a form like this:

cypress forms

We can load the application using Cypress using code below:

// use function instead of arrow syntax to access aliased values on this
it("02 - can sign up using email address", function () {
    // click sign up and fill out the form
    cy.get("[data-test=sign-in-create-account-link]").click()
    // use the email address and a test password
    cy.get("[name=email]").type(this.emailAddress).trigger('change');
    cy.get("[name=password]").type('test-password').trigger('change');
    // click the submit button
    cy.get("[data-test=sign-up-create-account-button]").click();
});

Receiving emails in code

To test email received events in CypressJS use the wait for methods like so:

it("03 - can receive confirmation code by email", function () {
    // app will send user an email containing a code, use mailslurp to wait for the latest email
    cy.mailslurp()
        // use inbox id and a timeout of 30 seconds
        .then(mailslurp => mailslurp.waitForLatestEmail(this.inboxId, 30000, true))
        // extract the confirmation code from the email body
        .then(email => /.*verification code is (\d{6}).*/.exec(email.body!!)!![1])
        // fill out the confirmation form and submit
        .then(code => {
            cy.get("[name=code]").type(code).trigger('change');
            cy.get("[data-test=confirm-sign-up-confirm-button]").click();
        })
});

More examples

There are many ways to configure and test if an email is received in CypressJs using MailSlurp. Check out the following links for more information: