cypress-mailhog
A collection of useful Cypress commands for MailHog 🐗.
This package supports TypeScript out of the box.
Setup
Install this package:
# npm
npm install --save-dev cypress-mailhog
# yarn
yarn add --dev cypress-mailhog
# pnpm
pnpm add -D cypress-mailhogInclude this package into your Cypress command file:
// cypress/support/commands
import 'cypress-mailhog';Before cypress 10.0.0
Add the base url of your MailHog installation to your cypress.json:
{
...
"mailHogUrl": "http://localhost:8090"
}After cypress 10.0.0
Add the base url of your MailHog installation in the e2e block of your cypress.config.ts / cypress.config.js:
export default defineConfig({
projectId: "****",
env: {
mailHogUrl: "http://localhost:8090/",
},
});If your MailHog instance uses authentication, add mailHogAuth to your cypress env config:
{
...
"mailHogAuth": {"user": "mailhog username", "pass": "mailhog password"}
}or add mailHogUsername and mailHogPassword in cypress env config
{
...
"mailHogUsername": "mailhog username",
"mailHogPassword": "mailhog password"
}Commands
Mail Collection
mhGetAllMails( limit=50, options={timeout=defaultCommandTimeout} )
Yields an array of all the mails stored in MailHog. This retries automatically until mails are found (or until timeout is reached).
cy
.mhGetAllMails()
.should('have.length', 1);mhGetMailsBySubject( subject, limit=50, options={timeout=defaultCommandTimeout} )
Yields an array of all mails with given subject. This retries automatically until mails are found (or until timeout is reached).
cy
.mhGetMailsBySubject('My Subject')
.should('have.length', 1);mhGetMailsBySender( from, limit=50, options={timeout=defaultCommandTimeout} )
Yields an array of all mails with given sender. This retries automatically until mails are found (or until timeout is reached).
cy
.mhGetMailsBySender('sender@example.com')
.should('have.length', 1);mhGetMailsByRecipient( recipient, limit=50 )
Yields an array of all mails with given recipient.
cy
.mhGetMailsByRecipient('recipient@example.com')
.should('have.length', 1);mhFirst()
Yields the first mail of the loaded selection.
cy
.mhGetAllMails()
.should('have.length', 1)
.mhFirst();mhDeleteAll()
Deletes all stored mails from MailHog.
cy.mhDeleteAll();Collection Filtering 🪮
Note: the below described filter functions can be chained together to build complex filters. They are currently not automatically retrying. So make sure to either wait a certain time before fetching your mails or to implement you own re-try logic.
mhFilterBySubject( subject )
Filters the current mails in context by subject and returns the filtered mail list.
cy
.mhGetMailsBySender('sender@example.com')
.mhFilterBySubject('My Subject')
.should('have.length', 1);mhFilterByRecipient( recipient )
Filters the current mails in context by recipient and returns the filtered mail list.
cy
.mhGetMailsBySender('sender@example.com')
.mhFilterByRecipient('recipient@example.com')
.should('have.length', 1);mhFilterBySender( sender )
Filters the current mails in context by sender and returns the filtered mail list.
cy
.mhGetMailsByRecipient('recipient@example.com')
.mhFilterBySender('sender@example.com')
.should('have.length', 1);Chaining Filters
Filters can be infinitely chained together.
cy
.mhGetAllMails()
.mhFilterBySubject('My Subject')
.mhFilterByRecipient('recipient@example.com')
.mhFilterBySender('sender@example.com')
.should('have.length', 1);Handling a Single Mail ✉️
mhGetSubject()
Yields the subject of the current mail.
cy
.mhGetAllMails()
.should('have.length', 1)
.mhFirst()
.mhGetSubject()
.should('eq', 'My Mails Subject');mhGetBody()
Yields the body of the current mail.
cy
.mhGetAllMails()
.should('have.length', 1)
.mhFirst()
.mhGetBody()
.should('contain', 'Part of the Message Body');mhGetSender()
Yields the sender of the current mail.
cy
.mhGetAllMails()
.should('have.length', 1)
.mhFirst()
.mhGetSender()
.should('eq', 'sender@example.com');mhGetRecipients()
Yields the recipient of the current mail.
cy
.mhGetAllMails()
.should('have.length', 1)
.mhFirst()
.mhGetRecipients()
.should('contain', 'recipient@example.com');mhGetAttachments()
Yields the list of all file names of the attachments of the current mail.
cy
.mhGetAllMails()
.should('have.length', 1)
.mhFirst()
.mhGetAttachments()
.should('have.length', 2)
.should('include', 'sample.pdf');Asserting the Mail Collection 🔍
mhHasMailWithSubject( subject )
Asserts if there is a mail with given subject.
cy.mhHasMailWithSubject('My Subject');mhHasMailFrom( from )
Asserts if there is a mail from given sender.
cy.mhHasMailFrom('sender@example.com');mhHasMailTo( recipient )
Asserts if there is a mail to given recipient (looks for "To", "CC" and "BCC").
cy.mhHasMailTo('recipient@example.com');Helper Functions ⚙️
mhWaitForMails( moreMailsThen = 0 )
Waits until more then <moreMailsThen> mails are available on mailhog.
This is especially useful when using the mhFilterBy<X> functions, since they do not support automatic retrying.
// this waits until there are at least 10 mails on mailhog
cy
.mhWaitForMails(9)
.mhGetAllMails()
.mhFilterBySender("sender-10@example.com")
.should("have.length", 1);Jim Chaos Monkey 🐵
mhGetJimMode()
Returns if Jim is enabled / disabled.
cy
.mhGetJimMode()
.should('eq', true);mhSetJimMode( enabled )
Enables / Disables Jim chaos monkey.
cy
.mhSetJimMode(true)
.mhGetJimMode()
.should('eq', true);Package Development
Start Local Test Server
Navigate into the test-server directory.
cd ./test-server/Install dependencies.
composer install
yarn # or npm installStart docker server.
docker-compose upOpen the test page in your browser: http://localhost:3000/cypress-mh-tests/
Open MailHog in your browser: http://localhost:8090/
Open the Cypress testclient.
yarn cypress:open