Cypress Commands for Mailpit š
npm install 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.
šØ 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!
Install this package:
``bashnpm
npm install --save-dev cypress-mailpit
Include this package into your Cypress command file:
JavaScript
// cypress/support/commands
import 'cypress-mailpit';
`Add the base URL of your Mailpit installation in the
block of your cypress.config.ts / cypress.config.js:`typescript
export default defineConfig({
projectId: "**",
env: {
MAILPIT_URL: "http://localhost:8025/",
},
});
`$3
Add
and MAILPIT_PASSWORD in Cypress env config:`json
{
"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
index up to limit.`JavaScript
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
index up to limit.
For more information about the query syntax, refer to the Mailpit documentation.`JavaScript
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
index up to limit.`JavaScript
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.
JavaScript
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.
JavaScript
cy
.mailpitSendMail({ to: [{ Email: 'recipient@example.com' }], 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.
JavaScriptcy.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);
});
`#### 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.
JavaScript
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.
JavaScript
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.
JavaScript
cy.mailpitHasEmailsBySubject('My Test');
`$3
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.JavaScript
cy.mailpitHasEmailsByTo('recipient@example.com', 0, 50, { timeout: 10000, interval: 500 });
`$3
Checks if there are no emails in Mailpit with the given subject.
Automatically retries until the condition is met or timeout is reached.JavaScript
cy.mailpitNotHasEmailsBySubject('My Test');
`
$3
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.JavaScript
cy.mailpitNotHasEmailsByTo('recipient@example.com');
`
Default Values
In the
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.
`JavaScript
cy.mailpitDeleteAllEmails();
`#### mailpitDeleteEmailsBySearch(query: string)
Deletes emails from the mailbox based on the search query.
JavaScript
cy.mailpitDeleteEmailsBySearch('subject:Test');
`
$3
#### mailpitGetMailTextBody(message?)
Yields the text body of the current mail.
JavaScript
cy
.mailpitGetMail()
.mailpitGetMailTextBody()
.should('contain', 'Message Body');
`#### mailpitGetMailHTMlBody(message?)
Yields the HTML body of the current mail.
JavaScript
cy
.mailpitGetMail()
.mailpitGetMailHTMlBody()
.should('contain', 'Message Body
');
`#### mailpitGetFromAddress(message?)
Yields the sender address of the current mail.
JavaScript
cy
.mailpitGetMail()
.mailpitGetFromAddress()
.should('eq', 'sender@example.com');
`#### mailpitGetRecipientAddress(message?)
Yields the recipient addresses of the current mail.
JavaScript
cy
.mailpitGetMail()
.mailpitGetRecipientAddress()
.should('contain', 'recipient@example.com');
`#### mailpitGetSubject(message?)
Yields the subject of the current mail.
JavaScript
cy
.mailpitGetMail()
.mailpitGetSubject()
.should('eq', 'My Subject');
`#### mailpitGetAttachments(message?)
Yields the list of all filenames of the attachments of the current mail.
JavaScript
cy
.mailpitGetMail()
.mailpitGetAttachments()
.should('have.length', 2)
.should('include', 'sample.pdf');
`#### mailpitGetMailSpamAssassinSummary(message?)
Yields the SpamAssassin summary of the current mail.
JavaScript
cy
.mailpitGetMail()
.mailpitGetMailSpamAssainSummary()
.should('have.property', 'score');
`#### mailpitSetAllEmailStatusAsRead()
Sets the status of all emails in Mailpit to 'read'.
JavaScript
cy.mailpitSetAllEmailStatusAsRead();
`#### mailpitSetAllEmailStatusAsUnRead()
Sets the status of all emails in Mailpit to 'unread'.
JavaScript
cy.mailpitSetAllEmailStatusAsUnRead();
`#### mailpitSetStatusAsRead(messages)
Sets the status of specified email(s) to 'read'. Can accept a single message or an array of messages.
JavaScript
cy.mailpitGetMail().mailpitSetStatusAsRead();
`#### mailpitSetStatusAsUnRead(messages)
Sets the status of specified email(s) to 'unread'. Can accept a single message or an array of messages.
JavaScript
cy.mailpitGetMail().mailpitSetStatusAsUnRead();
`Package Development
Make sure the mailpit server is running. and set the env in
Install dependencies.
bash
npm install
`Build the package
bash
npm run build
`Run cypress tests
bash
npm run cy:run
``