Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
360 lines (248 sloc) 8.65 KB

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

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.

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
You can’t perform that action at this time.