How to test email and SMS with WebdriverIO

What is WebdriverIO?

WebdriverIO (sometimes shortened to wdio) is a browser and mobile automation test framework for Node.js. It lets users automate any application written with modern web frameworks such as React, Angular, Polymer or Vue.js, as well as native mobile applications.

If you’re reading this, you likely already know to use WebdriverIO, however, if you are just getting started, take a look at the awesome getting started guide on the WebdriverIO website.

What is Mailosaur?

Mailosaur is a test automation service that lets you test email and SMS messages in frameworks like WebdriverIO. Allowing you to create end-to-end tests for account creation, password reset requests, identity verification and more!

If you don’t already have one, create a free account trial now, and send an email into Mailosaur first. Once you have this working, you’re ready to start testing!

Get Started

Installation

Install the Mailosaur Node.js library via npm or yarn:

npm i -D mailosaur
# or
yarn add -D mailosaur

Then import the library into your code. The value for YOUR_API_KEY is covered in the next step (creating an account):

const MailosaurClient = require('mailosaur')
const mailosaur = new MailosaurClient('YOUR_API_KEY')

API Reference

The Node.js library is powered by the Mailosaur email & SMS testing API. You can easily check out the API itself by looking at our API reference documentation or via our Postman or Insomnia collections:

Creating an account

Create a free trial account for Mailosaur via the signup page.

Once you have this, navigate to the API tab to find the following values:

Server ID - Servers act like projects, which group your tests together. You need this ID whenever you interact with a server via the API.
Server Domain - Every server has its own domain name. You’ll need this to send email to your server.
API Key - You can create an API key per server (recommended), or an account-level API key to use across your whole account. Learn more about API keys.

Test email addresses with Mailosaur

Mailosaur gives you an unlimited number of test email addresses to use with WebDriverIO - with no setup or coding required!

Here’s how it works:

When you create an account, you are given a server.
Every server has its own Server Domain name (e.g. abc123.mailosaur.net)
Any email address that ends with @{YOUR_SERVER_DOMAIN} will work with Mailosaur without any special setup. For example:
- build-423@abc123.mailosaur.net
- john.smith@abc123.mailosaur.net
- rAnDoM63423@abc123.mailosaur.net
You can create more servers when you need them. Each one will have its own domain name.

Can’t use test email addresses? You can also use SMTP to test email. By connecting your product or website to Mailosaur via SMTP, Mailosaur will catch all email your application sends, regardless of the email address.

Find an email

In automated tests you will want to wait for a new email to arrive. This library makes that easy with the messages.get method. Here’s how you use it:

const { remote } = require('webdriverio');
const MailosaurClient = require('mailosaur')
const mailosaur = new MailosaurClient('API_KEY')

;(async () => {
    const browser = await remote({
        capabilities: {
            browserName: 'chrome'
        }
    })

    await browser.url('https://example.mailosaur.com/password-reset')

    // See https://mailosaur.com/app/project/api
    const serverId = 'abc123'
    const serverDomain = 'abc123.mailosaur.net'
    
    const testEmailAddress = `some-random-string@${serverDomain}`

    // Submit the password reset request
    const email = await browser.$('#email')
    email.setValue(testEmailAddress)

    const btn = await browser.$('button[type="submit"]')
    btn.click()

    const searchCriteria = {
      sentTo: testEmailAddress
    }

    const message = await mailosaur.messages.get(serverId, searchCriteria)

    console.log(message.subject)

    await browser.deleteSession()
})()

What is this code doing?

Sets up an instance of MailosaurClient with your API key.
Waits for an email to arrive at the server with ID abc123.
Performs an assertion on the subject line of the email.

My email wasn’t found

First, check that the email you sent is visible in the Mailosaur Dashboard.

If it is, the likely reason is that by default, message.get only searches emails received by Mailosaur in the last 1 hour. You can override this behavior (see the receivedAfter option below), however we only recommend doing this during setup, as your tests will generally run faster with the default settings:

const email = await mailosaur.messages.get(
  serverId,
  searchCriteria,
  // Override receivedAfter to search all messages since Feb 1st
  { receivedAfter: new Date(2021, 1, 1) }
)

Find an SMS message

Important: Trial accounts do not automatically have SMS access. Please contact our support team to enable a trial of SMS functionality.

If your account has SMS testing enabled, you can reserve phone numbers to test with, then use the Mailosaur API in a very similar way to when testing email:

// ...

const searchCriteria = {
  sentTo: '4471235554444'
}

const sms = await mailosaur.messages.get(serverId, searchCriteria)

console.log(sms.text.body)

Testing plain text content

Most emails, and all SMS messages, should have a plain text body. Mailosaur exposes this content via the text.body property on an email or SMS message:

console.log(message.text.body) // "Hi Jason, ..."

if (message.text.body.indexOf('Jason') > -1) {
  console.log('Email contains "Jason"')
}

Extracting verification codes from plain text

You may have an email or SMS message that contains an account verification code, or some other one-time passcode. You can extract content like this using a simple regex.

Here is how to extract a 6-digit numeric code:

console.log(message.text.body) // "Your access code is 243546."

const regEx = new RegExp('([0-9]{6})')
const matches = regEx.exec(message.text.body)

console.log(matches[0]) // "243546"

Testing HTML content

Most emails also have an HTML body, as well as the plain text content. You can access HTML content in a very similar way to plain text:

console.log(message.html.body) // "<html><head ..."

Working with HTML using JSDOM

If you need to traverse the HTML content of an email. For example, finding an element via a CSS selector, you can use the JSDOM library.

npm i -D jsdom
# or
yarn add -D jsdom

const { JSDOM } = require('jsdom')

// ...

const dom = new JSDOM(message.html.body);

const el = dom.window.document.querySelector('.verification-code');
const verificationCode = el.textContent; // "542163"

Working with hyperlinks

When an email is sent with an HTML body, Mailosaur automatically extracts any hyperlinks found within anchor (<a>) and area (<area>) elements and makes these available via the html.links array.

Each link has a text property, representing the display text of the hyperlink within the body, and an href property containing the target URL:

// How many links?
console.log(message.html.links.length) // 2

const firstLink = message.html.links[0]
console.log(firstLink.text) // "Google Search"
console.log(firstLink.href) // "https://www.google.com/"

Important: To ensure you always have valid emails. Mailosaur only extracts links that have been correctly marked up with <a> or <area> tags.

Links in plain text (including SMS messages)

Mailosaur auto-detects links in plain text content too, which is especially useful for SMS testing:

// How many links?
console.log(message.text.links.length) // 2

const firstLink = message.text.links[0]
console.log(firstLink.href) // "https://www.google.com/"

Working with attachments

If your email includes attachments, you can access these via the attachments property:

// How many attachments?
console.log(message.attachments.length) // 2

Each attachment contains metadata on the file name and content type:

const firstAttachment = message.attachments[0]
console.log(firstAttachment.fileName) // "contract.pdf"
console.log(firstAttachment.contentType) // "application/pdf"

The length property returns the size of the attached file (in bytes):

const firstAttachment = message.attachments[0]
console.log(firstAttachment.length) // 4028

Writing an attachment to disk

const fs = require('fs')

// ...

const firstAttachment = message.attachments[1]

const fileBytes = await mailosaur.files.getAttachment(firstAttachment.id)
fs.writeFileSync(firstAttachment.fileName, fileBytes)

Working with images and web beacons

The html.images property of a message contains an array of images found within the HTML content of an email. The length of this array corresponds to the number of images found within an email:

// How many images in the email?
console.log(message.html.images.length) // 1

Remotely-hosted images

Emails will often contain many images that are hosted elsewhere, such as on your website or product. It is recommended to check that these images are accessible by your recipients.

All images should have an alternative text description, which can be checked using the alt attribute.

const image = message.html.images[0]
console.log(image.alt) // "Hot air balloon"

Triggering web beacons

A web beacon is a small image that can be used to track whether an email has been opened by a recipient.

Because a web beacon is simply another form of remotely-hosted image, you can use the src attribute to navigate to that address:

const image = message.html.images[0]
console.log(image.src) // "https://example.com/s.png?abc123"

// Make an HTTP call to trigger the web beacon
await t.page(image.src)

Spam checking

You can perform a SpamAssassin check against an email. The structure returned matches the spam test object:

const result = await mailosaur.analysis.spam(message.id)

console.log(result.score) // 0.5

result.spamFilterResults.spamAssassin.forEach(r => {
  console.log(r.rule)
  console.log(r.description)
  console.log(r.score)
})

Library reference

Check out all of the methods available to the Mailosaur Node.js library.