README
MailSlurp helper for CodeceptJS
MailSlurp helper for testing emails with MailSlurp service. MailSlurp creates disposable mailbox for each test and removes it after a test.
Setup
Register and obtain API key from MailSlurp.
npm i @codeceptjs/mailslurp-helper --save
Enable helper in codecept.conf.js
.
helpers: {
MailSlurp: {
apiKey: '<insert api key here>',
require: '@codeceptjs/mailslurp-helper'
},
}
Use Cases
Use this helper in your tests to check email interactions. The most popular one
- Account activation
- Restore forgotten password
- Action verification
Use Case: Restore Password
const mailbox = await I.haveNewMailbox();
// register user on a website
I.registerUser(mailbox.emailAddress);
// wait 10 seconds for an email
const email = await I.waitForLatestEmail(10);
I.seeInEmailSubject('Restore Password');
I.seeInEmailBody('Click link to restore password');
const restoreUrl = email.body.match(/http(s):\/\/(.*?)\s/)[0];
I.amOnPage(restoreUrl);
Switching Between Mailboxes
const mailbox1 = await I.haveNewMailbox();
const mailbox2 = await I.haveNewMailbox();
I.openMailbox(mailbox1);
const email = I.waitForEmailMatching({ subject: 'Register' });
Using Custom Assertions In Tests
const assert = require('assert');
const mailbox = await I.haveNewMailbox();
const email = await I.waitForEmailMatching({ subject: 'Thanks' });
assert.eql(email.subject, 'Thanks for registering')
API
Table of Contents
- MailSlurp
- Configuration
- Parameters
- haveNewMailbox
- openMailbox
- sendEmail
- waitForLatestEmail
- waitForEmailMatching
- waitForNthEmail
- grabEmailsMatching
- grabAllEmailsFromMailbox
- seeInEmailSubject
- dontSeeInEmailSubject
- seeInEmailBody
- dontSeeInEmailBody
- seeEmailIsFrom
- seeEmailSubjectEquals
- dontSeeEmailSubjectEquals
- seeNumberOfEmailAttachments
- seeEmailAttachment
MailSlurp
Allows to use real emails in end 2 end tests via MailSlurp service. Sign up for account at MailSlurp to start.
A helper requires apiKey from MailSlurp to start
helpers: {
MailSlurp: {
apiKey: '<insert api key here>',
require: '@codeceptjs/mailslurp-helper'
},
}
Use .env file and environment variables to store sensitive data like API keys
Configuration
apiKey
(required) - api key from MailSlurptimeout
(default: 10000) - time to wait for emails in milliseconds.
Parameters
config
haveNewMailbox
Creates a new mailbox. A mailbox will be deleted after a test. Switches to last created mailbox.
const mailbox = await I.haveNewMailbox();
openMailbox
Change a current mailbox to a provided one:
const mailbox1 = await I.haveMailbox();
const mailbox2 = await I.haveMailbox();
// mailbox2 is now default mailbox
// switch back to mailbox1
I.openMailbox(mailbox)
Parameters
mailbox
sendEmail
Sends an email from current mailbox, created by I.haveNewMailbox()
.
I.sendEmail({
to: ['user@site.com'],
subject: 'Hello',
body: 'World'
});
Parameters
data
waitForLatestEmail
Waits for the first email in mailbox. If mailbox is not empty - opens the last email.
I.waitForLatestEmail()
// wait for 30 seconds for an email
I.waitForLatestEmail(30);
Parameters
sec
num? Number of seconds to wait.
Returns Promise<Email> an email received.
waitForEmailMatching
Wait for an exact email matched by query. You can match emails by from
, to
, subject
, cc
, bcc
fields.
My default, non-strcit matching enabled, so it searches for inclusion of a string. For a strict matching (equality)
prepend a value with =
prefix.
// wait for email with 'password' in subject
const email = await I.waitForEmailMatching({
subject: 'password',
});
// wait 30 seconds for email with exact subject
const email = await I.waitForEmailMatching({
subject: '=Forgot password',
}, 30);
//
const email = await I.waitForEmailMatching({
from: '@mysite.com', // find anything from mysite
subject: 'Restore password', // with Restore password in subject
});
Parameters
query
object to locate an emailsec
num? Number of seconds to wait.
Returns Promise<Email> an email received.
waitForNthEmail
Wait for exact number of emails in mailbox. Returns the last email in the list.
// wait for 2 emails
I.waitForNthEmail(2);
// wait for 5 emails for 60 seconds
I.waitForNthEmail(5, 60);
// wait for 2 emails and return the last one
const email = await I.waitForNthEmail(2);
Parameters
number
sec
grabEmailsMatching
Returns a bunch of emails matched by query.
Similar to waitForEmailMatching
but returns an array of emails.
// return 2 emails from 'user@user.com'
const emails = await I.grabEmailsMatching({ from: 'user@user.com'}, 2);
Parameters
query
object to locate an emailnum
num? Number of emails to return.
Returns Promise<[Email]> emails matching criteria.
grabAllEmailsFromMailbox
Returns all emails from a mailbox.
const emails = await I.grabAllEmailsFromMailbox();
Returns Promise<[Email]> emails.
seeInEmailSubject
Checks that current email subject contains a text.
I.seeInEmailSubject('Restore password');
Requires an opened email. Use either waitForEmail*
methods to open. Or open manually with I.openEmail()
method.
Parameters
text
dontSeeInEmailSubject
Checks that current email subject does not contain a text.
I.seeInEmailSubject('Restore password');
Requires an opened email. Use either waitForEmail*
methods to open. Or open manually with I.openEmail()
method.
Parameters
text
seeInEmailBody
Checks that current email body contains a text.
I.seeInEmailBody('Click link');
Requires an opened email. Use either waitForEmail*
methods to open. Or open manually with I.openEmail()
method.
Parameters
text
dontSeeInEmailBody
Checks that current email body does not contain a text.
I.dontSeeInEmailBody('Click link');
Requires an opened email. Use either waitForEmail*
methods to open. Or open manually with I.openEmail()
method.
Parameters
text
seeEmailIsFrom
Checks that email is from a specified address.
I.seeEmailIsFrom('user@user.com');
Requires an opened email. Use either waitForEmail*
methods to open. Or open manually with I.openEmail()
method.
Parameters
text
seeEmailSubjectEquals
Checks that current email subject equals to text.
I.seeEmailSubjectEquals('Restore password');
Requires an opened email. Use either waitForEmail*
methods to open. Or open manually with I.openEmail()
method.
Parameters
text
dontSeeEmailSubjectEquals
Checks that current email subject doesn't equal to text.
I.dontSeeEmailSubjectEquals('Restore password');
Requires an opened email. Use either waitForEmail*
methods to open. Or open manually with I.openEmail()
method.
Parameters
text
seeNumberOfEmailAttachments
Checks that current email has expected number of attachments.
I.seeNumberOfEmailAttachments(2);
Requires an opened email. Use either waitForEmail*
methods to open. Or open manually with I.openEmail()
method.
Parameters
number
seeEmailAttachment
Checks that current email has an attachment with specified name.
I.seeEmailAttachment('ExampleAttachment.pdf');
Be aware that Mailslurp SDK removes special characters in name of attachment, e.g. "Example-Attachment.pdf" will have name "ExampleAttachment.pdf".
Requires an opened email. Use either waitForEmail*
methods to open. Or open manually with I.openEmail()
method.
Parameters
nameRegExp