AppiumLibrary: A Detailed How-To Guide
Mobile GUI testing doesn't have to be hard work.
AppiumLibrary makes it easy to drive a mobile app from Python. It lets you drive your apps inside a test script with a simple syntax in scripts that run from inside your IDE or your build pipelines.
Let's look at AppiumLibrary and Robot. We'll go over what these tools are, and then run them against Android sample code.
What is AppiumLibrary?
What is Appium?
Before we can talk about AppiumLibrary, we need to cover the tool it's designed to interface with, Appium, as well as the Robot Framework it connects to.
Appium is an open-source toolkit for automating applications. It can drive web or mobile apps, with support for:
- iOS web (Safari) and mobile apps
- Android web (Chrome) and mobile apps
- Windows desktop apps.
So, you can use Appium with native or hybrid applications.
Appium abstracts the differences between these applications with a client-server architecture, so you can write test code using the same API for all these platforms. More importantly, Appium works on compiled code. You don't have to include extra libraries in your code to test with Appium.
Appium is designed with this philosophy:
Appium is built on the idea that testing native apps shouldn't require including an SDK or recompiling your app. And that you should be able to use your preferred test practices, frameworks, and tools. Appium is an open source project and has made design and tool decisions to encourage a vibrant contributing community.
What's Robot Framework?
Robot Framework is a generic Python framework for automation. You can use it for test automation and for robotic process automation (RPA). Robot's developers made it easy to add extensions, so a library that connects it to Appium makes sense.
Robot scripts are exceptionally easy to write. It uses a human-friendly syntax that's easy to read and maintain. This, combined with a tremendous ecosystem, makes Robot a popular choice for testing.
So, What's AppiumLibrary?
AppiumLibrary is a Python library that connects Appium to the Robot Framework. It uses Appium to communicate with Android and iOS applications from Robot's test scripts. So, you can use Robot's simple language to drive mobile apps and verify their behavior.
It's a lot easier to show the tell here, so let's get to work with a few tests.
How Do I Use AppiumLibrary in Robot Framework?
Using AppiumLibrary with Robot Framework is straightforward, if not simple. Let's go over setting up a development environment for testing an Android application.
Android Sample Code
Before we start, you'll need to have Android Studio installed.
Open the IDE and create a new project. Use the Basic Activity example.
Give your application a name and select the latest library versions.
Build the app, and set up an emulator to run it. Make sure everything's working before you continue.
You should see this screen on startup.
And this is when you click the NEXT button.
Install and Configure Appium
Before you can run tests, you need to install an Appium server and a driver for the applications you want to test. The server receives requests from the Appium library, and uses the driver to control your application under test.
You can install the server with Appium Desktop or with npm, depending on what's easiest for you.
When you use Appium with Android Studio, you don't need to install a separate driver. Appium will find the Android emulator you have configured for your project automatically.
Create a Virtual Environment
Next, you'll need to install the Python libraries for Robot and Appium. Start with a virtual environment so you can maintain the dependencies for testing separately from your other python applications.
You can install this virtual environment anywhere, but inside the working directory of your Android project is a great place.
This example uses virtualenv, but you can use whichever Python tool you prefer.
Next, activate the environment before you install any libraries.
Install Robot Framework
Now, install Robot with pip. The library name is robotframework.
Install Appium Library
Finally, install robotframework-appiumlibrary. This library has several dependencies and will take a few moments to install.
That takes care of the prerequisites. Let's run some tests.
Testing Android with Appium Library and Robot Framework
So, now you've got an application and the tools to test it. Let's start with a simple script.
Robot Script Setup
Create a directory inside your project to store your test scripts. For this example, I'll use the directory name robot.
For these scripts, we'll borrow from the sample code here for the structure.
This script, stored in a file named resource.robot, sets some default variables for the tests, and declares a function that opens the application under test.
Let's go over each line:
Lines #2 and #3 tell Robot we're using its built in library, along with Appium.
Next, we set five environment variables that are key to running a Robot script with AppiumLibrary.
- ANDROID_AUTOMATION_NAME - the Appium driver to drive the application under test. UIAutomator2 is the default interface for Android applications.
- ANDROID_APP - the path to the Android Package (APK) to run for the test. Appium runs compiled code. It will pass this package to the emulator.
- ANDROID_PLATFORM_NAME - We're running an Android application on the "standard" platform.
- ANDROID_PLATFORM_VERSION - set the platform version here.
- ANDROID_APP_PACKAGE - the application package name.
Then, the file defines Open Android Test App to load applications. This function accepts an activity as its only argument and loads it from the application defined in ANDROID_APP.
By storing these variables in a separate file, we can reuse them in scripts. Let's see how.
Initial Test Script
Here's the first test:
On line #2, we load the first file, so the variables and Open Android Test App function are available to the script. Then we define the default test teardown procedure and start the tests.
A test case starts with a text description, so line #7 explains what this test does:
- Load .MainActivity from the test application.
- Wait for a button to load with an id of button_first.
- Verify that the button text is NEXT.
- Take a screenshot and save it as first_test.png.
Before we run the test, note something in the file: there are double spaces after the Robot keywords. This helps Robot discern between keywords, which can have spaces in them, and arguments.
Make sure your Appium server is running, and execute the test script with robot.
One test ran and passed.
Let's look at the screenshot.
It's the first and only screen that loaded during the test.
The script used JSON XPath identifiers to specify the button. Let's inspect them before finishing with a more complicated test.
This statement is built from the following components:
- xpath= - Appium uses a few different syntaxes for finding components. This tells them you're using XPath. While it's a little verbose, XPath is very precise.
- // - two slashes mean anywhere in the application. If you're using unique component ids everywhere, this wildcard syntax will save you a lot of work.
- android.widget.Button - finally we get to the component. This is the Android class name.
- [@resource-id,'button_first'] - find a button with a resource id of button_first.
The XPath syntax implemented in Appium is very powerful and can use more criteria than resource ids. Start here to learn more.
More Test Cases
Let's expand on the test.
Unit tests should be granular, so this test breaks down each button click and its result into a specific test.
The click element keyword clicks the button specified by the XPath identifier.
Run this test:
We see each test run and pass.
While that second test had a lot more going on, it was a little repetitive and relied purely on the button test. Let's take advantage of XPath a bit more.
Here's a modified version of the script:
Now, after we click a button, we wait for the text in the toolbar to change:
wait until page contains element //*[contains(@text, "Second Fragment")]
But instead of matching on a Java class name, we're using a wildcard.
- // - we don't have to specify xpath here.
- * - any object that matches the following criteria. Be careful!
- [contains()] - this is an XPath function that will match an object that contains the criteria passed to it.
- @text, "Second Fragment" - text that matches the second argument.
Run this script and you'll see the same results.
AppiumLibrary And Robot For Powerful GUI Tests
We've set up an Android test environment and used it to run Appium tests via the Robot framework. Then, we saw how easy it is to drive Appium tests from Robot, using a clear and simple test syntax. Finally, we spent a little extra time using Appium's robust XPath implementation to target specific GUI elements and activate them or check their values.
Now that you're familiar with AppiumLibrary and Robot, use them to step up your mobile testing today.
Click here to learn more.