How to: Automated Tests for Unity Mobile Apps with Appium and AltUnity

[Update 2022] AltUnity Tester becomes AltTester Unity SDK starting with v. 1.8.0 and similarly, AltUnity Inspector becomes AltTester Desktop starting with v. 1.5.0 and they are both available here

This comes with a series of major changes:

1. AltTester Unity SDK is now available only through our website and is no longer available on the Unity Asset Store

2. We moved the AltTester Unity SDK project from GitLab to GitHub.

Read more about all the major changes in this article and join our Discord Server, if you have any questions or issues with AltTester!

When it comes to mobile automation testing, there are many different choices for a tool. One popular option is Appium, an open-source framework which enables running automated tests on both Android and iOS devices.

Although a powerful tool, Appium has some limitations related to interacting with some non-native application types, one example being Unity games. For this reason we use AltUnity Tools, consisting of: 

  • AltUnity Tester, an open source asset allowing you to identify and interact with Unity objects and run end-to-end automated tests on real devices 
  • AltUnity Inspector, a desktop application helping you to visualize the game object hierarchy and get components, properties, methods and fields easily without access to the source code 

Why use Appium together with AltUnity Tools

There are a couple of scenarios for which you would want to use both of these frameworks at the same time:

  • By itself, AltUnity Tester cannot launch an app on a device. If you want to run tests in a pipeline, or by using cloud services, you can either create a script which will start your app, or you can use Appium before the test execution;
  • AltUnity Tester cannot perform some types of actions, such as interacting with any native popups your app might have, or putting the app in the background and resuming it. In any of these cases, you can use Appium to do the things that AltUnity Tester can’t.
  • With AltUnity Inspector you can’t visualize the native objects. For this you could use the Appium Inspector. 

AltUnity Tester with Appium example

To help you get started on Unity test automation, we’ve created an example python project which can be found here.

After you cloned it, there are a couple of things you need to check before running the tests:

  • For Android you need to have Android SDK version 16 or higher installed on your machine;
  • For iOS you need XCode with Command Line Tools installed (will only work on Mac OSX);
  • Your mobile device needs to have developer mode enabled and be connected via USB to the machine running the tests.

Inspecting the games 

When writing the tests you’ll need information about the Unity objects. With AltUnity Inspector you can get objects’s paths, components, methods, fields and properties. 

If your game contains native elements, you’ll need to use the Appium Inspector from which you can get the selectors and attributes. 

Running the tests

  • For Android, you can just run the script
  • For iOS, you first need to export IOS_UDID= then run the script
    • To find out an iOS device UDID you can go to Finder, click the device in the sidebar and click the info under the device name to reveal the UDID

The script will install any requirements that are missing from your machine (except Android SDK and XCode CLT), then run a basic test scenario:

  1. The app will be started by Appium;
  2. AltUnity Tester will ensure it’s initially loaded;
  3. Appium will put the app in the background for a couple of seconds, then resume it;
  4. Appium will check if the app was resumed successfully.

Please observe the following about the setup method in

  1. A minimum amount of desired capabilities have to be set in order for Appium to work. More details about desired capabilities can be found in the official Appium documentation
  2. The Appium driver needs to be created before the port forwarding needed by AltUnity Tester is done. This is because Appium clears any other port forwarding when it starts.

Let us know if you tried our example and if you found it helpful. If you have any questions or feedback, please leave us a comment below or join us on Discord or Google Groups.

Subscribe to our newsletter

And get our best articles in your inbox

 Back to top

Leave a Reply

Your email address will not be published. Required fields are marked *