codeceptjs
Version:
Modern Era Acceptance Testing Framework for NodeJS
177 lines (125 loc) • 5.01 kB
Markdown
---
id: email
title: Email Testing
---
In End 2 End testing we need to interact with emails.
Email delivery can't tested locally or mocked while testing.
That's why for an end to end test you need to use a real emails to be sent and real email address to receive that emails.
Setting up an email server can be hard. So we recommend to use a [MailSlurp](https://mailslurp.com/) - a service designed for testing emails. It creates disposable mailboxes and provides you an access to those mailboxes via REST API.
> You no longer need to open your gmail account in a browser to check for an email!
## Installation
MailSlurp is a commercial service with a free plan available. To start, [create an account at MailSlurp](https://app.mailslurp.com/) and receive API key to use it. Once received install mailslurp helper from npm:
```
npm i /mailslurp-helper --save-dev
```
Then enable a helper in `codecept.conf.js`:
```js
helpers: {
MailSlurp: {
require: '/mailslurp-helper',
apiKey: '<apiKeyFromMailSlurp>'
}
}
```
After a helper is added, regenerate TypeScript definitions for auto-completion support:
```
npx codeceptjs def
```
## Creating Mailbox
MailSlurp allows you to create disposable mailboxes. It means that an email address is created for a one test only and is deleted afterwards. So you can be confident that no other emails are received at that address.
To create a mailbox use `I.haveNewMailbox()` command:
```js
// inside async/await function
const mailbox = await I.haveNewMailbox();
```
mailbox object contains:
* `id` - which is used in next commands
* `emailAddress` - randomly generated address of a created mailbox.
> See [MailSlurp's guide](https://www.mailslurp.com/guides/getting-started/#create-email-addresses) for details.
Mailbox is opened on creation. If you need more than one mailboxes and you want to switch between them use `openMailbox` method:
```js
const mailbox1 = await I.haveNewMailbox();
const mailbox2 = await I.haveNewMailbox();
// mailbox2 is now default mailbox
// switch back to mailbox1
I.openMailbox(mailbox);
```
## Receiving An Email
A last created mailbox will be activated. It means that it will be used by default to check for emails.
After an action that triggers sending an email is performed on a website you should wait for this email to be received.
A timeout for waiting an email can be set globally for a helper or for a one call.
Use `waitForLatestEmail` function to return the first email from a mailbox:
```js
// to wait for default time (10 secs by default)
I.waitForLatestEmail();
// or specify number of time to wait
I.waitForLatestEmail(30);
```
To specify the exact email to match use `waitForEmailMatching` function:
```js
// wait for an email with partial match in subject
I.waitForEmailMatching({ subject: 'Restore password' });
// wait 30 seconds for email with exact subject
I.waitForEmailMatching({ subject: '=Forgot password' }, 30);
// wait a last email from any address @mysite.com
I.waitForEmailMatching({
from: '.com', // find anything from mysite
subject: 'Restore password', // with Restore password in subject
});
```
## Opening An Email
All wait* functions return a matched email as a result. So you can use it in a test:
```js
const email = await I.waitForLatestEmail();
```
> Please note, that we use `await` to assign email. This should be declared inside async function
An `email` object contains following fields:
* `subject`
* `for`
* `to`
* `body`
So you can analyze them inside a test. For instance, you can extract an URL from email body and open it.
This is how we can emulate "click on this link" behavior in email:
```js
// clicking a link in email
const email = await I.waitForLatestEmail();
// extract a link by RegExp
const url = email.body.match(/http(s):\/\/(.*?)\s/)[0];
// open URL
I.amOnPage(url);
```
## Assertions
Assertions are performed on the currently opened email.Email is opened on `waitFor` email call, however, you can open an exact email by using `openEmail` function.
```js
const email1 = await I.waitForLatestEmail();
// test proceeds...
const email2 = await I.waitForLatestEmail();
I.openEmail(email1); // open previous email
```
After opening an email assertion methods are available.
* `seeInEmailSubject`
* `seeEmailIsFrom`
* `seeInEmailBody`
* `dontSeeInEmailBody`
And here is an example of their usage:
```js
I.waitForLatestEmail()
I.seeEmailIsFrom('.com');
I.seeInEmailSubject('Awesome Proposal!');
I.seeInEmailBody('To unsubscribe click here');
```
> More methods are listed in [helper's API reference](https://github.com/codecept-js/mailslurp-helper/blob/master/README.md#api)
## Listing All Emails
Use `grabAllEmailsFromMailbox` to get all emails from a current mailbox:
```js
const emails = await I.grabAllEmailsFromMailbox();
```
## Sending an Email
You can also send an email from an active mailbox:
```js
I.sendEmail({
to: ['user.com'],
subject: 'Hello',
body: 'World'
});
```