Skip to content

codeceptjs/mailslurp-helper

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

69 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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();
// 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')

LICENSE

MIT

API

Table of Contents

Configuration

Allows to use real emails in E2E tests via MailSlurp service. Sign up for an 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.
  • debug (default: false) - print debug logs

Type: {apiKey: string, timeout: number?, debug: boolean?}

Properties

haveNewMailbox

Creates a new mailbox. A mailbox will be deleted after a test. Switches to last created mailbox.

const mailbox = await I.haveNewMailbox();

haveExistingMailbox

Use an existing mailbox.

const mailbox = await I.haveExistingMailbox('94cxxxf4-7231-46ce-9f40-xxxcae39xxxx');

Parameters

  • mailboxId string ID of an existing MailSlurp inbox.

Returns Promise<Inbox>

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: ['[email protected]'],
  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 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 '[email protected]'
const emails = await I.grabEmailsMatching({ from: '[email protected]'}, 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('[email protected]');

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