SMS testing for Cypress

What you'll find in this guide

• How to test various aspects of SMS
• Testing links and codes
• Managing SMS tests

What you'll need

• An understanding of how to use Cypress.
• A Mailosaur account with the SMS feature enabled. If you don�t have one already, you can start a free trial.
• A Cypress project with Mailosaur's API client configured. See our short guide on this.

Basic usage

To perform SMS testing with Cypress, all you need to do is:

1. Send an SMS message to your dedicated Mailosaur phone number.
2. Connect to the Mailosaur API with the official client library.
3. Search for the message you sent in step 1.
4. Perform assertions in the same way you would for any other test.

If you would like to learn about Server IDs, and what to replace SERVER_ID with, see sending test emails to Mailosaur.

// Search for the message
cy.mailosaurGetMessage("SERVER_ID", {
  sentTo: "123456789", // Phone number
}).then((message) => {
  // Perform test assertions
  expect(message.from[0].name).to.equal("Support");
  expect(message.from[0].phone).to.equal("654321");
});

The above example will search for the phone number that a message was sent to. You can also use any of the below criteria to search:

Find an SMS message

Search for a specific message in your inbox. We recommend using cy.mailosaurGetMessage(), as this will automatically wait for messages to arrive, and then return the full message result.

cy.mailosaurGetMessage("SERVER_ID", {
  sentTo: "123456789",
}).then((message) => {
  cy.log(message.text.body);
});

Time range for searching

By default searches only look for messages received in the last hour. To look back further in your message history, If you want to look further back than this, just set the 'received after' parameter.

// Calculate a datetime for yesterday
const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);

// Use this timestamp in the search
cy.mailosaurGetMessage("SERVER_ID", {
  sentTo: "123456789",
}, {
  receivedAfter: yesterday
}).then((message) => {

});

"No matching messages" troubleshooting

If you see the error "No matching messages found in time" when searching for messages:

• Ensure that target email or SMS message is visible in the Mailosaur Dashboard, as it may not have arrived at all.
• Check when the message arrived. By default, searches only include messages received within the last hour. See "time range for searching" above on how to override this.
• Check you have correctly set the sent to parameter in your search criteria.

Other methods of fetching SMS messages

We recommend using the cy.mailosaurGetMessage() as this automatically waits for a matching result and returns the message.

Search for multiple messages

Identify if multiple messages meet the same criteria.

// Search for all messages sent to 123456789.
// Limit results to the first 10 matches only.
cy.mailosaurSearchMessages(
  "SERVER_ID",
  {
    sentTo: "123456789",
  },
  {
    page: 0,
    itemsPerPage: 10,
  }
)
  .then((result) => {
    // Get the most recent message (the first one in the list)
    const latestMessage = result.items[0];

    // Get the full message object
    return cy.mailosaurGetMessageById(latestMessage.id);
  })
  .then((message) => {
    cy.log(message.text.body);
  });

List current inbox contents

List everything that is currently in your inbox.

// List the most recent messages
cy.mailosaurListMessages("SERVER_ID")
  .then((result) => {
    // Get the most recent message (the first one in the list)
    const latestMessage = result.items[0];

    // Get the full message object
    return cy.mailosaurGetMessageById(latestMessage.id);
  })
  .then((message) => {
    cy.log(message.text.body);
  });

Common test scenarios

Testing basic properties

Once you an SMS has been retrieved, you can effectively test the properties of that text:

// Test sender information
expect(message.from[0].name).to.equal("Support");
expect(message.from[0].phone).to.equal("654321");

// Test recipient information
expect(message.to[0].name).to.equal("John Smith");
expect(message.to[0].phone).to.equal("1234567890");

Testing SMS contents

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

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

Testing links

Any links found in email content can be automatically available via the text.links array:

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

const firstLink = message.text.links[0];
expect(firstLink.text).to.equal("Google Search");
expect(firstLink.href).to.equal("https://www.google.com/");

Testing verification codes

Extract codes automatically from the content of your SMS message. Make them available via the text.codes array:

const otp = message.text.codes[0];
expect(otp.value).to.equal("456812");

Replying to an SMS message

If your product handles SMS replies from your customers, you can use the Mailosaur’s reply feature to simulate responses. The SMS is sent back to the phone number it was originally sent to Mailosaur from:

cy.mailosaurReplyToMessage("MESSAGE_ID", {
  text: "FYI",
});

Forwarding a message to email

You can forward messages from your Mailosaur account to external email addresses either one-by-one, or via automated forwarding rules. However, to forward messages, you must set up a verified external email address:

cy.mailosaurForwardMessage("MESSAGE_ID", {
  to: "verified-address@example.com",
  text: "FYI",
});

Deleting messages

Deleting an individual message

Permanently deletes a single message and any attachments related to it. This operation cannot be undone:

cy.mailosaurDeleteMessage("MESSAGE_ID");

Delete all messages

Permanently deletes all messages held in the specified server/inbox, along with all related attachments. This operation cannot be undone:

cy.mailosaurDeleteAllMessages("SERVER_ID");

See also

• Email testing guide
• MFA/2FA guide