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.

``js
helpers: {
MailSlurp: {
apiKey: '',
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

`js
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

`js
const mailbox1 = await I.haveNewMailbox();
const mailbox2 = await I.haveNewMailbox();
I.openMailbox(mailbox1);
const email = I.waitForEmailMatching({ subject: 'Register' });
`

Using Custom Assertions In Tests

`js
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
- Configuration
- Properties
- haveNewMailbox
- haveExistingMailbox
- Parameters
- openMailbox
- Parameters
- sendEmail
- Parameters
- waitForLatestEmail
- Parameters
- waitForEmailMatching
- Parameters
- waitForNthEmail
- Parameters
- grabEmailsMatching
- Parameters
- grabAllEmailsFromMailbox
- seeInEmailSubject
- Parameters
- dontSeeInEmailSubject
- Parameters
- seeInEmailBody
- Parameters
- dontSeeInEmailBody
- Parameters
- seeEmailIsFrom
- Parameters
- seeEmailSubjectEquals
- Parameters
- dontSeeEmailSubjectEquals
- Parameters
- seeNumberOfEmailAttachments
- Parameters
- seeEmailAttachment
- Parameters

$3

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

`js
helpers: {
MailSlurp: {
apiKey: '',
require: '@codeceptjs/mailslurp-helper'
},
}
`

> Use .env file and environment variables to store sensitive data like API keys

$3

- 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

- apiKey string
- timeout number?
- debug boolean?

$3

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

`js
const mailbox = await I.haveNewMailbox();
`

$3

Use an existing mailbox.

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

#### Parameters

- mailboxId string ID of an existing MailSlurp inbox.

Returns Promise<Inbox>

$3

Change a current mailbox to a provided one:

`js
const mailbox1 = await I.haveMailbox();
const mailbox2 = await I.haveMailbox();
// mailbox2 is now default mailbox
// switch back to mailbox1
I.openMailbox(mailbox)
`

#### Parameters

- mailbox

$3

Sends an email from current mailbox, created by I.haveNewMailbox().

`js
I.sendEmail({
to: ['user@site.com'],
subject: 'Hello',
body: 'World'
});
`

#### Parameters

- data

$3

Waits for the first email in mailbox.
If mailbox is not empty - opens the last email.

`js
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.

$3

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.

`js
// 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.

$3

Wait for exact number of emails in mailbox. Returns the last email in the list.

`js
// 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

$3

Returns a bunch of emails matched by query.
Similar to waitForEmailMatching but returns an array of emails.

`js
// 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.

$3

Returns all emails from a mailbox.

`js
const emails = await I.grabAllEmailsFromMailbox();
`

Returns Promise<\[Email]> emails.

$3

Checks that current email subject contains a text.

`js
I.seeInEmailSubject('Restore password');
`

Requires an opened email. Use either waitForEmail* methods to open. Or open manually with I.openEmail() method.

#### Parameters

- text

$3

Checks that current email subject does not contain a text.

`js
I.seeInEmailSubject('Restore password');
`

Requires an opened email. Use either waitForEmail* methods to open. Or open manually with I.openEmail() method.

#### Parameters

- text

$3

Checks that current email body contains a text.

`js
I.seeInEmailBody('Click link');
`

Requires an opened email. Use either waitForEmail* methods to open. Or open manually with I.openEmail() method.

#### Parameters

- text

$3

Checks that current email body does not contain a text.

`js
I.dontSeeInEmailBody('Click link');
`

Requires an opened email. Use either waitForEmail* methods to open. Or open manually with I.openEmail() method.

#### Parameters

- text

$3

Checks that email is from a specified address.

`js
I.seeEmailIsFrom('user@user.com');
`

Requires an opened email. Use either waitForEmail* methods to open. Or open manually with I.openEmail() method.

#### Parameters

- text

$3

Checks that current email subject equals to text.

`js
I.seeEmailSubjectEquals('Restore password');
`

Requires an opened email. Use either waitForEmail* methods to open. Or open manually with I.openEmail() method.

#### Parameters

- text

$3

Checks that current email subject doesn't equal to text.

`js
I.dontSeeEmailSubjectEquals('Restore password');
`

Requires an opened email. Use either waitForEmail* methods to open. Or open manually with I.openEmail() method.

#### Parameters

- text

$3

Checks that current email has expected number of attachments.

`js
I.seeNumberOfEmailAttachments(2);
`

Requires an opened email. Use either waitForEmail* methods to open. Or open manually with I.openEmail() method.

#### Parameters

- number

$3

Checks that current email has an attachment with specified name.

`js
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`