nightwatch-mailtrap
v1.0.6
Published
Nightwatch plugin adding custom assertions for e2e email test scenarios with mailtrap.io
Downloads
6
Maintainers
Readme
nightwatch-mailtrap
Nightwatch.js 🦉 plugin adding custom assertions for covering email functionality in e2e test scenarios with mailtrap.io 📨
Purpose
In your end-to-end (e2e) Nightwatch browser test automation you may encounter scenarios where you need to ensure an email is sent out by the system under test to the correct recipient and verify its contents. Other scenarios, like user registration, may require following a link received in an email. This is hard to do programmatically with most mail services in a CI/CD system, but Mailtrap provides an email sandbox service with API that let's you programmatically receive and read email messages to their virtual inboxes.
The nightwatch-mailtrap plugin will allow one to programmatically
- Assert inbox message count (optionally filtered by subject, recipient name, or recipient address)
- Assert partial text match of email message body
- Assert partial text match of email subject
- Extract the first link from an email message body
Examples
module.exports = {
'should get messages': async (browser) => {
const inboxId = browser.globals.mailtrap.mailboxId;
// Ability to grab the link URL out of the message body
let url = await browser.getLinkFromEmail(inboxId);
// Example navigating the browser to the URL from the message body link
browser.url(url);
// Test inbox contains 5 emails
browser.assert.expectedInboxCount(5, inboxId);
// Test inbox has 1 email if subject, to_email, or to_name matches "hello"
browser.assert.expectedInboxCount(1, inboxId, 'hello');
// Test that the first email message containing Welcome has "Bienvenue à Nightwatch" in the message body
browser.assert.emailBodyContains(
'Bienvenue à Nightwatch',
inboxId,
'Welcome'
);
// Assert the text of the first email matching 'latest tests' matches 'The latest tests delivered...'
browser.assert.emailSubjectContains(
'The latest tests delivered straight to your inbox',
inboxId,
'latest tests' // optional search filter
);
},
browser.end();
},
};
Installation (for Nightwatch >= v2.0)
- In an existing working Nightwatch.js test project open
nightwatch.conf.js
- Locate or add the
plugins:
section and appendnightwatch-mailtrap
to the array.
// nightwatch.conf.js
module.exports = {
...
src_folders: ['test'],
plugins: ['nightwatch-mailtrap'],
...
}
- Run
npm install nightwatch-mailtrap --save
to ensure the library is added to your project and can be used as a plugin.
Alternate Installation (Older method not using plugin pattern)
- Run
npm install nightwatch-mailtrap --save
- Specify the paths for the custom commands and custom assertions in the
nightwatch.conf.js
file
//nightwatch.conf.js
module.exports = {
...
custom_commands_path: './node_modules/nightwatch-mailtrap/nightwatch/commands',
custom_assertions_path: './node_modules/nightwatch-mailtrap/nightwatch/assertions',
...
}
Configuration
nightwatch-mailtrap extends Nightwatch commands and assertions to work with an existing Mailtrap.io account. For that to work you need to provide your Mailtrap API Token and mailbox id (mailbox id is optional and can be provided at the test level). Those values are read from the nightwatch.conf.js
globals section.
//nightwatch.conf.js
test_settings: {
default: {
launch_url: 'http://localhost',
desiredCapabilities: {
browserName: 'chrome',
},
globals: {
mailtrap: {
apiToken: '${MAILTRAP_API_TOKEN}',
mailboxId: '${MAILTRAP_MAILBOX_ID}',
},
},
},
It's recommended you use environment variables as shown instead of hardcoding these values
Usage
Once the configuration changes are made the commands and assertions will be made available to the Nightwatch API (browser object) in your test cases.
browser.getLinkFromEmail(mailboxId: string, searchText: string?) => string
This will return the href value of the first link found in the most recent email in the specified mailbox id.
const url = await browser.getLinkFromEmail('12345', 'activate your account');
browser.navigate(url);
browser.assert.emailBodyContains(expectedText: string, mailboxId: string, searchText: string?) => NightwatchAPI
This is a custom assertion that will return pass or fail if a partial match is found of your expectedText in the most recent email, filtered by the searchText parameter if provided.
browser.assert.emailBodyContains(
'reaching out to you',
browser.globals.mailtrap.mailboxId,
'car warranty'
);
browser.assert.expectedInboxCount(expectedCount: number, mailboxId: string, searchText: string?) => NightwatchAPI
browser.assert.expectedInboxCount(
2,
browser.globals.mailtrap.mailboxId,
'Jane'
);
See full article Automated Email Testing with Nightwatch and MailTrap for more information.