Cypress Mailpit

This package provides a comprehensive set of Cypress commands designed specifically for interacting with Mailpit, a popular mail testing tool. This package supports TypeScript out of the box.

Table of Contents

• Features
• Setup
• Commands Reference
  • Mail Management
    • mailpitGetAllMails
    • mailpitSearchEmails
    • mailpitGetEmailsBySubject
    • mailpitGetEmailsByTo
    • mailpitGetMail
    • mailpitSendMail
    • mailpitDeleteAllEmails
    • mailpitDeleteEmailsBySearch
  • Email Assertions
    • mailpitHasEmailsBySearch
    • mailpitNotHasEmailsBySearch
    • mailpitHasEmailsBySubject
    • mailpitHasEmailsByTo
    • mailpitNotHasEmailsBySubject
    • mailpitNotHasEmailsByTo
  • Single Mail Operations
    • mailpitGetMailTextBody
    • mailpitGetMailHTMLBody
    • mailpitGetFromAddress
    • mailpitGetRecipientAddress
    • mailpitGetSubject
    • mailpitGetAttachments
    • mailpitGetMailSpamAssassinSummary
  • Email Status Management
    • mailpitSetAllEmailStatusAsRead
    • mailpitSetAllEmailStatusAsUnRead
    • mailpitSetStatusAsRead
    • mailpitSetStatusAsUnRead

Features

📨 Email Management: Get, search, send, and delete emails • Get emails by subject • Custom Mailpit URL support • TypeScript and Basic Auth integration

📝 Email Content: Access email body, subject, sender, recipients, and attachments • Spam Assassin summary analysis

📱 Status Control: Set email status (read/unread) for individual or all emails • Full status management capabilities

🚀 Coming Soon: More exciting features in development!

Setup

Install this package:

# npm
npm install --save-dev cypress-mailpit

# yarn
yarn add --dev cypress-mailpit

# pnpm
pnpm add -D cypress-mailpit

Include this package into your Cypress command file:

// cypress/support/commands
import 'cypress-mailpit';

Add the base URL of your Mailpit installation in the e2e block of your cypress.config.ts / cypress.config.js:

export default defineConfig({
  projectId: "****",
  env: {
    MAILPIT_URL: "http://localhost:8025",
  },
});

Mailpit authentication (Basic Auth)

Add MAILPIT_USERNAME and MAILPIT_PASSWORD in Cypress env config:

{
  "MAILPIT_USERNAME": "mailpit username",
  "MAILPIT_PASSWORD": "mailpit password"
}

Commands

mailpitGetAllMails(start = 0, limit = 50)

Yields an array of all the mails stored in Mailpit starting from start index up to limit.

cy.mailpitGetAllMails().then((result) => {
    expect(result).to.have.property('messages');
    expect(result.messages).to.have.length(numberOfEmails);
    expect(result.messages).to.be.an('array');
    expect(result).to.have.property('tags');
    expect(result).to.have.property('messages_count', numberOfEmails);
    expect(result).to.have.property('start');
    expect(result).to.have.property('total', numberOfEmails);
    expect(result).to.have.property('count', numberOfEmails);
    expect(result).to.have.property('unread');
});

mailpitSearchEmails(query, start = 0, limit = 50)

Searches all mails from Mailpit using the given query and yields an array of matching mails starting from start index up to limit. For more information about the query syntax, refer to the Mailpit documentation.

cy.mailpitSearchEmails('Test').then((result) => {
    expect(result).to.have.property('messages');
    expect(result.messages).to.have.length(numberOfEmails);
    expect(result.messages).to.be.an('array');
    expect(result.messages[0].Snippet).to.contain('Test');
    expect(result.messages).to.have.length(numberOfEmails);
    expect(result.messages).to.be.an('array');
    expect(result).to.have.property('messages_count', numberOfEmails);
    expect(result).to.have.property('total', 3);
    expect(result).to.have.property('count', numberOfEmails);
});

mailpitGetEmailsBySubject(subject, start = 0, limit = 50)

Fetches all mails from Mailpit with the given subject starting from start index up to limit.

cy.mailpitGetEmailsBySubject('My Test').then((result) => {
    expect(result).to.have.property('messages');
    expect(result.messages).to.have.length(numberOfEmails);
    expect(result.messages).to.be.an('array');
    expect(result).to.have.property('messages_count', numberOfEmails);
    expect(result).to.have.property('total', 2 * numberOfEmails);
    expect(result).to.have.property('count', numberOfEmails);
});

mailpitGetMail(id?)

Yields the mail with the given ID. If no ID is provided, yields the latest email.

cy.mailpitGetMail().then((result) => {
    expect(result).to.have.property('ID');
    expect(result).to.have.property('MessageID');
    expect(result).to.have.property('From');
    expect(result).to.have.property('To');
    expect(result).to.have.property('Subject');
});

mailpitSendMail(options?)

Sends an email with the given options. If no options are provided, sends a default email.

cy
  .mailpitSendMail({ to: [{ Email: '[email protected]' }], subject: 'Hello', text: 'Test message' })
  .should('have.property', 'ID');

mailpitGetEmailsByTo(email, start = 0, limit = 50)

Fetches all emails from Mailpit sent to the given email address. Yields an array of matching emails.

cy.mailpitGetEmailsBySubject('[email protected]').then((result) => {
    expect(result).to.have.property('messages');
    expect(result.messages).to.have.length(numberOfEmails);
    expect(result.messages).to.be.an('array');
    expect(result).to.have.property('messages_count', numberOfEmails);
    expect(result).to.have.property('total', 2 * numberOfEmails);
    expect(result).to.have.property('count', numberOfEmails);
});

mailpitHasEmailsBySearch(query, start = 0, limit = 50, { timeout = 10000, interval = 500 })

Checks if there are any emails in Mailpit with the given query. Automatically retries until the condition is met or timeout is reached.

cy.mailpitHasEmailsBySearch('subject:My Test');

mailpitNotHasEmailsBySearch(query, start = 0, limit = 50, { timeout = 4000, interval = 500 })

Checks if there are any emails in Mailpit with the given search query. Automatically retries until the condition is met or timeout is reached.

cy.mailpitNotHasEmailsBySearch('Subject:My Test');

mailpitHasEmailsBySubject(subject, start = 0, limit = 50, { timeout = 4000, interval = 500 })

Checks if there are any emails in Mailpit with the given subject. Automatically retries until the condition is met or timeout is reached.

cy.mailpitHasEmailsBySubject('My Test');

mailpitHasEmailsByTo(email, start = 0, limit = 50, { timeout = 4000, interval = 500 })

Checks if there are no emails in Mailpit sent to the given email address. Automatically retries until the condition is met or timeout is reached.

cy.mailpitHasEmailsByTo('[email protected]', 0, 50, { timeout: 10000, interval: 500 });

mailpitNotHasEmailsBySubject(subject, start = 0, limit = 50, { timeout = 4000, interval = 500 })

Checks if there are no emails in Mailpit with the given subject. Automatically retries until the condition is met or timeout is reached.

cy.mailpitNotHasEmailsBySubject('My Test');

mailpitNotHasEmailsByTo(email, start = 0, limit = 50, { timeout = 10000, interval = 500 })

Checks if there are any emails in Mailpit sent to the given email address. If no emails are found, the command will retry until the timeout is reached.

cy.mailpitNotHasEmailsByTo('[email protected]');

Default Values

In the MailpitCommands module, the following default values are used:

• Timeout: The default value for timeout is determined by the Cypress.config("defaultCommandTimeout"). If not specified in the options, it will fallback to this configuration.
• Interval: The default value for interval is set to 500 milliseconds if not provided in the options.

mailpitDeleteAllEmails()

Deletes all stored mails from Mailpit.

cy.mailpitDeleteAllEmails();

mailpitDeleteEmailsBySearch(query: string)

Deletes emails from the mailbox based on the search query.

cy.mailpitDeleteEmailsBySearch('subject:Test');

Handling a Single Mail

mailpitGetMailTextBody(message?)

Yields the text body of the current mail.

cy
  .mailpitGetMail()
  .mailpitGetMailTextBody()
  .should('contain', 'Message Body');

mailpitGetMailHTMlBody(message?)

Yields the HTML body of the current mail.

cy
  .mailpitGetMail()
  .mailpitGetMailHTMlBody()
  .should('contain', '<p>Message Body</p>');

mailpitGetFromAddress(message?)

Yields the sender address of the current mail.

cy
  .mailpitGetMail()
  .mailpitGetFromAddress()
  .should('eq', '[email protected]');

mailpitGetRecipientAddress(message?)

Yields the recipient addresses of the current mail.

cy
  .mailpitGetMail()
  .mailpitGetRecipientAddress()
  .should('contain', '[email protected]');

mailpitGetSubject(message?)

Yields the subject of the current mail.

cy
  .mailpitGetMail()
  .mailpitGetSubject()
  .should('eq', 'My Subject');

mailpitGetAttachments(message?)

Yields the list of all filenames of the attachments of the current mail.

cy
  .mailpitGetMail()
  .mailpitGetAttachments()
  .should('have.length', 2)
  .should('include', 'sample.pdf');

mailpitGetMailSpamAssassinSummary(message?)

Yields the SpamAssassin summary of the current mail.

cy
  .mailpitGetMail()
  .mailpitGetMailSpamAssainSummary()
  .should('have.property', 'score');

mailpitSetAllEmailStatusAsRead()

Sets the status of all emails in Mailpit to 'read'.

cy.mailpitSetAllEmailStatusAsRead();

mailpitSetAllEmailStatusAsUnRead()

Sets the status of all emails in Mailpit to 'unread'.

cy.mailpitSetAllEmailStatusAsUnRead();

mailpitSetStatusAsRead(messages)

Sets the status of specified email(s) to 'read'. Can accept a single message or an array of messages.

cy.mailpitGetMail().mailpitSetStatusAsRead();

mailpitSetStatusAsUnRead(messages)

Sets the status of specified email(s) to 'unread'. Can accept a single message or an array of messages.

cy.mailpitGetMail().mailpitSetStatusAsUnRead();

Package Development

Make sure the mailpit server is running. and set the env in cypress.config.ts

Install dependencies.

npm install

Build the package

npm run build

Run cypress tests

npm run cy:run