Email Cypress Test Report

Sometimes you run the Cypress end-to-end tests on CI and want to be notified quickly if something has failed. Most CIs can be configured to send you an email on test job failure, but they do not send detailed information about what has failed. In this blog post, I will show my simple cypress-email-results plugin that can send an email after each Cypress run.

Important: this plugin only sends the test results from the current Cypress instance. If you are using Cypress parallelization then each test runner will send its portion of the results.

Install and use

I will install the plugin in the bahmutov/chat.io repo where I am testing a Chat application. The plugin is an NPM module that I install as a dev dependency.

$ npm i -D cypress-email-results
+ [email protected]

In the Cypress plugins file, let's send an email after a failed test run (by default, the plugin sends an email after each run)

cypress/plugins/index.js

module.exports = (on, config) => {
  // https://github.com/bahmutov/cypress-email-results
  // only configure the email plugin if the environment variable is set
  if (process.env.EMAIL_TO) {
    require('cypress-email-results')(on, config, {
      email: process.env.EMAIL_TO,
      emailOnSuccess: false,
    })
  }
  ...
}

CI configuration

For my needs I have configured a SendGrid account, but you can pass any email transport module as an option

require('cypress-email-results')(on, config, {
  email: process.env.EMAIL_TO,
  // use your own email sender
  transport: { sendEmail ... }
})

Because I am using SendGrid, I need to pass the API key with the permission "Mail Send"

SENDGRID_HOST=smtp.sendgrid.net
SENDGRID_PORT=465
SENDGRID_USER=apikey
SENDGRID_PASSWORD=... the api key ...
SENDGRID_FROM=email address

I will pass the on GitHub Actions I set config values as secrets

On GitHub Actions I need to explicitly pass the secrets as environment variables when running the Cypress GitHub Action

.github/workflows/ci.yml

# https://github.com/cypress-io/github-action
- name: Cypress tests 🧪
  uses: cypress-io/github-action@v2
  with:
    start: npm start
  env:
    # email test results after the tests are finished
    EMAIL_TO: ${{ secrets.EMAIL_TO }}
    # pass SendGrid settings to the plugin via environment variables
    SENDGRID_HOST: ${{ secrets.SENDGRID_HOST }}
    SENDGRID_PORT: ${{ secrets.SENDGRID_PORT }}
    SENDGRID_USER: ${{ secrets.SENDGRID_USER }}
    SENDGRID_PASSWORD: ${{ secrets.SENDGRID_PASSWORD }}
    SENDGRID_FROM: ${{ secrets.SENDGRID_FROM }}

Let's push the code and let the CI run. We see the "results emailed" message at the end of the run.

The received email has all the information, including the Cypress Dashboard URL (via SendGrid redirect)

Nice.

Tip: to learn about Cypress test statuses like "pending" and "skipped", read the blog post Cypress Test Statuses.