What is Appium?
Appium is an open-source cross-platform tool for automating native mobile web and hybrid applications for iOS, Android, and Windows desktop platforms. It allows you to write tests against multiple platforms, such as iOS, Android, and Windows, using the same API, same classes, and the same structure.
Appium contains two parts: client and server. By connecting between the client and server, we can start a session to open a connection between the client and the server. Then, we’ll have the desired capabilities (or configuration) to be able to send it via the session to the server.
We are using the client from our test script and connecting it to the Appium server to be able to open the session between the client and the server, and then using the desired capabilities or specific configuration to start our session with Appium.
In the client/server architecture, Appium is a web server that exposes a REST API.
Getting started with Appium
To get started with Appium for Android applications, you should prepare your local machine with the following requirements:
- macOS High Sierra or Mojave or Windows 10
- NodeJS and NPM
- Java +8
- Android Studio includes Android SDK +16 (Android Emulator and command-line tools)
- Appium Desktop
- Appium Doctor
- Maven or Gradle for your automation project
More information about installing Appium can be found here.
If you don’t have an Android application, you can fork the Sunflower app from GitHub. Sunflower app is a gardening app illustrating Android development best practices with Android Jetpack.
With Appium, you can test automation scripts or projects that are stand-alone, not like Espresso inside the Android project. I created a Maven project (you can create a Gradle one if you’d like) with the following structure:
POM.xml: I added the project dependencies such as testNG, Appium and created a Maven profile to run the tests from the command line with the maven surefire plugin.
Android_testng.xml: I added my testcase to run it with the maven command line.
FirstAndroidTest.java: it’s the test class where I added my test case and Appium desired capabilities with the following scenario:
- Open App
- Click on Plant List
- Click on My Garden
- Click on Add Plant button
- Click on Avocado
- Click Back
- Click on My Garden and assert that the plant name is exist
The full project can be found on GitHub.
The final result will look like this:
Appium Tests integration with Bitrise CI
After we successfully run our tests locally, it’s time to integrate our tests with our Android CI using Bitrise. But first, we need to do a small change in our application path, because locally, we’re using the absolute path of the app, but with Bitrise or our CI server, it should be as an environment variable.
So inside our test script we will change the app path to Bitrise app path to look like this:
Now, the automation project is ready and will start adding it to our existing Android Workflow.
I will assume that you already have your android CI Workflow in Bitrise like the following, but if you need to know how to add it, you can check this link.
Now I need to configure the CI Workflow with the new steps required for Appium:
1. Add a Script step to clone the Appium repository.
2. As we know, we are using Appium Desktop as a server and inspector locally, but with CI servers we can’t use it, so we need to run Appium Server from the command line. Here I’ll add another Script step to install and run Appium server in the background.
You will notice that I’m passing --log appium.log with the appium command to export the server log as a .txt file for more debugging purposes if any tests failed.
3. Add the AVD Manager Step to create an Android Emulator to use it with your tests. You can choose any API level. For example, you can change it to 28 but you need to change it in the Appium desired capabilities and commit the change to your GitHub repository as well.
4. Add the Wait for the Android emulator Step and wait for the emulator to be ready before running our tests on it.
5. Add the Script Step to run the UI tests. You need to switch inside the automation project to be able to run the maven command.
6. Add the Script Step to copy the appium log file to the Deploy Directory of Bitrise to be able to find it in the artifacts tab.
7. Add a Step to Export the test results to the Bitrise Test Report Add-on and specify the test results search pattern like this: (*/target/surefire-reports/junitreports/*)
The final Workflow will look like the following:
Notice that we didn’t add any prerequisites for our CI server like Java, NodeJS, npm, or Android SDK. What we need is to install Appium and run the server just like that.
To run the Workflow, go to the application page and click on the Start/Schedule Build button and select the Workflow then click on the Start Build button.
If everything runs successfully, you will find a green build at the end and an email notification with the build status as well.
What about the Artifacts?
To check the test results and the appium log file you can click on the Test Report add-on, and for appium log and the app.apk file you can click on Apps & Artifacts tab.
Congratulations! 🎉 You have successfully integrated your Appium Android UI tests with Bitrise.
If you’d like to find out more about how Bitrise can help you release better apps, faster, you can also request a demo here.