cypress-mailhog
v2.5.0
Published
Cypress Commands for MailHog ๐ณ๐
Downloads
73,074
Maintainers
Readme
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';
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/",
},
});
MailHog authentication (Basic Auth)
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} )
Fetches all mails from MailHog and 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} )
Fetches all mails from MailHog and yields an array of all mails with given sender. This retries automatically until mails are found (or until timeout is reached).
cy
.mhGetMailsBySender('[email protected]')
.should('have.length', 1);
mhGetMailsByRecipient( recipient, limit=50 )
Fetches all mails from MailHog and yields an array of all mails with given recipient.
cy
.mhGetMailsByRecipient('[email protected]')
.should('have.length', 1);
mhFirst()
Yields the first mail of the loaded selection.
cy
.mhGetAllMails()
.should('have.length', 1)
.mhFirst();
mhDeleteAll(options={timeout=requestTimeout})
Deletes all stored mails from MailHog.
cy.mhDeleteAll();
Mail Searching
mhSearchMails( kind, query, limit=50, options={timeout=defaultCommandTimeout} )
Yields an array of mails matching the search query. This retries automatically until mails are found (or until timeout is reached).
Possible search kinds are from
(sender), to
(recipient) or containing
(subject).
cy
.mhSearchMails('containing', 'My favorite subject')
.should('have.length', 1)
.mhFirst();
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('[email protected]')
.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('[email protected]')
.mhFilterByRecipient('[email protected]')
.should('have.length', 1);
mhFilterBySender( sender )
Filters the current mails in context by sender and returns the filtered mail list.
cy
.mhGetMailsByRecipient('[email protected]')
.mhFilterBySender('[email protected]')
.should('have.length', 1);
Chaining Filters
Filters can be infinitely chained together.
cy
.mhGetAllMails()
.mhFilterBySubject('My Subject')
.mhFilterByRecipient('[email protected]')
.mhFilterBySender('[email protected]')
.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', '[email protected]');
mhGetRecipients()
Yields the recipient of the current mail.
cy
.mhGetAllMails()
.should('have.length', 1)
.mhFirst()
.mhGetRecipients()
.should('contain', '[email protected]');
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('[email protected]');
mhHasMailTo( recipient )
Asserts if there is a mail to given recipient (looks for "To", "CC" and "BCC").
cy.mhHasMailTo('[email protected]');
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("[email protected]")
.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