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.

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:

JavaScript

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

}

Python

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)

VBScript

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

DelphiScript

procedure Connect_Android_Appium();
var server, capabilities;
begin
  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);
end;

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.

Example

The code below shows how to get the ApplicationManager object and how to use it to start, reset, and then stop the tested application for which the testing session is opened on the mobile device:

Note: For the example to work correctly, your project must be connected to the BitBar cloud and the bitbar_app capability must specify a correct application ID in the BitBar file storage. If you use an iOS device, the bundleId capability must also be specified for the testing session. See Project Properties > Device Cloud > Mobile.

JavaScript

function Test()
{
  // Connect to a mobile device
  var capabilities = {
    "platformName": "ANDROID",
    "bitbar_target": "android",
    "bitbar_findDevice": "false",
    "bitbar_device": "Google Pixel 3a Android 10",
    "deviceName": "Google Pixel 3a Android 10",
    "automationName": "UiAutomator2",
    "bitbar_app": "1234"
};
  var server = "https://appium.bitbar.com/wd/hub/";
  Mobile.ConnectDevice(server, capabilities);

  var appManager = Mobile.Device().ApplicationManager;
  // Launch the tested application
  appManager.LaunchTestedApp();

  // Simulate user actions
  // …

  // Switch the tested application to the background mode
  appManager.BackgroundTestedApp();
  // …

  // Reset and restart the tested application
  appManager.ResetTestedApp();
  // …

  // Close the tested application and stop the testing session
  appManager.CloseTestedApp();

}

JScript

function Test()
{

  // Connect to a mobile device
  var capabilities = "{\"platformName\":\"ANDROID\",\"bitbar_target\":\"android\",\"bitbar_findDevice\":false,\"bitbar_device\":\"Google Pixel 3a Android 10\",\"deviceName\":\"Google Pixel 3a Android 10\",\"automationName\":\"UiAutomator2\",\"bitbar_app\":\"1234\"}";
  var server = "https://appium.bitbar.com/wd/hub/";
  Mobile.ConnectDevice(server, capabilities);

  var appManager = Mobile.Device().ApplicationManager;
  // Launch the tested application
  appManager.LaunchTestedApp();

  // Simulate user actions
  // …

  // Switch the tested application to the background mode
  appManager.BackgroundTestedApp();
  // …

  // Reset and restart the tested application
  appManager.ResetTestedApp();
  // …

  // Close the tested application and stop the testing session
  appManager.CloseTestedApp();

}

Python

def Test():

  # Connect to a mobile device
  capabilities = {
    "platformName": "ANDROID", 
    "bitbar_target": "android", 
    "bitbar_findDevice": "false", 
    "bitbar_device": "Google Pixel 3a Android 10", 
    "deviceName": "Google Pixel 3a Android 10", 
    "automationName": "UiAutomator2", 
    "bitbar_app": "1234"
}
  server = "https://appium.bitbar.com/wd/hub/"
  Mobile.ConnectDevice(server, capabilities)

  appManager = Mobile.Device().ApplicationManager
  
  # Launch the tested application
  appManager.LaunchTestedApp

  # Simulate user actions
  # ...

  # Switch the tested application to the background mode
  appManager.BackgroundTestedApp
  # ...

  # Reset and restart the tested appication
  appManager.ResetTestedApp
  # ...

  # Close the tested application and stop the testing session
  appManager.CloseTestedApp

VBScript

Sub Test()

  ' Connect to a mobile device
  capabilities = "{""platformName"":""ANDROID"",""bitbar_target"":""android"",""bitbar_findDevice"":false,""bitbar_device"":""Google Pixel 3a Android 10"",""deviceName"":""Google Pixel 3a Android 10"",""automationName"":""UiAutomator2"",""bitbar_app"":""1234""}"
  server = "https://appium.bitbar.com/wd/hub/"
  Call Mobile.ConnectDevice(server, capabilities)

  Set appManager = Mobile.Device().ApplicationManager
  ' Launch the tested application
  appManager.LaunchTestedApp

  ' Simulate user actions
  ' …

  ' Switch the tested application to the background mode
  appManager.BackgroundTestedApp
  ' …

  ' Reset and restart the tested application
  appManager.ResetTestedApp
  ' …

  ' Close the tested application and stop the testing session
  appManager.CloseTestedApp

End Sub

DelphiScript

procedure Test();
var capabilities, server, appManager;
begin

  // Connect to a mobile device
  capabilities := '{"platformName":"ANDROID","bitbar_target":"android","bitbar_findDevice":false,"bitbar_device":"Google Pixel 3a Android 10","deviceName":"Google Pixel 3a Android 10","automationName":"UiAutomator2","bitbar_app":"1234"}';
  server := 'https://appium.bitbar.com/wd/hub/';
  Mobile.ConnectDevice(server, capabilities);

  appManager := Mobile.Device().ApplicationManager;
  // Launch the tested application
  appManager.LaunchTestedApp();

  // Simulate user actions
  // …

  // Switch the tested application to the background mode
  appManager.BackgroundTestedApp();
  // …

  // Reset and restart the tested application
  appManager.ResetTestedApp();
  // …

  // Close the tested application and stop the testing session
  appManager.CloseTestedApp();

end;

C++Script, C#Script

function Test()
{

  // Connect to a mobile device
  var capabilities = "{\"platformName\":\"ANDROID\",\"bitbar_target\":\"android\",\"bitbar_findDevice\":false,\"bitbar_device\":\"Google Pixel 3a Android 10\",\"deviceName\":\"Google Pixel 3a Android 10\",\"automationName\":\"UiAutomator2\",\"bitbar_app\":\"1234\"}";
  var server = "https://appium.bitbar.com/wd/hub/";
  Mobile["ConnectDevice"](server, capabilities);

  var appManager = Mobile["Device"]()["ApplicationManager"];
  // Launch the tested application
  appManager["LaunchTestedApp"]();

  // Simulate user actions
  // …

  // Switch the tested application to the background mode
  appManager["BackgroundTestedApp"]();
  // …

  // Reset and restart the tested application
  appManager["ResetTestedApp"]();
  // …

  // Close the tested application and stop the testing session
  appManager["CloseTestedApp"]();

}

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.

ActivateProcess - Switches the process running in the background to the foreground mode.
TerminateProcess - Stops the process.

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

Example

The code below shows how to get the ApplicationManager object and how to use it to manage a process running on a mobile device:

Note: For the example to work correctly, your project must be connected to the BitBar cloud, the bitbar_app capability must specify the correct application ID in the BitBar file storage, and the processName variable must specify the proper name of the process existing on the connected mobile device. If you use an iOS device, the bundleId capability must also be specified for the testing session. See Project Properties - Device Cloud > Mobile.

JavaScript

function Test()
{

  // Connect to a mobile device
  var capabilities = {
  "platformName": "ANDROID",
  "bitbar_target": "android",
  "bitbar_findDevice": "false",
  "bitbar_device": "Google Pixel 3a Android 10",
  "deviceName": "Google Pixel 3a Android 10",
  "automationName": "UiAutomator2",
  "bitbar_app": "1234"
};
  var server = "https://appium.bitbar.com/wd/hub/";
  Mobile.ConnectDevice(server, capabilities);

  var appManager = Mobile.Device().ApplicationManager;
  var processName = "smartbear.example.orders";

  // Launch the tested application
  appManager.LaunchTestedApp();

  // Switch the tested application to the background mode
  appManager.BackgroundTestedApp();
  // Post the process state to the test log
  Log.Message(appManager.ProcessState(processName));

  // Restore the process of the tested application from the background
  appManager.ActivateProcess(processName);

  // Terminate the process of the tested application
  appManager.TerminateProcess(processName);

}

JScript

function Test()
{
  // Connect to a mobile device
  var capabilities = "{\"platformName\":\"ANDROID\",\"bitbar_target\":\"android\",\"bitbar_findDevice\":false,\"bitbar_device\":\"Google Pixel 3a Android 10\",\"deviceName\":\"Google Pixel 3a Android 10\",\"automationName\":\"UiAutomator2\",\"bitbar_app\":\"1234\"}";
  var server = "https://appium.bitbar.com/wd/hub/";
  Mobile.ConnectDevice(server, capabilities);

  var appManager = Mobile.Device().ApplicationManager;
  var processName = "smartbear.example.orders";

  // Launch the tested application
  appManager.LaunchTestedApp();

  // Switch the tested application to the background mode
  appManager.BackgroundTestedApp();

  // Post the process state to the test log
  Log.Message(appManager.ProcessState(processName));

  // Restore the process of the tested application from the background
  appManager.ActivateProcess(processName);

  // Terminate the process of the tested application
  appManager.TerminateProcess(processName);

}

Python

def Test():

  # Connect to a mobile device
  capabilities = {
    "platformName": "ANDROID", 
    "bitbar_target": "android", 
    "bitbar_findDevice": "false", 
    "bitbar_device": "Google Pixel 3a Android 10", 
    "deviceName": "Google Pixel 3a Android 10", 
    "automationName": "UiAutomator2", 
    "bitbar_app": "1234"
}
  server = "https://appium.bitbar.com/wd/hub/"
  Mobile.ConnectDevice(server, capabilities)

  appManager = Mobile.Device().ApplicationManager
  processName = "smartbear.example.orders"
  
  # Launch the tested application
  appManager.LaunchTestedApp()
  
  # Switch the tested application to the background mode
  appManager.BackgroundTestedApp()
  
  # Post the process state to the test log
  Log.Message(appManager.ProcessState[processName])
  
  # Restore the process of the tested application from the background
  appManager.ActivateProcess(processName)
  
  # Terminates the process of the tested application
  appManager.TerminateProcess(processName)

VBScript

Sub Test()

  ' Connect to a mobile device
  capabilities = "{""platformName"":""ANDROID"",""bitbar_target"":""android"",""bitbar_findDevice"":false,""bitbar_device"":""Google Pixel 3a Android 10"",""deviceName"":""Google Pixel 3a Android 10"",""automationName"":""UiAutomator2"",""bitbar_app"":""1234""}"
  server = "https://appium.bitbar.com/wd/hub/"
  Call Mobile.ConnectDevice(server, capabilities)

  Set appManager = Mobile.Device().ApplicationManager
  processName = "smartbear.example.orders"

  ' Launch the tested application
  appManager.LaunchTestedApp

  ' Switch the tested application to the background mode
  appManager.BackgroundTestedApp

  ' Post the process state to the test log
  Log.Message(appManager.ProcessState(processName))

  ' Restore the process of the tested application from the background
  appManager.ActivateProcess(processName)

  ' Terminate the process of the tested application
  appManager.TerminateProcess(processName)

End Sub

DelphiScript

def Test():

  # Connect to a mobile device
  capabilities = {
    "platformName": "ANDROID",
    "bitbar_target": "android",
    "bitbar_findDevice": "false",
    "bitbar_device": "Google Pixel 3a Android 10",
    "deviceName": "Google Pixel 3a Android 10",
    "automationName": "UiAutomator2",
    "bitbar_app": "1234"
}
  server = "https://appium.bitbar.com/wd/hub/"
  Mobile.ConnectDevice(server, capabilities)

  appManager = Mobile.Device().ApplicationManager
  processName = "smartbear.example.orders"

  # Launch the tested application
  appManager.LaunchTestedApp()

  # Switch the tested application to the background mode
  appManager.BackgroundTestedApp()

  # Post the process state to the test log
  Log.Message(appManager.ProcessState[processName])

  # Restore the process of the tested application from the background
  appManager.ActivateProcess(processName)

  # Terminate the process of the tested application
  appManager.TerminateProcess(processName)

C++Script, C#Script

function Test()
{
  // Connect to a mobile device
  var capabilities = "{\"platformName\":\"ANDROID\",\"bitbar_target\":\"android\",\"bitbar_findDevice\":false,\"bitbar_device\":\"Google Pixel 3a Android 10\",\"deviceName\":\"Google Pixel 3a Android 10\",\"automationName\":\"UiAutomator2\",\"bitbar_app\":\"1234\"}";
  var server = "https://appium.bitbar.com/wd/hub/";
  Mobile["ConnectDevice"](server, capabilities);

  var appManager = Mobile["Device"]()["ApplicationManager"];
  var processName = "smartbear.example.orders";

  // Launch the tested application
  appManager["LaunchTestedApp"]();

  // Switch the tested application to the background mode
  appManager["BackgroundTestedApp"]();

  // Post the process state to the test log
  Log["Message"](appManager["ProcessState"](processName));

  // Restore the process of the tested application from the background
  appManager["ActivateProcess"](processName);

  // Terminate the process of the tested application
  appManager["TerminateProcess"](processName);

}

Run Tested Applications on Mobile Devices

Prerequisites for iOS applications

Autorun applications on recording

Run and stop applications from tests

Starting the application when connecting to the device

Restarting, restoring, and closing the application

Managing arbitrary processes on the mobile device

See Also