cypress-mailpit
v1.4.0
Published
Cypress Commands for Mailpit π
Downloads
12,964
Maintainers
Readme
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
- Email Assertions
- Single Mail Operations
- Email Status Management
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 theCypress.config("defaultCommandTimeout")
. If not specified in the options, it will fallback to this configuration. - Interval: The default value for
interval
is set to500
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