About Testing Android Applications (Legacy)

Supported Android versions and devices

Requirements and preparations

Creating and recording tests for Android applications

What your Android tests can do

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

Mobile Screen window

Recording and playing back gestures

Object hierarchy and object properties

Support for Android controls

Verifying device and control properties

Samples

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:

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.

Unsupported features and devices

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.

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.

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

• Add new operations to recorded tests, reorder operations and modify their parameters.

• Delete or disable unneeded operations (for example, superfluous recorded operations).

• Insert checkpoints for verifying objects and values in the tested application.

• Create data-driven tests that run multiple test iterations using different sets of data.

• The following topics provide detailed information about creating and enhancing tests:

  Task	See topic…
  Simulating user actions	Simulating User Actions Over Android Open Applications (Legacy) and Simulating User Actions Over Android Devices (Legacy)
  Creating tests using recording	Recording Tests in TestComplete and Recording Android Tests (Legacy)
  Creating tests manually	Keyword Testing and Scripting
  Running tests	Running Tests
  Creating checkpoints for verifying application behavior and state	Checkpoints
  Running multiple test iterations using data from an external file	Data-Driven Testing
  Testing applications that display web pages	Testing Hybrid Mobile Applications

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

• Touch and long touch on-screen controls.

• Drag and swipe items.

• Simulate multi-touch gestures.

• Input text via a keyboard.

• Press on-device (physical) buttons.

• Emulate a GPS location.

• Get sensor values.

• Install and run applications on devices.

• Verify objects and their properties.

• And more.

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.

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:

  

  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:

  

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

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

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).

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.

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:

  ImageRepository.ImageSetName.ItemName

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.

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.

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