How to test SMS in Node.js

What is Mailosaur?

Mailosaur is a service that captures email and SMS messages and lets you test them, both via it’s web dashboard and via the Mailosaur testing API.

Install the Mailosaur API client

Mailosaur provides an official library with everything you need to easily automate SMS testing in Playwright or any other Node.js tests.

Install the Mailosaur Node.js library via npm

npm install mailosaur

Import Mailosaur into your project

In order to connect to Mailosaur, you need an API key. You access your API key via in the account settings area.

In your tests, simply import the Mailosaur library, using your API key:

const MailosaurClient = require("mailosaur");
const mailosaur = new MailosaurClient("YOUR_API_KEY_HERE");

Basic usage

The messages.get method automatically waits for the first SMS to arrive that matches the search criteria you provide.

const MailosaurClient = require("mailosaur");
const mailosaur = new MailosaurClient("YOUR_API_KEY_HERE");

const sms = await mailosaur.messages.get("SERVER_ID", {
  sentTo: "15551234444",
});

console.log(sms.text.body);

To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.

This example searches for the phone number a message was sent to, but you can also search using any of this criteria too:

PARAMETER	DESCRIPTION
sentTo	The full phone number to which the target message was sent.
sentFrom	The full phone number from which the target message was sent.
body	Finds messages where the message body contains this text.

The messages.get method returns the message object, which contains everything you need to perform in-depth automated testing.

Increasing the wait time

By default, the messages.get method will wait for 10 seconds for a matching message to arrive. You can increase this wait time by using the timeout option:

const sms = await mailosaur.messages.get(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    timeout: 20000, // 20 seconds (in milliseconds)
  }
);

console.log(sms.text.body);

Searching for older messages

By default, the messages.get method will only find messages received in the last hour. You can change this by setting the receivedAfter option.

const testStart = new Date();

// TODO Do something here to send an SMS message into your account

// Find any SMS received after `testStart` was set
const sms = await mailosaur.messages.get(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    receivedAfter: testStart,
  }
);

console.log(sms.text.body);

Testing basic properties

Once you have fetched an SMS message (e.g. using messages.get), you can easily test the properties of that message:

// Test sender information
expect(sms.from[0].name).toBe("ACME Corp.");
expect(sms.from[0].phone).toBe("123456");

// Test recipient information
expect(sms.to[0].phone).toBe("15551234444");

Testing SMS contents

The content of an SMS message is available via the text.body property:

// Check that the SMS message contains some text
expect(sms.text.body).toContain("Expected text");

Testing links

Any links that are found in the content of your message are instantly available via the text.links array:

console.log(`${sms.text.links.length} links found in text content`);

// Check the first link found
expect(sms.text.links[0].href).toBe("https://google.com");

Navigating to a link

If you using an automation framework like Playwright or Cypress, you can navigate the browser to links within your tests:

// Playwright Example: Navigating to a link found in an SMS message
await page.goto(sms.text.links[0].href);

Clicking a link

If you just need to simulate a link being clicked and do not need to do anything on the target page, you can do this with https.

Import https at the top of your test file:

const https = require("https");

Then use this in your test to perform a 'click':

// Make an HTTP call to simulate someone clicking a link
https.get(sms.text.links[0].href, (r) => console.log(r.statusCode)); // 200

Testing verification codes

Codes are automatically extracted from the content of your SMS message. Codes are made available via the text.codes array:

console.log(`${sms.text.codes.length} codes found in text content`);

// Check the first code found in text content
expect(sms.text.codes[0].value).toBe("432123");

List all messages

Recommendation: We strongly recommend using the messages.get method for most use cases. This method has been purposely optimised for the most common automated testing scenarios.

If you simply need to list the current messages in an inbox, you can use messages.list:

const result = await mailosaur.messages.list("SERVER_ID");

console.log(`${result.items.length} messages in inbox`);

// Note: List results only contain summary information. To get
// the text content of a message, use `messages.getById`
const sms = await mailosaur.messages.getById(result.items[0].id);

console.log(sms.text.body);

Alternative search for messages

Recommendation: We strongly recommend using the messages.get method for most use cases. This method automatically waits for a matching result, and also returns the whole message object in the result, rather than just a summary.

Using the messages.search method:

const result = await mailosaur.messages.search("SERVER_ID", {
  sentTo: "15551234444",
});

console.log(`${result.items.length} messages in inbox`);

// Note: List results only contain summary information. To get
// the text content of a message, use `messages.getById`
const sms = await mailosaur.messages.getById(result.items[0].id);

console.log(sms.text.body);

Wait for matches to arrive

By default the messages.search method will only return current matches. By setting the timeout option, the method will automatically wait for a match:

const result = await mailosaur.messages.search(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    timeout: 10000, // Wait 10 seconds (in milliseconds) for a match
  }
);

Testing that no matching messages are found

By default, an error will be thrown if no matches are found in time. However, if you are expecting no messages to arrive in a certain period of time, then simply set errorOnTimeout: false to prevent an exception being thrown:

const result = await mailosaur.messages.search(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    timeout: 10000,
    errorOnTimeout: false,
  }
);

Deleting messages

Delete all messages

To permanently delete all messages held in a specific server/inbox, use the messages.deleteAll method. This also deletes any attachments related to each message. This operation cannot be undone.

await mailosaur.messages.deleteAll("SERVER_ID");

Deleting an individual message

To permanently delete a single message, use messages.del. This also deletes any attachments related to the message. This operation cannot be undone.

await mailosaur.messages.del("MESSAGE_ID");

Replying to an SMS message

If your product is capable of handling SMS replies from your customers, you can use Mailosaur’s reply feature to simulate such a scenario.

When you reply, the SMS is sent back to the phone number it was originally sent to Mailosaur from.

await mailosaur.messages.reply("MESSAGE_ID", {
  text: "FYI",
});

Forwarding a message to email

Teams often need to forward SMS messages onto an email address outside of Mailosaur. For example, to send messages to colleagues for further review/analysis.

You can forward messages from your Mailosaur account to external email addresses either one-by-one, or via the creation of automated forwarding rules.

Before you can forward messages, you must set up a verified external email address, so that you can send email to it.

await mailosaur.messages.forward("MESSAGE_ID", {
  to: "verified-address@example.com",
  text: "Hello world",
});

The options available to use with the messages.forward method are:

PARAMETER	DESCRIPTION
to	The email address to which the email will be sent. Must be a verified email address.
text	Any additional text content to forward the message with.
html	Any additional HTML content to forward the message with.
subject	Optionally override the default subject line.