Testing email and SMS with Appium

Are you looking to test the sign-up, log-in, and two-factor authentication flows of your mobile app? Appium and Mailosaur form the right combo to help you with this task.

In this guide, we take a sample Android app and show you how to test it with Appium. We then provide examples of how you can combine Appium with Mailosaur to seamlessly test email and SMS-related functionality in your Android (or iOS) application.

What is Appium?

Appium is a test automation framework known for its ability to test mobile applications. The tool automates testing for three basic types of apps:

Native mobile apps are those written using the native libraries of iOS and Android mobile devices.
Mobile web applications are those delivered through a mobile browser. Appium supports Chrome or the built-in Browser app on Android and Safari on iOS.
Hybrid apps, while technically web applications, are those resulting from combining the attributes of a native app with those of a mobile web app.

Internally, Appium is a server that exposes an API similar to the standard Selenium WebDriver API, but with added functionality that’s focused on mobile platforms. To interact with Appium, you can use any of the Appium client libraries, which are available in languages like Java, Python, C#, Ruby, JavaScript, and PHP.

Once you send a command with one of the client libraries, Appium will translate it for the particular platform you’re testing on. For example, if you’re testing on iOS, Appium will translate your test commands to native iOS XCUITest actions under the hood. Appium will then return the rest of the action back into your test code.

Crucially, Appium is open-source, and its cross-functionality allows you to use the same base code to create tests for multiple platforms, including Android and iOS.

How to get started with Appium on your device

To get started with Appium, you’ll first need to install and configure the Appium service. If you’re new to Appium, simply follow the steps below.

But if you already have the framework installed, jump straight into the next section to see our examples of email and SMS testing.

Install Appium

You can install Appium onto your machine in one of two ways.

With Node.js and NPM on your machine, open up a command prompt and type in the following:

npm install -g appium

This command will install the latest version of the Appium server.

Alternatively, you can install Appium with Appium Desktop, an executable that lets you run the Appium server straight from your desktop.

Download drivers

Each mobile operating system has unique drivers that give you access to specific automation technologies. These drivers are necessary to support automation on a particular platform. Appium recommends the XCUITest Driver for iOS and the UiAutomator2 Driver for Android.

In our example, we’ll use Android, so we’ll need to ensure that all tools like Android Studio are installed and ready to go. By installing Appium itself, we don’t need to worry about separately installing the Appium UiAutomator2 driver, which is a dependency of the framework.

Set up an Appium Client

The Appium framework we downloaded in step one is the server that Appium uses to communicate with your mobile device. To be able to generate an automated test, you’ll need to use an Appium Client.

Effectively, an Appium Client is a library extension that adds the necessary functionality to whatever coding platform you’re using to write your automated tests. In order for your code to interface with Appium, it’s imperative to download the appropriate client.

In our example, we’ll use WebDriverIO as the client. When using WebDriverIO, our Android tests will be written in JavaScript. If you prefer a different language for writing your tests, you can go with any of the other Appium client options.

Start up the Appium Server

With the Appium server and client in place, the next step is to fire up the server you’ll be testing through.

If you installed Appium from NPM, you’ll need to run the following command from your command prompt:

appium

Users that went the Appium Desktop route simply need to launch the programme and click the ‘Start Server’ button.

Note: the shell where you run Appium needs to have the ANDROID_HOME environment variable set up for the Android tests to work correctly:

On Windows, this path is usually C:\Users\<username>\AppData\Local\Android\sdk;
On macOS, this path is normally ~/Library/Android/sdk;
On Linux, the path would be ~/Android/Sdk.

If you’re getting any errors related to environment variables when using Appium, check out the Android documentation on setting up the environment correctly.

When Appium starts up, it will display an introductory prompt:

$ appium
[Appium] Welcome to Appium v1.21.0
[Appium] Appium REST http interface listener started on 0.0.0.0:4723

Write your code

With the server humming in the background, you’ll want to switch your attention back to your IDE or text editor and write the code you’re planning to test on your mobile device. In our example, this will be the WebDriverIO code. We’ll cover this in greater detail in the next section.

Hook up your mobile device (or mobile simulator/emulator)

You’ll need to hook up your mobile device before you can run your test on it. Assuming your Appium server and code are on a computer, you’ll simply need to connect your mobile device using a USB cable. If you’re looking to test in an Android emulator or iOS simulator, you’ll need to start those virtual devices.

Run and verify

With all the pieces linked together, you’ll simply need to run your test code and check the test output for the test results. In our example, we’ll be running the WebDriverIO test code.

Let’s now take a look at the internals of an Appium Android test.

Using the Mailosaur email and SMS API with Appium

Testing the email and SMS flows of your mobile app is a great way to ensure consistent experience for your mobile app users. In two examples below, we'll use Mailosaur to help us conduct both email and and SMS testing. Mailosaur offers a Node.js library that we’ll use to reference Mailosaur information directly in our WebDriverIO test code. Appium won’t need to interface with Mailosaur directly.

Let’s start by testing the email capability.

Example: email testing with Appium

We start off by including all the necessary dependencies. In this case, we only need WebDriverIO (that’s going to be our Appium driver, as we mentioned above), assert for concise checking of test conditions, and the Mailosaur Node.js client library.

// index.js

const wdio = require("webdriverio");
const assert = require("assert");
const MailosaurClient = require("mailosaur");

We then define the options for our Appium test suite. In this example, we’re going to be testing on Android 11 using the Android Emulator. We also specify the path to the APK file where the resulting app build is located. The automation framework that we’ll be using is UiAutomator2; it’s the recommended option when testing on Android with Appium.

const opts = {
  path: "/wd/hub",
  port: 4723,
  capabilities: {
    platformName: "Android",
    platformVersion: "11",
    deviceName: "Android Emulator",
    app: "/Users/wizard/Downloads/mailosaur-app-debug.apk",
    appPackage: "io.appium.android.apis",
    appActivity: ".MainActivity",
    automationName: "UiAutomator2"
  }
};

The core logic of our test suite in this example lies in the main function. We first initialise the WebDriverIO client with the options we configured. At this point, Appium and WebDriverIO will take care of launching the Android Emulator and loading our app onto it.

async function main () {
  const client = await wdio.remote(opts);

Our app contains three fields that can be filled out. We reference them by the identifiers used in the activity_main.xml file in our Android project. We then use the setValue directive to have Appium fill out those fields with pre-defined values.

const firstName = await client.$("com.mailosaur:id/firstName");
await firstName.setValue("John");
const lastName = await client.$("com.mailosaur:id/lastName");
await lastName.setValue("Smith");
const email = await client.$("com.mailosaur:id/emailAddress");
await email.setValue("android@abcd1234.mailosaur.net");

After filling out the sign-up information, we tell Appium to click the ‘Submit’ button:

await client.$("android.widget.Button").click();

At this stage, the account information will be submitted by the app to the back-end service. We can now check whether the sign-up has generated an email as we expected. We initialise the Mailosaur client using our API key and supply the Mailosaur server ID:

const mailosaur = new MailosaurClient("API_KEY");
const serverId = "abcd1234";
const serverDomain = "abcd1234.mailosaur.net";

We then define the criteria by which we’ll search for emails. Here, we’re using an android@ prefix for emails that we send from our Android test suite. Other test suites (say, iOS or web) can use other prefixes, and Mailosaur will still route all those usernames to our test inbox.

const searchCriteria = {
  sentTo: "android@" + serverDomain
};

Now, we’re ready to fetch the relevant message using the Mailosaur library:

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

Our test is successful if the command returns a valid message. We can check whether the message is valid using the assert call:

assert(message);

Regardless of the outcome, we need to clean up the test session to prepare the Android Emulator and the Appium server for the next run. This wraps up our definition of the main function:

  await client.deleteSession();
}

Finally, we call the main function to actually run all tests:

main();

To run the test suite, we start two processes:

in one shell, we start the Appium process by running appium;
in the second shell, we invoke our test suite by running the node index.js command.

That’s it, our Appium email test suite is now up and running!

Example: SMS testing with Appium

The key difference when testing SMS with Mailosaur is that the search criteria for SMS messages won’t include any email addresses. Instead, we need to supply a phone number by which to search messages:

const mailosaur = new MailosaurClient("API_KEY");
const serverId = "abcd1234";
const serverDomain = "abcd1234.mailosaur.net";

const searchCriteria = {
  sentTo: "1234567890"
};

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

Mailosaur provides us with a test phone number, and in our SMS test we’ll need to make sure that that’s the number that gets entered into our application.

Email and SMS testing with Mailosaur

Mailosaur works seamlessly with the Appium framework, allowing you to capture, test, and analyse email and SMS messages. We have a wealth of information to help you learn to use Mailosaur to verify your code’s functionality.