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

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')

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 MailSlurp
timeout (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.haveMailbox();

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.waitForEmail({
 subject: 'password',
});

// wait 30 seconds for email with exact subject
const email = await I.waitForEmail({
 subject: '=Forgot password',
}, 30);

// 
const email = await I.waitForEmail({
 from: '@mysite.com', // find anything from mysite
 subject: 'Restore password', // with Restore password in subject
});

Parameters

query object to locate an email
sec 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 email
num 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.