Testing

Use MailSlurp to test email related functionality using real email addresses.

Integration testing is a core function of MailSlurp. This page covers the basic approaches and use cases.

Concepts

In testing it is best to create all the entities you need each test run. This ensures that you start with a blank slate each time.

Creating inboxes

The first step for any test is to create a new empty inbox with a randomly assigned email address. Use the createInbox() method for this purpose.

This guide assumes you have instantiated a Javascript MailSlurp client. The same approaches apply to any integration.

const inbox = await mailslurp.createInbox()

The resulting inbox will look something like this:

{
  "id": "123",
  "emailAddress": "123@mailslurp.com"
}

From now on in a test we can use the inboxes email address. We might sign up for an account with it, test to see if a welcome email was sent, or send an email from it to a processing endpoint in our app and test the apps response. It's up to you.

Sending emails

You can send an email easily using the sendEmail() methods with a given inbox id.

await mailslurp.sendEmail(inboxId, { to: ['user@test.com'], body: 'Hello' })

Receiving emails

To receive emails in tests use the waitFor methods after your app or test has done something that sends an email to your inbox.

Note waitFor methods hold a connection open until a conditon is met within the default or specified timeout. You must ensure that your test-suite has an appropriately high timeout to permit this.

There are many waitFor methods available. The simplest is waitForLatestEmail which has the following signature:

waitForLatestEmail(inboxId?: string, timeout?: number): Promise<Email>

This will either return the latest email OR hold open the connection until a email is received. You can adjust the timeout period with a millisecond value as the second parameter. Here is an example:

test('app sends welcome`, async () => {

  const inbox = await mailslurp.createInbox();

  await myApp.sendWelcome(inbox.emailAddress);

  const welcome = await mailslurp.waitForLatestEmail(inbox.id)

  expect(welcome.subject).toBe('Welcome!')
})

Extracting email content

MailSlurp email responses split a message into various properties such as to, subject and body. The body is the text content of an email in string form. The full body is available like so:

const email = await mailslurp.waitForLatestEmail(inbox.id)
console.log(email.body)

If you want to extract a section of the message body for use in further test steps you can do so easily with a regular expression.

// fetch an email
const email = await mailslurp.waitForLatestEmail(inbox.id)

// execute a regular express capture group on the body and 
// destructure the matching group into a variable
const [_, verificationCode] = /your code is "([0-9]{6})"/g.exec(email.body)

// do something with code like verifying an account
myApp.confirmUser(verificationCode)

Be aware that some emails contain HTML entities such as &amp;. These look like regular characters in a browser but aren't matched by those characters in Javascript regular expressions. Use HTML entities in your regular expression if this is the case.

Here is an example that extracts a code number from the body of an HTML message containing http://test.com?code=123.

// notice that "=" is replaced with "&#x3D;" HTML entity
const [_, code] = /\?code&#x3D;([^'"]+)/g.exec(body)

MailSlurp is free for personal use and scales with your team. Try it today.