SMS testing with Cucumber

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 Cucumber and how it works.
A Mailosaur account with the SMS feature enabled. You can start a free trial if you don’t have one.
A Cucumber project with Mailosaur’s API client configured. See our quickstart guide on this.
Your Mailosaur account's API key and Server ID. To learn about Server IDs and what to replace “SERVER_ID” with, see our guide on sending test emails to Mailosaur.

Basic usage

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

1 - Send an SMS message to your dedicated Mailosaur phone number. (You can use your own mobile device to do this.)
2 - Write a Gherkin scenario using Given, When, and Then steps, such as:

Connect to the Mailosaur API with the official client library.
Search for the SMS you sent in step 1.
Verify that the sender's phone number is correct.

3 - Implement each Given, When and Then step in code, including assertions.

Cucumber tests are BDD (behavior-driven development) tests and have two parts:

Feature files: These define testing scenarios with Given, When, and Then steps to define the journey being tested.
Step definition files: These contain the code that implements each step from the feature files, including the test setup, actions, and assertions.

Create a scenario in a feature file, replacing "123456789" with the number of the SMS mailbox you messaged earlier and replacing "123456787" with your own phone number. Phone numbers should be entered in E.164 format without the plus sign:

✅ 14155550000 ❌ +14155550000 ❌ 0014155550000 ❌ 4155550000

Scenario: Basic SMS usage
    Given the Mailosaur API client is setup for SMS
    When I search for an SMS sent to "123456789"
    Then that SMS should be sent from "123456787"

Next, implement these steps in a step definition file:

Given('the Mailosaur API client is setup for SMS', function () {
  const apiKey = process.env.MAILOSAUR_API_KEY;
  serverId = process.env.MAILOSAUR_SERVER_ID;

  assert.ok(apiKey, 'MAILOSAUR_API_KEY must be set in .env');
  assert.ok(serverId, 'MAILOSAUR_SERVER_ID must be set in .env');
  
  assert.notStrictEqual(apiKey, '', 'MAILOSAUR_API_KEY must not be empty');
  assert.notStrictEqual(serverId, '', 'MAILOSAUR_SERVER_ID must not be empty');

  mailosaurClient = new MailosaurClient(apiKey);
});

When('I search for an SMS sent to {string}', async function (toNumber) {
  const searchCriteria = {
    sentTo: toNumber
  };

  message = await mailosaurClient.messages.get(serverId, searchCriteria);
});

Then('that SMS should be sent from {string}', function (fromNumber) {
  assert.strictEqual(message.from[0].phone, fromNumber, 'Sender phone number does not match');
});
@Given("the Mailosaur API client is setup for SMS")
public void the_mailosaur_api_client_is_setup() {
    Dotenv dotenv = Dotenv.load();
    String apiKey = dotenv.get("MAILOSAUR_API_KEY");
    serverId = dotenv.get("MAILOSAUR_SERVER_ID");
    assertNotNull("MAILOSAUR_API_KEY must be set", apiKey);
    assertNotNull("MAILOSAUR_SERVER_ID must be set", serverId);
    assertFalse("MAILOSAUR_API_KEY must not be empty", apiKey.isEmpty());
    assertFalse("MAILOSAUR_SERVER_ID must not be empty", serverId.isEmpty());
    mailosaurClient = new MailosaurClient(apiKey);
    assertNotNull("Client should be initialized", client);
}

@When("I search for an SMS sent to {string}")
public void i_search_for_an_sms_sent_to(String phoneNumber) throws Exception {
    // Setup search criteria
    SearchCriteria searchCriteria = new SearchCriteria();
    searchCriteria.withSentTo(phoneNumber);

    // Search for the message
    message = mailosaurClient.messages().get(serverId, searchCriteria);
    
}

@Then("that SMS should be sent from {string}")
public void that_sms_should_be_sent_from(String phoneNumber) {
    assertNotNull("Expected to find a message", message);
    assertNotNull("Message sender should not be null", message.from());
    assertEquals(phoneNumber, message.from().get(0).phone());
}
Given("the Mailosaur API client is setup for SMS") do
  api_key = ENV['MAILOSAUR_API_KEY']
  @server_id = ENV['MAILOSAUR_SERVER_ID']

  expect(api_key).not_to be_nil, 'MAILOSAUR_API_KEY must be set'
  expect(api_key.strip).not_to be_empty, 'MAILOSAUR_API_KEY must not be empty'

  expect(@server_id).not_to be_nil, 'MAILOSAUR_SERVER_ID must be set'
  expect(@server_id.strip).not_to be_empty, 'MAILOSAUR_SERVER_ID must not be empty'
  
  @mailosaurClient = Mailosaur::MailosaurClient.new(api_key)
  expect(@client).not_to be_nil
end

When("I search for an SMS sent to {string}") do |phone_number|
  criteria = Mailosaur::Models::SearchCriteria.new
  criteria.sent_to = phone_number

  @message = @client.messages.get(@server_id, criteria)
end

Then("that SMS should be sent from {string}") do |expected_number|
  expect(@message).not_to be_nil
  expect(@message.from.first.phone).to eq(expected_number)
end
@given('the Mailosaur API client is setup for SMS')
def step_impl(context):
    global apiKey
    global serverId
    global mailosaurClient
    apiKey = os.getenv('MAILOSAUR_API_KEY')
    serverId = os.getenv('MAILOSAUR_SERVER_ID')
    assert apiKey, 'MAILOSAUR_API_KEY environment variable must be set'
    assert serverId, 'MAILOSAUR_SERVER_ID environment variable must be set'
    mailosaurClient = MailosaurClient(apiKey)

@when('I search for an SMS sent to "{toNumber}"')
def step_impl(context, toNumber):
    global message
    criteria = SearchCriteria()
    criteria.sent_to = toNumber
    message = mailosaurClient.messages.get(serverId, criteria)
    assert message, 'Message not found'
 
@then('that SMS should be sent from "{fromNumber}"')
def step_impl(context, fromNumber):
    assert message.sender[0].phone == fromNumber, 'Sender phone number does not match'[Given("the Mailosaur API client is setup for SMS")]
public void GivenTheMailosaurApiClientIsSetup()
{
    var apiKey = _config["appSettings:MAILOSAUR_API_KEY"];
    serverId = _config["appSettings:MAILOSAUR_SERVER_ID"];

    Assert.NotNull(apiKey);
    Assert.NotNull(serverId);
    Assert.NotEmpty(apiKey);
    Assert.NotEmpty(serverId);

    mailosaurClient = new MailosaurClient(apiKey);
}

[When("I search for an SMS sent to {string}")]
public void WhenISearchForAnSmsSentTo(string toNumber)
{
    // Setup search criteria
    var searchCriteria = new SearchCriteria()
    {
        SentTo = toNumber
    };

    // Search for the message
    message = mailosaurClient!.Messages.Get(serverId, searchCriteria);
}

[Then("that SMS should be sent from {string}")]
public void ThenThatSmsShouldBeSentFrom(string fromNumber)
{
    Assert.Equal(fromNumber, message.From[0].Phone);
}

This example will search for the phone number that a message was sent to, but you can also search using any of the below criteria:

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

Find an SMS message

When searching for a specific message within your inbox, it’s always better to use messages.get(), as it will automatically wait for messages to arrive and return the full message result.

// Search for the message
const message = await mailosaurClient.messages.get("SERVER_ID", {
  sentTo: "123456789", // Phone number
});

console.log(message.text.body);
MessageSearchParams params = new MessageSearchParams();
params.withServer("SERVER_ID");

SearchCriteria searchCriteria = new SearchCriteria();
searchCriteria.withSentTo("123456789"); // Phone number

Message message = mailosaurClient.messages().get(params, searchCriteria);

System.out.println(message.text().body());
criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = "123456789" # Phone number

message = mailosaurClient.messages.get("SERVER_ID", criteria)

puts(message.text.body)
criteria = SearchCriteria()
criteria.sent_to = "123456789" # Phone number

message = mailosaurClient.messages.get("SERVER_ID", criteria)

print(message.text.body)var criteria = new SearchCriteria() {
    SentTo = "123456789" // Phone number
};

var message = mailosaurClient.Messages.Get("SERVER_ID", criteria);

Console.WriteLine(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, 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
const message = await mailosaurClient.messages.get("SERVER_ID", {
  sentTo: "123456789",
}, {
  receivedAfter: yesterday
});
// Calculate a timestamp for yesterday
Calendar calendar = Calendar.getInstance();
calendar.add(Calendar.DAY_OF_YEAR, -1);
long yesterday = calendar.getTimeInMillis();

// Use this timestamp in the search
MessageSearchParams params = new MessageSearchParams();
params.withServer("SERVER_ID");
params.withReceivedAfter(yesterday);

SearchCriteria searchCriteria = new SearchCriteria();
searchCriteria.withSentTo("123456789");

Message message = mailosaurClient.messages().get(params, searchCriteria);# Calculate a datetime for yesterday
yesterday = Date.today - 1

criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = "123456789"

# Use this timestamp in the search
message = mailosaurClient.messages.get("SERVER_ID", criteria, received_after: yesterday)# Calculate a datetime for yesterday
yesterday = datetime.today() - timedelta(days=1)

criteria = SearchCriteria()
criteria.sent_to = "123456789"

# Use this timestamp in the search
message = mailosaurClient.messages.get("SERVER_ID", criteria, received_after=yesterday)// Calculate a datetime for yesterday
var yesterday = DateTime.Today.AddDays(-1);

var criteria = new SearchCriteria() {
    SentTo = "123456789"
};

// Use this timestamp in the search
var message = mailosaurClient.Messages.Get("SERVER_ID", criteria, receivedAfter: yesterday);

“No matching messages” troubleshooting

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

Ensure that the 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 to learn how to override this.
Check that you have correctly set the sent to parameter in your search criteria.

It is usually better to use messages.get()

The list and search methods will only return basic summaries, meaning several properties (including the message body) are not included. To get this data, you need to use .getById(). Instead, we recommend using the messages.get() as this automatically waits for a matching result and returns the message in the result.

##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.
const result = await mailosaurClient.messages.search(
  "SERVER_ID",
  {
    sentTo: "123456789",
  },
  {
    page: 0,
    itemsPerPage: 10,
  }
);

// Get the most recent message (the first one in the list)
const latestMessage = result.items[0];

// Get the full message object
const message = await mailosaurClient.messages.getById(latestMessage.id);

console.log(message.text.body);
// Search for all messages sent to 123456789.
SearchCriteria criteria = new SearchCriteria();
criteria.withSentTo("123456789");

// Limit results to the first 10 matches only.
MessageSearchParams params = new MessageSearchParams();
params.withServer("SERVER_ID")
  .withPage(0)
  .withItemsPerPage(10);

MessageListResult result = mailosaurClient.messages().search(params, criteria);

// Get the most recent message (the first one in the list)
MessageSummary latestMessage = result.items().get(0);

// Get the full message object
Message message = mailosaurClient.messages().getById(latestMessage.id());

System.out.println(message.text().body());
# Search for all messages sent to 123456789.
criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = "123456789"

# Limit results to the first 10 matches only.
result = mailosaurClient.messages.search("SERVER_ID", criteria, page: 0, items_per_page: 10)

# Get the most recent message (the first one in the list)
latest_message = result.items[0]

# Get the full message object
message = mailosaurClient.messages.get_by_id(latest_message.id)

puts(message.text.body)
# Search for all messages sent to 123456789.
criteria = SearchCriteria()
criteria.sent_to = "123456789"

# Limit results to the first 10 matches only.
result = mailosaurClient.messages.search("SERVER_ID", criteria, page=0, items_per_page=10)

# Get the most recent message (the first one in the list)
latest_message = result.items[0]

# Get the full message object
message = mailosaurClient.messages.get_by_id(latest_message.id)

print(message.text.body)// Search for all messages sent to 123456789.
var criteria = new SearchCriteria() {
    SentTo = "123456789"
};

// Limit results to the first 10 matches only.
var result = mailosaurClient.Messages.Search("SERVER_ID", criteria, page: 0, itemsPerPage: 10);

// Get the most recent message (the first one in the list)
var latestMessage = result.Items[0];

// Get the full message object
var message = mailosaurClient.Messages.GetById(latestMessage.Id);

Console.WriteLine(message.Text.Body);

List current inbox contents

See a full list of everything currently in your inbox.

// List the most recent messages
const result = await mailosaurClient.messages.list("SERVER_ID");

// Get the most recent message (the first one in the list)
const latestMessage = result.items[0];

// Get the full message object
const message = await mailosaurClient.messages.getById(latestMessage.id);

console.log(message.text.body);
// List the most recent messages
MessageListParams params = new MessageListParams();
params.withServer("SERVER_ID");
MessageListResult result = mailosaurClient.messages().list(params);

// Get the most recent message (the first one in the list)
MessageSummary latestMessage = result.items().get(0);

// Get the full message object
Message message = mailosaurClient.messages().getById(latestMessage.id());

System.out.println(message.text().body());
# List the most recent messages
result = mailosaurClient.messages.list("SERVER_ID")

# Get the most recent message (the first one in the list)
latest_message = result.items[0]

# Get the full message object
message = mailosaurClient.messages.get_by_id(latest_message.id)

puts(message.text.body)
# List the most recent messages
result = mailosaurClient.messages.list("SERVER_ID")

# Get the most recent message (the first one in the list)
latest_message = result.items[0]

# Get the full message object
message = mailosaurClient.messages.get_by_id(latest_message.id)

print(message.text.body)// List the most recent messages
var result = mailosaurClient.Messages.List("SERVER_ID");

// Get the most recent message (the first one in the list)
var latestMessage = result.Items[0];

// Get the full message object
var message = mailosaurClient.Messages.GetById(latestMessage.Id);

Console.WriteLine(message.Text.Body);

Common test scenarios

Testing basic properties

Once you have fetched an SMS, you can simply test the properties of that text:

// Test sender information
assertEquals("Support", message.from().get(0).name());
assertEquals("654321", message.from().get(0).phone());

// Test recipient information
assertEquals("John Smith", message.to().get(0).name());
assertEquals("1234567890", message.to().get(0).phone());# Test sender information
self.assertEqual("Support", message.sender[0].name)
self.assertEqual("654321", message.sender[0].phone)

# Test recipient information
self.assertEqual("John Smith", message.to[0].name)
self.assertEqual("1234567890", message.to[0].phone)// Test sender information
Assert.Equal("Support", message.From[0].Name);
Assert.Equal("654321", message.From[0].Phone);

// Test recipient information
Assert.Equal("John Smith", message.To[0].Name);
Assert.Equal("1234567890", message.To[0].Phone);# Test sender information
assert_equal("Support", message.from[0].name)
assert_equal("654321", message.from[0].phone)

# Test recipient information
assert_equal("John Smith", message.to[0].name)
assert_equal("1234567890", message.to[0].phone)// Test sender information
expect(message.from[0].name).toBe("Support");
expect(message.from[0].phone).toBe("654321");

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

Testing SMS contents

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

System.out.println(message.text().body()); // "Hi Jason, ..."print(message.text.body) # "Hi Jason, ..."Console.WriteLine(message.Text.Body); // "Hi Jason, ..."puts(message.text.body) # "Hi Jason, ..."console.log(message.text.body); // "Hi Jason, ..."

Testing links

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

// How many links?
System.out.println(message.text().links().size()); // 2

Link firstLink = message.text().links().get(0);
assertEquals("Google Search", firstLink.text());
assertEquals("https://www.google.com/", firstLink.href());# How many links?
print(len(message.text.links)) # 2

first_link = message.text.links[0]
self.assertEqual("Google Search", first_link.text)
self.assertEqual("https://www.google.com/", first_link.href)// How many links?
Console.WriteLine(message.Text.Links.Count); // 2

var firstLink = message.Text.Links[0];
Assert.Equal("Google Search", firstLink.Text);
Assert.Equal("https://www.google.com/", firstLink.Href);# How many links?
puts(message.text.links.length) # 2

first_link = message.text.links[0]
assert_equal("Google Search", first_link.text)
assert_equal("https://www.google.com/", first_link.href)// How many links?
console.log(message.text.links.length); // 2

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

Testing verification codes

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

Code otp = message.text().codes().get(0);
assertEquals("456812", otp.value());otp = message.text.codes[0]
self.assertEqual("456812", otp.value)var otp = message.Text.Codes[0];
Assert.Equal("456812", otp.Value);otp = message.text.codes[0]
assert_equal("456812", otp.value)const otp = message.text.codes[0];
expect(otp.value).toBe("456812");

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 this. When you reply, the SMS is sent back to the phone number it was originally sent to Mailosaur from:

MessageReplyOptions options = new MessageReplyOptions();
options.withText("FYI");

mailosaur.messages().reply("MESSAGE_ID", options);options = MessageReplyOptions(text="FYI")

mailosaur.messages.reply("MESSAGE_ID", options)mailosaur.Messages.Reply("MESSAGE_ID", new MessageReplyOptions()
  {
      Text = "FYI"
  }
);options = Mailosaur::Models::MessageReplyOptions.new()
options.text = "FYI"

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

Parameter	Description
text	Any additional text content to include in the reply
html	Any additional HTML content to include in the reply
subject	Optionally override the default subject line
attachments	Optional attachments (see 'include attachments' above)

Forwarding a message to email

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 you can send email to it:

MessageForwardOptions options = new MessageForwardOptions();
options.withTo("verified-address@example.com")
  .withText("FYI");

mailosaur.messages().forward("MESSAGE_ID", options);recipient = "verified-address@example.com"
options = MessageForwardOptions(recipient, text="FYI")

mailosaur.messages.forward("MESSAGE_ID", options)mailosaur.Messages.Forward("MESSAGE_ID", new MessageForwardOptions()
  {
      To = "verified-address@example.com",
      Text = "FYI"
  }
);options = Mailosaur::Models::MessageForwardOptions.new()
options.to = 'verified-address@example.com'
options.text = 'FYI'

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

Parameter	Description
to	The email address to which the message 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

Deleting messages

Deleting an individual message

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

await mailosaurClient.messages.del("MESSAGE_ID");mailosaurClient.messages().delete("MESSAGE_ID");mailosaurClient.messages.delete("MESSAGE_ID")mailosaurClient.messages.delete("MESSAGE_ID")mailosaurClient.Messages.Delete("MESSAGE_ID");

Delete all messages

Permanently deletes all messages held in the specified server/inbox. Also deletes any attachments related to each message. This operation cannot be undone:

await mailosaurClient.messages.deleteAll("SERVER_ID");mailosaurClient.messages().deleteAll("SERVER_ID");mailosaurClient.messages.delete_all("SERVER_ID")mailosaurClient.messages.delete_all("SERVER_ID")mailosaurClient.Messages.DeleteAll("SERVER_ID");

SMS testing with Cucumber

What you’ll find in this guide

What you’ll need

Basic usage

Find an SMS message

Time range for searching

“No matching messages” troubleshooting

It is usually better to use `messages.get()`

List current inbox contents

Common test scenarios

Testing basic properties

Testing SMS contents

Testing links

Testing verification codes

Replying to an SMS message

Forwarding a message to email

Deleting messages

Deleting an individual message

Delete all messages

See also

SMS testing with Cucumber

What you’ll find in this guide

What you’ll need

Basic usage

Find an SMS message

Time range for searching

“No matching messages” troubleshooting

It is usually better to use messages.get()

List current inbox contents

Common test scenarios

Testing basic properties

Testing SMS contents

Testing links

Testing verification codes

Replying to an SMS message

Forwarding a message to email

Deleting messages

Deleting an individual message

Delete all messages

See also

It is usually better to use `messages.get()`