MailSlurp logo

guides

Cypress Email Testing Guide for Signup, OTP, and Reset Flows

Learn Cypress email testing with MailSlurp for account verification, OTP codes, and password reset assertions in CI pipelines.

View MarkdownAgent setup

Cypress testing

Cypress is a strong fit for end-to-end browser tests where email is part of the workflow. MailSlurp adds real inbox control so your tests can assert links, codes, and content instead of mocking email delivery.

Start with the canonical Cypress email testing guide for the subject-matched, per-test workflow. For a longer plugin walkthrough with screenshots and video, see the in-depth Cypress tutorial.

What to test with Cypress and MailSlurp

Use the combo for high-value user flows:

  • New-user signup and confirmation links
  • Password reset links and expiry behavior
  • OTP and MFA code delivery
  • Invitation and magic-link authentication
  • Transactional notifications that must be rendered correctly

Why teams use this pattern

Compared with static fixtures, real inbox testing catches classes of failures your UI suite alone misses:

  • Misconfigured sender/authentication settings
  • Broken links in generated templates
  • Delayed delivery and retry edge cases
  • Environment routing mistakes (staging vs production)

Cypress vs Selenium

Cypress and Selenium solve similar E2E goals with different mechanics:

  • Cypress: browser-first DX, fast local feedback, strong frontend developer ergonomics.
  • Selenium: broad browser/grid compatibility and enterprise test-grid integrations.

Both can work with MailSlurp; choose based on your team's runtime and tooling constraints.

Setup

Install Cypress and the official MailSlurp plugin:

npm install --save-dev cypress cypress-mailslurp

Import the plugin in cypress/support/e2e.ts:

import "cypress-mailslurp";

The plugin adds cy.mailslurp(), which returns the standard MailSlurp client. Use its waitController.waitForMatchingFirstEmail method with a subject, sender, or run-token rule instead of selecting whichever message happens to be latest.

Use environment variables for API keys in local and CI runs. Do not hardcode credentials in spec files.

A reliable email E2E test usually follows this sequence:

  1. Create inbox at test start.
  2. Perform browser action that triggers an email.
  3. Wait for a subject- or token-matched message with a bounded timeout.
  4. Assert subject, sender, and body content.
  5. Extract and visit confirmation/reset links.
  6. Delete the inbox in afterEach, including after failed assertions.

This gives you both UI confidence and mail-delivery confidence in one test pass.

CI reliability practices

To reduce flaky Cypress email tests:

  • Use dedicated inbox per test worker.
  • Add explicit wait windows and message-matching rules for asynchronous delivery.
  • Assert minimal required content first, then deep checks.
  • Keep retries targeted (not globally masking failures).
  • Capture inbox and message IDs with failed-run evidence for fast triage.
  • Never reuse a shared Gmail inbox or suite-wide alias across parallel workers.