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.

Features

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: 'recipient@example.com', subject: 'Hello', text: 'Test message' })
  .should('have.property', 'ID');

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

Checks if there are any emails in Mailpit with the given subject. Yields a boolean value.

cy.mailpitHasEmailsBySubject('My Test').should('be.true');

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('recipient@example.com').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);
});

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

Checks if there are any emails in Mailpit sent to the given email address. Yields a boolean value.

cy.mailpitHasEmailsByTo('recipient@example.com');

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

Checks if there are emails in Mailpit with the given subject. Yields a boolean value.

cy.mailpitNotHasEmailsBySubject('My Test').should('be.true');

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

Checks if there are any emails in Mailpit sent to the given email address. Yields a boolean value.

cy.mailpitNotHasEmailsByTo('recipient@example.com');

mailpitDeleteAllEmails()

Deletes all stored mails from Mailpit.

cy.mailpitDeleteAllEmails();

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', 'sender@example.com');

mailpitGetRecipientAddress(message?)

Yields the recipient addresses of the current mail.

cy
  .mailpitGetMail()
  .mailpitGetRecipientAddress()
  .should('contain', 'recipient@example.com');

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');

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

pushpak1300/cypress-mailpit