Testing email with Cypress
Learn how to automate email testing with Cypress and Mailosaur
Before you start
If you don’t already have one, create a Mailosaur account.
Make sure you know how to send email to Mailosaur first. Once you have this working, you’re ready to start testing!
Installing Mailosaur
Extend Cypress, by installing Mailosaur’s custom commands package cypress-mailosaur.
Install cypress-mailosaur via npm
:
cd your/project/path
npm install cypress-mailosaur --save-dev
Register the commands by appending an import
statement to the cypress/support/commands.js
file, within your project folder:
echo "import 'cypress-mailosaur'" >> cypress/support/commands.js
Authenticating with Mailosaur
In order to connect to Mailosaur, you need to add your API key to your tests. You access your API key via the account settings screen.
Option 1: Add API key to cypress.json
{
"env": {
"MAILOSAUR_API_KEY": "your-key-here"
}
}
Option 2: Add API key to a cypress.env.json
file
You can create your own cypress.env.json
file that Cypress will automatically check. This is useful because if you add cypress.env.json
to your .gitignore
file, the values in here can be different for each developer machine.
{
"MAILOSAUR_API_KEY": "your-key-here"
}
Option 3: Set API key via a system environment variable
To set the environment variable on your machine, it needs to be prefixed with either CYPRESS_
or cypress_
.
export CYPRESS_MAILOSAUR_API_KEY=your-key-here
Send and fetch an email
In this example, we’ll navigate to a password reset page, request a new password link (sent via email) and get that email.
touch cypress/integration/password-reset.spec.js
Now edit the file to something like this:
describe('Password reset', () => {
const serverId = 'SERVER_ID'; // Replace SERVER_ID with an actual Mailosaur Server ID
const testEmail = `something@${serverId}.mailosaur.net`
it('Makes a Password Reset request', () => {
cy.visit('https://github.com/password_reset')
cy.title().should('equal', 'Forgot your password?')
cy.get('#email_field').type(testEmail)
})
it('Gets a Password Reset email', () => {
cy.mailosaurGetMessage(serverId, {
sentTo: testEmail
}).then(email => {
expect(email.subject).to.equal('Reset your password');
})
})
})
Gotcha! receivedAfter
By default, the mailosaurGetMessage
command only looks for emails that were received by Mailosaur within the last hour.
You can override this, by adding the receivedAfter
option, like so:
cy.mailosaurGetMessage(serverId, {
sentTo: testEmail
}, {
// Find messages received since Jan 1st 2020. This will be slow!
receivedAfter: new Date('2020-01-01T00:00:00Z')
})
Follow a link in the email
Now that we have our password reset email, we want to navigate to the link within it, just like an end user would:
describe('Password reset', () => {
const serverId = 'SERVER_ID'; // Replace SERVER_ID with an actual Mailosaur Server ID
const testEmail = `something@${serverId}.mailosaur.net`
let passwordResetLink;
it('Makes a Password Reset request', () => {
cy.visit('https://github.com/password_reset')
cy.title().should('contain', 'Forgot your password?')
cy.get('#email_field').type(testEmail)
cy.get('form').submit()
})
it('Gets a Password Reset email', () => {
cy.mailosaurGetMessage(serverId, {
sentTo: testEmail
}).then(email => {
expect(email.subject).to.contain('reset your password');
passwordResetLink = email.text.links[0].href;
})
})
it('Follows the link from the email', () => {
const validPassword = 'delighted cheese jolly cloud'
cy.visit(passwordResetLink)
cy.title().should('contain', 'Change your password')
cy.get('#password').type(validPassword)
cy.get('#password_confirmation').type(validPassword)
cy.get('form').submit()
})
})