Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MailSlurp Cypress Commands
✓ import 'cypress-mailslurp';
✗ require('cypress-mailslurp');
This import registers the `cy.mailslurp()` custom command and other MailSlurp-related utilities with Cypress. It should be added to `cypress/support/e2e.js` or `cypress/support/index.js` (for older Cypress versions).
cy.mailslurp()
✓ cy.mailslurp().then((mailslurp) => { /* use mailslurp instance */ });
✗ const mailslurp = cy.mailslurp();
The `cy.mailslurp()` command is an asynchronous Cypress command and must be chained with `.then()` to access the MailSlurp client instance. It cannot be assigned directly like a synchronous function.
MailSlurpInbox
✓ import { Inbox } from 'mailslurp-client';
While `cypress-mailslurp` provides the commands, for direct type usage or advanced scenarios, you might need to import types from `mailslurp-client` directly, as `cypress-mailslurp` re-exports minimal types. `Inbox` is a common type used when interacting with `createInbox()`.
This quickstart demonstrates a complete user registration and email verification flow in Cypress using MailSlurp. It creates a disposable inbox, signs up a user, waits for a verification email, extracts the code, confirms the account, and then logs in to verify success. Requires `CYPRESS_MAILSLURP_API_KEY`.
import 'cypress-mailslurp';
describe('MailSlurp E2E Test', () => {
let inboxId: string;
let emailAddress: string;
let verificationCode: string;
before(() => {
// Ensure your MailSlurp API key is set as an environment variable (e.g., CYPRESS_MAILSLURP_API_KEY)
if (!Cypress.env('MAILSLURP_API_KEY')) {
throw new Error('CYPRESS_MAILSLURP_API_KEY environment variable is not set.');
}
});
it('should allow a user to sign up and verify via email', function () {
cy.mailslurp().then((mailslurp) => {
cy.visit('https://playground.mailslurp.com'); // Replace with your app's signup page
cy.then(() => mailslurp.createInbox()).then((inbox) => {
inboxId = inbox.id;
emailAddress = inbox.emailAddress;
});
cy.get('[data-test=sign-in-create-account-link]').click();
cy.then(() => {
cy.get('[name=email]').type(emailAddress);
cy.get('[name=password]').type('Test1234!');
cy.get('[data-test=sign-up-create-account-button]').click();
});
cy.then(
{ timeout: 60000 },
() => {
return mailslurp
.waitForLatestEmail(inboxId, 60000, true)
.then((email) =>
mailslurp.emailController.getEmailContentMatch({
emailId: email.id,
contentMatchOptions: {
pattern: 'Your Demo verification code is ([0-9]{6})'
}
})
)
.then(({ matches }) => {
verificationCode = matches[1];
});
}
);
cy.then(() => {
cy.get('[name=code]').type(verificationCode);
cy.get('[data-test=confirm-sign-up-confirm-button]').click();
cy.get('[data-test=username-input]').type(emailAddress);
cy.get('[data-test=sign-in-password-input]').type('Test1234!');
cy.get('[data-test=sign-in-sign-in-button]').click();
});
cy.get('h1').should('contain', 'Welcome');
});
});
});
Debug
Known issues
gotchaWhen using `this.propertyName` to access values set with `cy.wrap().as()`, ensure you use a traditional `function()` syntax for your `it` or `then` blocks, not an arrow function `() => {}`. Arrow functions lexically bind `this`, preventing access to the Cypress context.fixReplace `it('test', () => { ... })` with `it('test', function () { ... })` and `cy.then(() => { ... })` with `cy.then(function () { ... })` when `this` context is needed. affects: >=1.0.0
gotchaMailSlurp API key must be configured as a Cypress environment variable (e.g., `CYPRESS_MAILSLURP_API_KEY`). Without this, `cy.mailslurp()` will fail to initialize the client.fixSet `CYPRESS_MAILSLURP_API_KEY` in your `cypress.config.js` or `cypress.env.json`, or pass it via command line `cypress run --env MAILSLURP_API_KEY=YOUR_KEY`.
affects: >=1.0.0
breakingOlder versions of Cypress (before 10.0) used `cypress/support/index.js` for support file inclusion. Newer versions (Cypress 10+) typically use `cypress/support/e2e.js` or `cypress/support/component.js`.fixFor Cypress 10+, ensure `import 'cypress-mailslurp';` is in `cypress/support/e2e.js` or the appropriate support file. For older versions, place it in `cypress/support/index.js`.
affects: >=1.0.0, <10.0 (Cypress versions)
gotchaNetwork requests to the MailSlurp API (e.g., `createInbox`, `waitForLatestEmail`) are asynchronous and can sometimes exceed default Cypress command timeouts, especially `waitForLatestEmail` which polls for an email. Long polling can lead to test failures if not accounted for.fixIncrease the timeout for specific Cypress commands or blocks using `{ timeout: 60000 }` (or higher) as an option to the Cypress command or `cy.then()` block where MailSlurp operations occur. affects: >=1.0.0
Errors
Common errors & fixes
Cypress command `mailslurp` is not a function
The `cypress-mailslurp` plugin was not correctly imported and registered with Cypress.
fixAdd `import 'cypress-mailslurp';` to your Cypress support file (e.g., `cypress/support/e2e.js` or `cypress/support/index.js`). Ensure the file is included in your Cypress configuration.
TypeError: Cannot read properties of undefined (reading 'createInbox')
The MailSlurp client instance (returned by `cy.mailslurp()`) was not accessed correctly, likely due to synchronous assignment or incorrect chaining.
fixAlways chain `cy.mailslurp()` with `.then((mailslurp) => { /* use mailslurp */ })` to ensure the client is available asynchronously. MailSlurpClientError: You must provide an API key to access MailSlurp. Get one at mailslurp.com.
The MailSlurp API key was not provided or correctly configured as a Cypress environment variable.
fixSet `CYPRESS_MAILSLURP_API_KEY` in your `cypress.config.js` or `cypress.env.json`, or pass it via command line `cypress run --env MAILSLURP_API_KEY=YOUR_KEY`.
Audit
Dependencies
cypressrequiredThis is a Cypress plugin and requires Cypress to be installed and configured in the project.
mailslurp-clientrequiredThe plugin wraps the MailSlurp client library for API interactions. While not a direct runtime dependency you install, it's an underlying dependency for the plugin's functionality.