{"id":13042,"library":"cypress-mailslurp","title":"Cypress MailSlurp Plugin","description":"cypress-mailslurp is the official Cypress plugin for the MailSlurp API, enabling end-to-end testing of email and SMS workflows directly within Cypress. It allows developers to create unlimited, disposable email addresses, send and receive emails, and read SMS messages for testing purposes. Key features include extracting verification codes, magic links, and handling attachments. The current stable version is 1.11.1, indicating a mature and actively maintained library. While no explicit release cadence is stated, the project appears to be regularly updated based on version history. This plugin differentiates itself by providing a seamless integration with Cypress, abstracting away direct MailSlurp API calls into `cy.mailslurp()` commands, simplifying complex email/SMS test scenarios compared to integrating the MailSlurp client library manually. It's designed to make testing user registration, password resets, and two-factor authentication flows straightforward.","status":"active","version":"1.11.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install cypress-mailslurp","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-mailslurp","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-mailslurp","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a Cypress plugin and requires Cypress to be installed and configured in the project.","package":"cypress","optional":false},{"reason":"The 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.","package":"mailslurp-client","optional":false}],"imports":[{"note":"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).","wrong":"require('cypress-mailslurp');","symbol":"MailSlurp Cypress Commands","correct":"import 'cypress-mailslurp';"},{"note":"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.","wrong":"const mailslurp = cy.mailslurp();","symbol":"cy.mailslurp()","correct":"cy.mailslurp().then((mailslurp) => { /* use mailslurp instance */ });"},{"note":"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()`.","symbol":"MailSlurpInbox","correct":"import { Inbox } from 'mailslurp-client';"}],"quickstart":{"code":"import 'cypress-mailslurp';\n\ndescribe('MailSlurp E2E Test', () => {\n  let inboxId: string;\n  let emailAddress: string;\n  let verificationCode: string;\n\n  before(() => {\n    // Ensure your MailSlurp API key is set as an environment variable (e.g., CYPRESS_MAILSLURP_API_KEY)\n    if (!Cypress.env('MAILSLURP_API_KEY')) {\n      throw new Error('CYPRESS_MAILSLURP_API_KEY environment variable is not set.');\n    }\n  });\n\n  it('should allow a user to sign up and verify via email', function () {\n    cy.mailslurp().then((mailslurp) => {\n      cy.visit('https://playground.mailslurp.com'); // Replace with your app's signup page\n      cy.then(() => mailslurp.createInbox()).then((inbox) => {\n        inboxId = inbox.id;\n        emailAddress = inbox.emailAddress;\n      });\n\n      cy.get('[data-test=sign-in-create-account-link]').click();\n      cy.then(() => {\n        cy.get('[name=email]').type(emailAddress);\n        cy.get('[name=password]').type('Test1234!');\n        cy.get('[data-test=sign-up-create-account-button]').click();\n      });\n\n      cy.then(\n        { timeout: 60000 },\n        () => {\n          return mailslurp\n            .waitForLatestEmail(inboxId, 60000, true)\n            .then((email) =>\n              mailslurp.emailController.getEmailContentMatch({\n                emailId: email.id,\n                contentMatchOptions: {\n                  pattern: 'Your Demo verification code is ([0-9]{6})'\n                }\n              })\n            )\n            .then(({ matches }) => {\n              verificationCode = matches[1];\n            });\n        }\n      );\n\n      cy.then(() => {\n        cy.get('[name=code]').type(verificationCode);\n        cy.get('[data-test=confirm-sign-up-confirm-button]').click();\n        cy.get('[data-test=username-input]').type(emailAddress);\n        cy.get('[data-test=sign-in-password-input]').type('Test1234!');\n        cy.get('[data-test=sign-in-sign-in-button]').click();\n      });\n      cy.get('h1').should('contain', 'Welcome');\n    });\n  });\n});\n","lang":"typescript","description":"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`."},"warnings":[{"fix":"Replace `it('test', () => { ... })` with `it('test', function () { ... })` and `cy.then(() => { ... })` with `cy.then(function () { ... })` when `this` context is needed.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `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`.","message":"MailSlurp 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For 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`.","message":"Older 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`.","severity":"breaking","affected_versions":">=1.0.0, <10.0 (Cypress versions)"},{"fix":"Increase 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.","message":"Network 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `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.","cause":"The `cypress-mailslurp` plugin was not correctly imported and registered with Cypress.","error":"Cypress command `mailslurp` is not a function"},{"fix":"Always chain `cy.mailslurp()` with `.then((mailslurp) => { /* use mailslurp */ })` to ensure the client is available asynchronously.","cause":"The MailSlurp client instance (returned by `cy.mailslurp()`) was not accessed correctly, likely due to synchronous assignment or incorrect chaining.","error":"TypeError: Cannot read properties of undefined (reading 'createInbox')"},{"fix":"Set `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`.","cause":"The MailSlurp API key was not provided or correctly configured as a Cypress environment variable.","error":"MailSlurpClientError: You must provide an API key to access MailSlurp. Get one at mailslurp.com."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}