Emails testing with Cypress

5 min readMar 14, 2024

Welcome to the guide about testing incoming emails with Cypress. In this guide we will learn how to:

Install Cypress
Install ProxiedMail plugin
Launch opening website + receiving sign-up email test

This will allow you to easily pass the email subject and body of the email to your test, also extract the code, and put it into your verification form.

Cypress JS

Cypress is an amazing end-to-end testing framework. It’s popular, bundles its own chrome browser and is easily extended. Cypress lets you test many parts of a website or web application with a browser in an automated way. It’s like Selenium but a lot more user-friendly. To get started create a new test folder and run npm init -y to create a new NodeJS project. This will create a node modules folder and package.json for further steps.

Installing Cypress

When installing Cypress simple run npm install --save cypress in the command line and then run npx cypress open to open the Cypress app. A Cypress welcome window will show that allows you to configure the browser you wish to use and scaffold a basic test file.

Testing with real email addresses

Numerous applications rely on email for account creation and login processes. Conducting login tests with Cypress is straightforward when employing a specific test user. However, the challenge arises with new account sign-ups.

The capability to sign up via email is crucial for any application, and conducting comprehensive end-to-end tests becomes challenging without the ability to use unique and private email addresses.

Fortunately, ProxiedMail offers a solution. This complimentary API enables the creation of genuine, randomized email addresses instantly. Moreover, it provides the functionality to programmatically send and receive emails, making it ideal for thoroughly testing user registration processes.

Install ProxiedMail plugin

So, it’s time to learn how to install ProxiedMail plugin for email testing.

ProxiedMail plugin destributes as cypress-test-email package. It provides the following features:

Creating a new email address
Receiving letter contents that were sent to generated emails
Receiving subject, body, html, headers of email

To install the plugin run the following command from your project location:

npm install --save-dev cypress-test-email

You can also visit Github repository of the plugin the see more details.

Plugin Configuration

It’s necessary to specify your API token in PROXIEDMAIL_API_KEY.

You can configure this plugin by putting to env variable PROXIEDMAIL_API_KEY to cypress.config.js.

const { defineConfig } = require("cypress");

module.exports = defineConfig({
    "env": {
        "PROXIEDMAIL_API_KEY": "YOUR API KEY"
    },
    e2e: {
        setupNodeEvents(on, config) {
            // implement node event listeners here
        },
    },
});

You can also pass the variable in a command line:

PROXIEDMAIL_API_KEY=your-api-key cypress run

Obtaining API key

You can obtain the API key by signing up on ProxiedMail. Basic usage of the product is free up to 10 mailboxes + some API limits. If you want to get the best result please think about upgrading your account.

See pricing on ProxiedMail

Timeouts

ProxiedMail requires timeouts to get your emails. Please adjust the timings where you have the email testings up to 10s (1000ms).

Calling custom commands

createProxyEmail

        cy.then(
            () => {
                return new Promise(resolve => {
                    proxiedmail.createProxyEmail(proxyEmail => {
                        resolve(proxyEmail)
                    })
                })
    })

getReceivedEmails

        cy.then(() => {
            return new Promise(resolve => {
                const interval = setInterval(() => {
                    proxiedmail.getReceivedEmails(global.proxyEmailId, (resp) => {
                        if (resp.data.length > 0) {
                            resp.data[0].getDetails(function (details) {
                                clearInterval(interval);
                                resolve(details)
                            })
                        }
                    })
                }, 3000);
                return interval;
            })
        },
        {
            timeout: 10000
        }
    ).then(details => {
        expect(details.getSubject()).to.equal('Please confirm your email on ProxiedMail')
        expect(details.getPayloadBodyHtml()).to.have.string(
            'please confirm that you want to receive messages by clicking'
        );
    });

Writing a test

Let’s start simple and write a test to load the ProxiedMail app in Cypress.

That would look a little like this:

it('can load oauth demo site', () => {
  cy.visit('https://proxiedmail.com');
  cy.contains('Sign in to your account');
});

Next we want to click a sign up button to begin the sign up process.

it('can click sign up link', () => {
  cy.get('[data-test="sign-in-create-account-link"]').click();
  cy.contains('Testable Sign Up Form');
});

Running tests

To run the test run PROXIEDMAIL_API_KEY=your-api-key npx cypress run.

Cypress will open:

Testing with emails in Cypress

After we have prepared everything let’s write the test that allows us to test that after signing up we’re going to receive the confirmation code email. It plays a critical role in our business, so we want to make sure that everything works correctly.

In this example, we’re going to test the sign-up on the ProxiedMail website and email receiving afterwards. It’s crucial to test the email validity.

describe('template spec', () => {
  it('testing email', {
    defaultCommandTimeout: 10000,
  }, () => {

    cy.proxiedmail().then((proxiedmail) => {

      cy.visit('https://proxiedmail.com')
      cy.get('.nav_li').contains('Sign up').click()
      cy.url().should('include', '/en/signup')


      cy.then(
          () => {
            return new Promise(resolve => {
              proxiedmail.createProxyEmail(proxyEmail => {
                resolve(proxyEmail)
              })
            })
      }).then((proxyEmail)  => {
        cy.wrap(proxyEmail.getId()).as('proxyEmailId')
        cy.wrap(proxyEmail.getProxyEmail()).as('emailAddress')
      })


      Cypress.on('uncaught:exception', (err, runnable) => {
        // returning false here prevents Cypress from
        // failing the test
        return false
      })


      cy.then(function () {
        global.proxyEmailId = this.proxyEmailId
        cy.get('#login').type(this.emailAddress)
        cy.get('#password').type('123456')
        return cy.get('#proceed').click()
      })



      cy.then(() => {
        return new Promise(resolve => {
              const interval = setInterval(() => {
                proxiedmail.getReceivedEmails(global.proxyEmailId, (resp) => {
                  if (resp.data.length > 0) {
                    resp.data[0].getDetails(function (details) {
                      clearInterval(interval);
                      resolve(details)
                    })
                  }
              })}, 3000);
              return interval;
            })
          },
          {
            timeout: 10000
          }
      ).then(details => {
        expect(details.getSubject()).to.equal('Please confirm your email on ProxiedMail')
        expect(details.getPayloadBodyHtml()).to.have.string(
            'please confirm that you want to receive messages by clicking'
        );
      });
    });
  })
})

Conclusion

You’ve mastered email testing in Cypress through the ProxiedMail plugin. ProxiedMail enables the generation of unlimited email addresses, allowing you to thoroughly test your application. It features webhook functionality and a method for browsing received emails.

Additionally, for the sake of your privacy, I recommend considering ProxiedMail for both personal and business purposes.

Should you have any inquiries, feel free to reach out to us at pmjshelp@pxdmail.com.