About Testing Android Applications (Legacy)

Applies to TestComplete 15.64, last modified on June 12, 2024
The information below concerns legacy mobile tests that work with mobile devices connected to the local computer. For new mobile tests, we recommend using the newer cloud-compatible approach.

TestComplete supports testing of mobile applications built for the Android operating system. This topic helps you get acquainted with the Android testing functionality supported by TestComplete.

Supported Android versions and devices

TestComplete supports testing physical mobile devices (smartphones and tablets), emulators and Android-x86 virtual machines running the Android operating system with the following API levels:

API Level Android OS Version
API level 30 11.0 (Additional preparations may be required. See Preparing Android Applications.)
API level 29 10.0
API level 28 9.0
API level 27 8.1
API level 26 8.0
API level 25 7.1.1
API level 24 7.0
API level 23 6.0
API level 22 5.1.1
API level 21 5.0.x
API level 19 4.4.x
API level 18 4.3.x
API level 17 4.2.x
API level 16 4.1.x
API level 15, NDK 8 4.0.3 – 4.0.4 (testing is supported with a number of limitations, see Possible Issues.)
API level 14, NDK 7 4.0.1 – 4.0.2 (testing is supported with a number of limitations, see Possible Issues.)

Xamarin.Forms and Xamarin.Android applications are also supported. TestComplete recognizes Xamarin.Forms controls and provides special wrapper test objects to simulate user actions on them. See About Xamarin.Forms Application Testing (Legacy). Controls of Xamarin.Android applications are supported as “native” Android controls.

Note: If your mobile device is running under custom firmware of the Android operating system, you may experience issues with testing.

Unsupported features and devices

The following features and devices are not supported and cannot be automated:

  • API level 20 (Android 4.4W).
  • Devices:

    Android Wear

    Android TV

    Android Auto

    Android Things

Requirements and preparations

  1. Install Java and Android SDK on the TestComplete computer. Specify their paths in TestComplete options (Tools > Options > Engines > Mobile > Android).

  2. Prepare your Android application:

    • To allow TestComplete to identify individual objects in your application (buttons, text boxes, and so on) and access their native properties and methods, your Android application must be prepared for testing (instrumented). TestComplete automatically instruments your Android application when running it from the Tested Applications collection. Alternatively, you can do this manually in Eclipse IDE or Android Studio.

      Non-instrumented applications can be tested in image-based mode only, but not in object-based mode.

    • The presence and value of the android:debuggable attribute in the application manifest do not matter.

  3. Prepare your Android device (physical device, emulator or virtual machine):

    • The device must have at least 512 MB of RAM. There are no requirements on the device CPU or screen resolution.

    • For physical devices: Enable developer options on the device.

    • For virtual machines: Make sure the virtual machine is available on the local network.

    • Connect to the tested Android device. TestComplete installs the TestComplete Android Agent on it.

    • Open the Mobile Screen and make sure TestComplete sees your device.

For detailed instructions, see Preparing for Testing Android Applications (Legacy).

When testing Android applications, do not run TestComplete and TestExecute at the same time on a computer (in the same Windows session, or in different sessions in Windows Server editions). Otherwise, the two Android testing engines will conflict and cause unexpected behavior.

Creating and recording tests for Android applications

In TestComplete, mobile tests can be recorded or created manually in form of keyword tests or scripts. It is usually easier to record the test first and then modify and enhance the recorded test.

When you record a test, you interact with the tested Android application as an end-user would: navigate through the application’s screens, fill out forms and so on. TestComplete captures all actions you performed in the application and adds them to the test.

A test consists of a sequence of operations with the device and objects of the tested application. For example, the sample keyword test uses the ClickItem operation to select an item from a combo box, and the SetText operation to simulate text input into text boxes.

A recorded Android test in TestComplete

The recorded tests can be modified and enhanced in a number of ways to create more flexible and efficient tests. For example, you can:

What your Android tests can do

TestComplete offers lots of test operations that can simulate a rich set of user activities and performs other test-related actions:

For complete information on simulating user actions and performing other test operations, see the topics of the Testing Android Applications (Legacy) section.

Important: The way in which in you interact with the tested application depends on whether the application was prepared for testing or not. See below for more information about this.

Testing Open (White-Box) and Black-Box applications

The way your test interacts with the tested Android application depends on whether the application is prepared for testing or not:

  • Testing prepared (Open, or white-box) applications

    Since the 14.70 version, TestComplete instruments Android applications automatically when running them from the Tested Applications collection.

    If an application was prepared for testing with TestComplete, the latter can access the application’s controls and their methods, fields and properties. We call these applications white-box or “Open” Applications.

    For testing Android Open Applications, TestComplete creates test objects that are wrappers for application controls. These wrappers contain methods and properties that TestComplete provides for all the test objects, plus they contain native methods, fields and properties of the appropriate controls. You can use these methods, fields and properties in your tests to determine or change the state of a control if other test means do not work for some reason.

    Another benefit of this approach is that TestComplete recognizes the control types (button, edit text, list view and so on) and supplies wrapper test objects with specific methods and properties that help you easily simulate user actions on the control and obtain the control’s data. Using these control-specific methods and properties you can create tests that can be easily ported to various Android devices.

    You can find methods, fields and properties available for testing in the Object Browser:

    Android controls in the Object Browser

    With TestComplete, you can record and play back user actions in Android Open Applications, or you can create tests for these applications manually from scratch. For detailed information on this, see Creating Tests for Android Open Applications (Legacy).

  • Testing unprepared (black-box) applications

    Android applications that were not prepared for testing do not expose their internal objects, methods and properties. You create image-based tests for them.

    The key difference of this approach is in the way TestComplete searches for windows and controls under test. When testing a white-box Android application, TestComplete uses specific control properties like class name, text or id to find the control in the operating system, and after the control is found, it sends test commands to it. When TestComplete performs image-based testing, it searches for controls on the device’s screen using the controls’ images:

    • When you touch the device screen during test recording (image-based tests can be recorded), TestComplete captures an image of the control with which you are working and saves the image to the Image Repository project item (see below).

    • During the test run, when TestComplete gets a command to simulate a touch or a keystroke against a control, TestComplete searches for the control’s image on the mobile device's screen and simulates a touch or a keystroke. TestComplete sends a touch notification to the screen. The control’s image is used only to find appropriate coordinates for the touch.

    To save control images to be used in testing, TestComplete includes the Image Repository project items. Since the image of a control can be different on different devices, the Image Repository supports storing a collection of possible images for each control:

    Testing Mobile Applications: Image Repository and Image Set items

    For complete information on the image-based testing approach, see Image-Based Testing.

Mobile Screen window

TestComplete includes the Mobile Screen window that displays the screen of the mobile device, emulator or virtual machine under test.

The TestComplete Mobile Screen Window

When you perform various actions in this window like touches, swipes or keystrokes, TestComplete passes them to the device, emulator or virtual machine under test. Similarly, any changes on the device screen are reflected in this window. In other words, you can use the Mobile Screen window to work with the mobile device, emulator or virtual machine without accessing this device, emulator or virtual machine.

The Mobile Screen window makes the device screen as accessible as your computer’s desktop. For instance, creating a keyword-test operation or checkpoint may require selecting an Android control from the device screen. To do this, you display your application in the Mobile Screen window and then choose the needed control from it in the same way as if you chose the control from the desktop. Another important role of this window is that it is used for recording script and keyword tests on Android applications. See Creating Tests for Android Open Applications (Legacy) and Recording Android Tests (Legacy).

Recording and playing back gestures

Multi-touch events (gestures) are complex events that cannot be recorded in the TestComplete Mobile Screen window. To record them, you need to use a physical mobile device like a phone or a tablet and switch TestComplete to a special mode in which it can register such events.

TestComplete records gestures as “movies” and stores them in the Android Gestures project item. You can then play back the gestures from scripts or keyword tests or do this in the Mobile Screen window.

Gestures can be recorded and simulated only on devices that support a touch-sensitive interface. Usually, these are hardware devices. Gestures cannot be recorded or played back on virtual machines and emulators, unless they support a touch-sensitive interface.

Currently, TestComplete does not support playing back gestures on devices with Android ver. 10.x - 11.x.

For complete information on working with multi-touch events, see the topics of the Simulating Gestures (Multi-Touch Events) (Legacy) section.

Object hierarchy and object properties

The top-level test object for mobile testing is Mobile. It contains methods and properties for accessing and enumerating mobile devices to which TestComplete is connected. You can see these methods and properties in the Object Browser:

The Mobile object has child Device objects that correspond to the connected mobile devices, emulators and virtual machines (see the image above). The properties of these objects provide information about the device and the operating system version installed on them. Methods help you simulate various test actions on the device: swipes, keystrokes, pressing physical (on device) buttons and so on.

The object hierarchy below the Device object depends on your application type:

  • If your Android application is an Open Application, you will see a hierarchy of application objects. TestComplete detects the controls’ class names and identifiers and uses them to name the test objects: TextView("textView1"), EditText("editText1"), Layout("verticalLayout1") and so on.

    For detailed information on naming objects and creating tests, see Creating Tests for Android Open Applications (Legacy).

  • If your Android application is a black-box application, you will not see test objects under the Device item. For these applications, TestComplete does not create test objects that are wrappers for mobile controls, nor does it provide access to native methods and properties of these controls. To work with mobile application controls, TestComplete uses images of the controls stored in the Image Repository. To get access to images in tests, you use the following syntax:


Here, ImageRepository is the reserved name of the top-level ImageRepository object that provides access to the repository data, ImageSetName is the name of the image set as you can see it in the Project Explorer panel, and ItemName is the name of the desired item (control) in the image set. The “item” objects provide methods for interacting with the corresponding control.

For complete information on addressing objects and creating image-based tests, see Image-Based Testing.

Support for Android controls

TestComplete recognizes controls in Android Open Applications only. It detects the control type and provides extended support for most frequently used controls like buttons, list views, action bars and others. See Supported Android Controls.

For supported controls, TestComplete offers specific built-in operations that help you automate various user actions on the controls: item selection, node expanding, data retrieval and so on. Some operations can be performed with “native” methods and properties that the Android Open Applications expose to TestComplete. Topics of the Working With Android Controls section contain dozens of samples demonstrating how to perform actions on Android controls.

Note: For information on working with web pages displayed in WebView controls, see the topics of the Testing Hybrid Mobile Applications (Legacy) section.

Verifying device and control properties

If you are testing an Open Android application, to verify properties of Android controls, you can use almost all the checkpoints available in TestComplete. For example, you can use the property checkpoint to validate object properties. You can also use region checkpoints to compare the device screen or its part, or a control image with some base-line picture.

If you are testing a black-box Android application, the only way to verify the control state is to use a mobile checkpoint, because black-box applications do not expose information on their internal objects.

Creating checkpoints for Android applications is very similar for creating checkpoints for Windows desktop and Web applications. The only difference is that you choose the control to be checked from the Mobile Screen window rather than from the desktop. For detailed information on checkpoint creation, see About Checkpoints.

You can also obtain the object property values and create custom verification scenarios with the if... then script statements or If.. Then keyword test operations.


TestComplete includes a sample test project that illustrates testing of an Android Open Application and working with the Android device’s sensors:

<TestComplete Samples>\Mobile\Android\Orders

Note: If you do not have the samples, download the TestComplete Samples installation package from the support.smartbear.com/testcomplete/downloads/samples page of our website and run it.

See Also

Testing Android Applications (Legacy)
Preparing for Testing Android Applications (Legacy)

Highlight search results