Run Tested Applications on Mobile Devices

Applies to TestComplete 15.65, last modified on July 17, 2024

Before you start creating automated mobile tests, you connect to a device, open a testing session on it, and run your tested application. When recording a test, you can run the application manually, for example, by touching the application icon on the screen on the device. However, this makes the test dependent on UI elements that may vary among devices.

To make your tests independent on these UI elements and, therefore, compatible with a larger number of devices and more stable, we recommend that you start the tested application automatically from the test.

Prerequisites for iOS applications

When connecting to an iOS device in the BitBar device cloud by using the Select BitBar Device dialog or from a test, specify the bundle ID of the tested iOS application. To do this, add the bundleId capability to the list of capabilities on the Custom Parameters tab page of the dialog or to the test code.

Autorun applications on recording

When you start test recording and connect to the target mobile device, TestComplete will launch the specified tested application automatically. After the recording is over, TestComplete will add commands that connect to the device and launch the application to the recorded test.

Recorded keyword test

Click the image to enlarge it.

Run and stop applications from tests

Starting the application when connecting to the device

In keyword tests, to connect to a mobile device and start the tested application on it, use the Run Remote Device operation:

Using the Run Remote Device operation to connect to a mobile device

Click the image to enlarge it.

In script tests, use the Mobile.ConnectDevice method. For example:


function Connect_Android_Appium()
  var server = "http://localhost:4723/wd/hub"; // or "http://localhost:4723/" for older versions
  var capabilities = {
    deviceName: "MyAndroidDevice",
    platformVersion: 10,
    platformName: "android",
    automationName: "UIAutomator2",
    app: "/tests/MyApp.apk",
    newCommandTimeout: 600

  Mobile.ConnectDevice(server, capabilities);



def Connect_Android_Appium():
  server = "http://localhost:4723/wd/hub" # or "http://localhost:4723/" for older versions
  capabilities = {
    "deviceName": "MyAndroidDevice",
    "platformVersion": 10,
    "platformName": "android",
    "automationName": "UIAutomator2",
    "app": "/tests/MyApp.apk",
    "newCommandTimeout": 600

  Mobile.ConnectDevice(server, capabilities)


Sub Connect_Android_Appium()
  server = "http://localhost:4723/wd/hub" // or "http://localhost:4723/" for older versions
  capabilities = "{""deviceName"":""MyAndroidDevice"",""platformVersion"":10,""platformName"":""android"",""automationName"":""UIAutomator2"",""app"":""\/tests\/MyApp.apk"",""newCommandTimeout"":600}"
  Call Mobile.ConnectDevice(server, capabilities)

End Sub


procedure Connect_Android_Appium();
var server, capabilities;
  server := 'http://localhost:4723/wd/hub'; // or "http://localhost:4723/" for older versions
  capabilities := '{"deviceName":"MyAndroidDevice","platformVersion":10,"platformName":"android","automationName":"UIAutomator2","app":"\/tests\/MyApp.apk","newCommandTimeout":600}';

  Mobile.ConnectDevice(server, capabilities);

C++Script, C#Script

function Connect_Android_Appium()
  var server = "http://localhost:4723/wd/hub"; // or "http://localhost:4723/" for older versions
  var capabilities = "{\"deviceName\":\"MyAndroidDevice\",\"platformVersion\":10,\"platformName\":\"android\",\"automationName\":\"UIAutomator2\",\"app\":\"\\/tests\\/MyApp.apk\",\"newCommandTimeout\":600}";
  Mobile["ConnectDevice"](server, capabilities);

Restarting, restoring, and closing the application

To manage the tested application from tests, use methods of the Mobile.Device.ApplicationManager object:

  • LaunchTestedApp - Starts the tested application on the mobile device.

  • ResetTestedApp - Restores the tested application to its initial state and restarts the application.

  • BackgroundTestedApp - Switches the tested application to the background mode.

  • CloseTestedApp - Stops the tested application.

    Note: The method may also close the testing session opened for the application on the mobile device.


Managing arbitrary processes on the mobile device

To manage processes running on the connected mobile device, use the methods of the Mobile.Device.ApplicationManager object. Specify the process by its name.

Use the ProcessState property to get the state of the process running on the device.


See Also

About Mobile Tests
Adding Applications to the List of Tested Applications

Highlight search results