Appium Tip #22: How to Deploy Image Recognition in Your Appium Tests

Server-side vs. Client-Side Run with Appium

This is the 22nd blog in our 37 Things You Should Know About Appium blog series and this time we’ll be focusing on how to use image recognition when testing mobile apps, games and even web sites. The image recognition has been lately one of the most prominent approach for enabling test automation for mobile apps and games that have graphics content or other content that regular test automation frameworks may not be able to identify with IDs, description or object characters.


Download Our Appium Step-by-Step Tutorial to Properly Set Up Your Appium Testing Environment for Image Recognition

We have recently updated our Image Recognition sample to be more diverse and robust. There are now instructions on how to launch the image recognition tests in your local environment, as a Client Side Appium testrun and as a Server Side Appium testrun. The dependencies are now also using the latest version of testdroid-appium-driver, which includes the usage of Appium java-client 3.2.0. 

In other words, the underlying libraries are now more up to date and should help you get your tests running more fluidly and with less problems from old known bugs!

The README may seem a bit more complicated now with instructions to all these three types of test execution included, so do take your time when looking through it. It also includes information on how to install the Image recognition libraries to your own machine, so make sure to follow it until the end before attempting to run the tests locally.


Running Appium Image Recognition Tests from Command Line

Once you have installed all the dependencies, you’re ready to setup the project for testing! For local tests, remember to set your Appium server ready as well. Copy the file into a file in the project root directory and uncomment the example lines depending on the type of test you’ll be running:

Local test:

## Android
## iOS
# appium.appFile=../apps/builds/BitbarIOSSample.ipa

Once the are set, use a maven test command with correct test class specified in “-Dtest” flag to launch the tests:

mvn -Dtest=iOSSample test


mvn -Dtest=AndroidSample test

Client Side test:

Uncomment the Client Side example lines of and also set your Testdroid Cloud user credentials:

testdroid.username=<add username here>
testdroid.password=<add password here>

Configure the following parameters based on which platform and device you’ll be using for testing:

## Android
testdroid.project=Client side Android
testdroid.device=Samsung Galaxy Nexus GT-I9250 4.2.2
## iOS
testdroid.project=Client side iOS
testdroid.device=Apple iPhone 5 A1429 9.2.1

Finally, run your tests with maven using the same logic as with local tests:

mvn -Dtest=<TestClass> test

In addition, if OpenCV is not installed using Brew, the java.library.path needs to be provided on the command line. In order to get this done, execute the following line with OpenCV java library path in place:

mvn -Djava.library.path=<java-lib-path> -Dtest=<TestClass> test

To get any additional Testdroid properties configured, check out Testdroid-Appium-Driver’s

To select device you want to run your test on, you can use either testdroid.device variable in the properties file or alternatively give the device name via command line parameter: (e.g. testdroid device name = “Apple iPhone 6 A1429 9.2.1”)

mvn -Dtestdroid.device="testdroid device name" -Dtest=<TestClass> test

After the test run is finalized (you need to wait until the device run is finalized) you’ll get the results, screenshots and all the other assets from the test run under ./target/reports/.

Running Appium Image Recognition Tests on Server-Side

You will need a Testdroid project of type CALABASH ANDROID or CALABASH IOS, which we have pre-configured for you to act as a Server-Side Appium project. If this has not been done already, please contact or your Testdroid contact person to get a project configured.

Once you have a properly configured Testdroid project available, use the provided scripts to create the test zip from your project:

## For ANDROID -
zip -r pom.xml src akaze/linux akaze/LICENSE lib/testdroid-appium-driver-1.2.0.jar queryimages
## For iOS -
zip -r pom.xml src akaze/mac akaze/LICENSE lib/testdroid-appium-driver-1.2.0.jar queryimages

These lines are included as shell script files and both and can be found from root of the project.

After you have executed these scripts, you should have a properly built test zip file and the application apk/ipa file ready for a test run. Then create a new testrun in your pre-configured Testdroid Cloud project, upload your APK or IPA as well as test zip file using the test run creation wizard. Choose a device group where your Appium test will be executed (you can include any number of devices for your test run and test will run simultaneously on these devices). The last page of the test run creation wizard includes the setting of max timeout for your tests, so make sure it is set high enough for your tests (default is 10 minutes).

Changing the Test Class Name

At any time if you change the name of your Android or iOS test class, you will need to update it to the and/or TEST and JUNIT variables as appropriate:

# Name of the desired test suite and optionally specific test case, eg: AndroidSample#mainPageTest
# JUnit file wont have the #caseName ending


Testdroid appium driver is a Java project, which utilizes the Testdroid API client for java and Appium’s java-client. The major benefits of using the driver is the ready-made logic for app upload to Testdroid Cloud, taking of Screenshots as well as simplifying the editing of desired capabilities. The, which is located at the root of the project, is the only file you need to edit when desired capabilities need changing.

Getting Started With Your Own Tests on Top

When you’re ready to start tweaking the actual tests, you will mostly working on the test files in src/test/java/.

Our collection of helper methods in src/main/java/ and src/main/java/ should also be a tremendous help when looking for different ways to make use of the image recognition data.

Happy Testing!

The Beginner’s Guide of Using Appium for Mobile App Testing

Learn all the basics about Appium, how to set it up and how to use it for mobile app testing.