cypress-mailhog v2.3.0
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-mailhog
Include 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 install
Start docker server.
docker-compose up
Open 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