Automating the Android testing process

You can automate the process of testing Android apps with several command line tools, the Android Debug Bridge (adb), and the USB Controller. The USB Controller also makes it possible to test in secure environments.

Before you begin

  • Install HCL OneTest™ UI and ensure that the Extension for Mobile is selected. For details, see Installing the product software.
  • Download and install adb, which is part of Android SDK Tools, on the computer running the test workbench. The current download page is at Android Studio but the location could change in the future. You do not need to install the full Android Studio. Just navigate to the SDK Tools Only section under Other Download Options to obtain the installer. Make sure your device is correctly setup for adb by executing the adb devices command.
  • To test on Android emulators, set up one or more AVD (Android Virtual Device) configurations. For details, see Using the Emulator. This article also describes ways to improve emulator performance through hardware acceleration.
  • To test on Android devices, enable USB debugging by going to Settings > Developer options on an Android device. Then, connect the Android device with a USB cable to the computer that is running the test workbench. If necessary, obtain the specific USB driver for your device from or go to the web site of the device vendor.
  • As an alternative for testing on Android devices, you can use the USB Controller, which provides silent install mode on Android devices and emulators, regardless of the API level, and also allows you to work in secure environments that have no WiFi access. With the USB Controller, you can also work in an environment where the test workbench is remote. See Installing and configuring the Android client with the USB Controller for details.
  • You cannot run a test from the command line on Mac OS X.
  • Record the test scripts for the application under test (AUT). The test recording process cannot be automated. See Recording tests from the Android mobile test client for details.

About this task

The automation process includes the following procedures:

  • Adding the applications under test (AUT) to the test workbench
  • Installing the latest release of the AUT on an Android device or emulator
  • Installing the mobile test client on an Android device and starting it in passive mode
  • Running the test from the command line or by using the UrbanCode Deploy plugin


  1. Add the AUT to the test workbench.

    You can instrument the AUT and add it to the test workbench by uploading the app from a mobile device or emulator or by clicking the Add applications to list icon Add applications to list in the test workbench. To automate the process, use AddAndroidApp.jar, which you can download from the Android Welcome Page. See Adding Android apps to the test workbench from the command line for details.

    Running AddAndroidApp.jar results in three new .apk files:

    • I-original apk name.apk - Recording-ready application
    • R-original apk name.apk - Playback-ready application
    • T-original apk name.apk - Test engine for the application

    See How the test workbench tests Android applications for details about the .apk files and the Android build chain.

  2. Use adb to install the latest release of the AUT on an Android device or emulator. Both the playback-ready .apk file and the test engine .apk file must be installed, unless you enable silent mode on the device or emulator. The adb utility is typically installed at Android-SDK-install-location\sdk\platform-tools. Release 21 or newer of the Android SDK Platform-tools is required.
    1. Locate the playback-ready .apk file and the test engine .apk file. As a result of Step 1, these files were downloaded to a local folder named localdir.
    2. Run the following commands from the command line to install the latest release of the AUT on an Android device or emulator:
      adb install -r localdir/R-AUT-name.apk
      adb install -r localdir/T-AUT-name.apk
    3. To install the AUT on multiple devices or emulators, use adb install with the -s (Serial) option, for example:
      adb install -s emulator-5556 -r localdir/T-AUT-name.apk
      adb install -s emulator-5556 -r localdir/R-AUT-name.apk
      adb install -s emulator-5558 -r localdir/T-AUT-name.apk 
      adb install -s emulator-5558 -r localdir/R-AUT-name.apk
      For details, see Directing commands to a specific emulator or device.
  3. Install the mobile test client and start it in passive mode. Passive mode allows text execution to be controlled by a script or batch file in the test workbench. Run the following adb commands to uninstall an existing version of the mobile test client, reinstall a newer version of the client, and set the client to passive mode.
    adb uninstall
    adb install "Eclipse client path/"
    adb shell am start -n -e workbench_url "Workbench-Url" --ez passive_mode “true”

    For example:

    adb uninstall
    adb install "C:\Program Files\HCL\HCLIMShared\"
    adb shell am start -n -e workbench_url "" --ez passive_mode “true”
  4. Run a test in command line mode. For details about running a test or schedule in command line mode, see Running a test or schedule from the command line.

    If you want to automate tests of mobile web applications, you must ensure that the Mobile Web Recorder is installed on the mobile test client. If the mobile test client is set up to run silent mode with the USB Controller, the Mobile Web Recorder will be installed automatically when the test run starts. No user action is required. However, if silent install is not set up, you must install the Mobile Web Recorder by tapping Manage Web Applications once in the mobile test client. This will initiate the installation of the two required apks and fulfill the requirements for automated test playback of a web app.

    If your automated testing requires the test workbench to be stopped and re-started, you can enable the Do not quit when workbench exits setting in the USB Controller to keep the USB Controller running even after the test workbench is closed. For details, see USB Controller.

    By default, the test workbench selects the first connected device that best fits the test execution requirements (Android OS and Android API). To run the test on one or more specific devices, define the Device ID selection variable. To find the Device ID, open the Mobile Devices editor in the test workbench, select a device, and look for the ID in Detailed Properties.

    You can also use a variable to select a specific device. For details, see Defining a variable to run a test with a selected mobile device.

    All test scripts are linked to a specific version of the AUT. If you upload a new version of the AUT, you should always run the test on the newest version of the AUT. For details, see Defining a variable in a test to run the latest version of an application.

    Note: If you have set the preference related to automatic refactoring of tests when a new application version is added, you do not need to define such a variable.
  5. As an alternative to running a test in command line mode, you can run a test using the UrbanCode Deploy plugin for HCL OneTest Studio. For more information, see, Testing from UrbanCode Deploy.