Connecting to Mobile Devices and Opening Testing Sessions

Applies to TestComplete 15.70, last modified on December 17, 2024

Before you start creating and running automated tests for a mobile application, connect TestComplete to the device and open a testing session there.

Prerequisites

Before connecting to a device and opening a testing session there, make sure that all requirements and prerequisites are met:

To open a testing session

In the BitBar device cloud

From the Object Browser

  1. In TestComplete, open the Object Browser.

  2. In the object tree, right-click the top-level Mobile item and then click Connect to Device. TestComplete will open the Connect to Device dialog.

  3. If the current TestComplete project does not have a BitBar API key specified, to connect to the BitBar device cloud dialog, enter the API key.

    Learn how to get the API key

  4. Select the mobile device and a tested application for which you want to open a testing session:

    • If the selected device is not available, TestComplete will not be able to connect to it. To command TestComplete to search for a replacement device, select the Connect to another device when the selected one is not available check box. On the Device Cloud > Mobile page of your project, you can set the search criteria for the replacement devices.

    • In the Application drop-down list box, select a mobile application for which you want to open a testing session. The application file must be either stored in the BitBar Files Library or added to the Tested Applications of the current TestComplete project. In the latter case, click Upload to BitBar to upload the application file to the BitBar Files Library and then select it in the list.

      For iOS only: To be able to launch and stop the tested application from tests or by using the Mobile Device Screen window of TestComplete, specify the bundle ID of the application when connecting to the device. It is the bundle ID that was used to compile the specified .ipa file. Add the bundleId capability to the list of desired capabilities on the View more BitBar parameters > Custom Parameters tab.

  5. To get more advanced options, click View more BitBar parameters:

    • On the Parameters tab, you can filter the device list by the device type, the version of the operating system running on the devices, their screen resolution, and their location.

    • By default, when a device is disconnected, the testing session on it is closed, and the device is restored to its initial state. Until the device is restored, it will remain unavailable. To keep the session alive to be able to reconnect to it, select the Keep the device available for quick reconnection check box. The session will be available for reconnection for up to 60 seconds.

    • If needed, on the Custom parameters tab, you can specify additional capabilities to be used for the testing session. Specify the capabilities in the JSON format. For example:

      JSON
      Copy Code

      JSON

      {
        "bitbar_project": "Automated tests",
        "bitbar_description": "Testing the Orders app"
      }

      The JSON code will be validated as you are typing it.

      Note: The capabilities you specify on the Custom capabilities tab can overwrite values specified on the Parameters tab.

      For the list of available capabilities, see the BitBar Documentation - Desired Capabilities.

  6. Click OK.

From the Mobile Device Screen window

  1. Click Show Mobile Screen on the TestComplete toolbar.

    Note: If the button is hidden, you can make it visible as it is described in Customizing Toolbars and Menus.

  2. TestComplete will open the Mobile Device Screen and then show the Select BitBar Device dialog.

  3. If the current TestComplete project does not have a BitBar API key specified, to connect to the BitBar device cloud dialog, enter the API key.

    Learn how to get the API key

  4. Select the mobile device and a tested application for which you want to open a testing session:

    • If the selected device is not available, TestComplete will not be able to connect to it. To command TestComplete to search for a replacement device, select the Connect to another device when the selected one is not available check box. On the Device Cloud > Mobile page of your project, you can set the search criteria for the replacement devices.

    • In the Application drop-down list box, select a mobile application for which you want to open a testing session. The application file must be either stored in the BitBar Files Library or added to the Tested Applications of the current TestComplete project. In the latter case, click Upload to BitBar to upload the application file to the BitBar Files Library and then select it in the list.

      For iOS only: To be able to launch and stop the tested application from tests or by using the Mobile Device Screen window of TestComplete, specify the bundle ID of the application when connecting to the device. It is the bundle ID that was used to compile the specified .ipa file. Add the bundleId capability to the list of desired capabilities on the View more BitBar parameters > Custom Parameters tab.

  5. To get more advanced options, click View more BitBar parameters:

    • On the Parameters tab, you can filter the device list by the device type, the version of the operating system running on the devices, their screen resolution, and their location.

    • By default, when a device is disconnected, the testing session on it is closed, and the device is restored to its initial state. Until the device is restored, it will remain unavailable. To keep the session alive to be able to reconnect to it, select the Keep the device available for quick reconnection check box. The session will be available for reconnection for up to 60 seconds.

    • If needed, on the Custom parameters tab, you can specify additional capabilities to be used for the testing session. Specify the capabilities in the JSON format. For example:

      JSON
      Copy Code

      JSON

      {
        "bitbar_project": "Automated tests",
        "bitbar_description": "Testing the Orders app"
      }

      The JSON code will be validated as you are typing it.

      Note: The capabilities you specify on the Custom capabilities tab can overwrite values specified on the Parameters tab.

      For the list of available capabilities, see the BitBar Documentation - Desired Capabilities.

  6. Click OK.

From a keyword test

Use the Run Remote Device operation:

  1. If there is no BitBar API key specified in the current TestComplete project, enter the key.

    Learn how to get the API key

  2. Select the mobile device and the tested application for which you want to open a testing session. The application file must be either added to the BitBar Files Library or to the Tested Applications collection of the current TestComplete project.

  3. If needed, specify additional capabilities for the testing session. For the list of available capabilities, see the BitBar Documentation - Desired Capabilities.

Connecting to the BitBar mobile device cloud from a keyword test

Click the image to enlarge it.

From a script test

Use the Mobile.ConnectDevice method to connect to the BitBar device cloud. You can write the code manually, or you can use the Generate Run Code dialog:

  1. Click on the Code Editor toolbar.

  2. If there is no BitBar API key specified in the current TestComplete project, enter the key.

    Learn how to get the API key

  3. In the resulting Generate Run Code dialog, select the mobile device and the tested application for which you want to open a testing session.

    The application file must be either added to the BitBar Files Library or to the Tested Applications collection of the current TestComplete project.

  4. If needed, specify additional capabilities for the testing session. For the list of available capabilities, see the BitBar Documentation - Desired Capabilities.

  5. Copy the code that the dialog generates and insert it into your script test.

Adding code that connects to BitBar and opens a testing session

Click the image to enlarge it.

The example below shows a code snippet that connects to a mobile device in the BitBar cloud and opens a testing session on it:

JavaScript
Python
VBScript
DelphiScript
C++Script, C#Script
Copy Code

JavaScript

function Connect_BitBar()
{
  var server = "https://appium.bitbar.com/wd/hub/";
  var capabilities = {
    "platformName": "android",
    "deviceName": "Android Phone",
    "automationName": "Appium",
    "bitbar_target": "android",
    "bitbar_device": "Samsung Galaxy A7 SM-A700F",
    "bitbar_app": "123",
    "newCommandTimeout": 600
  };
  Mobile.ConnectDevice(server, capabilities);

}

Python

def Connect_BitBar():
  server = "https://appium.bitbar.com/wd/hub/"
  capabilities = {
    "platformName": "android",
    "deviceName": "Android Phone",
    "automationName": "Appium",
    "bitbar_target": "android",
    "bitbar_device": "Samsung Galaxy A7 SM-A700F",
    "bitbar_app": "123",
    "newCommandTimeout": 600
  };
  Mobile.ConnectDevice(server, capabilities)

VBScript

Sub Connect_BitBar
  capabilities = "{""platformName"":""ANDROID"",""bitbar_target"":""android"", ""bitbar_device"":""Samsung Galaxy A7 SM-A700F"",""deviceName"":""Android Phone"",""automationName"":""Appium"",""bitbar_app"":""123"",""newCommandTimeout"":600}"
  server = "https://appium.bitbar.com/wd/hub/"
  Call Mobile.ConnectDevice(server, capabilities)
End Sub

DelphiScript

procedure Connect_BitBar();
var server, capabilities;
begin
  capabilities := '{"platformName":"ANDROID","bitbar_target":"android","bitbar_device":"Samsung Galaxy A7 SM-A700F","deviceName":"Android Phone","automationName":"Appium","bitbar_app":"123","newCommandTimeout":600}';
  server := 'https://appium.bitbar.com/wd/hub/';
  Mobile.ConnectDevice(server, capabilities);
end;

C++Script, C#Script

function Connect_BitBar()
{
  var capabilities = "{\"platformName\":\"ANDROID\",\"bitbar_target\":\"android\",\"bitbar_device\":\"Samsung Galaxy A7 SM-A700F\",\"deviceName\":\"Android Phone\",\"automationName\":\"Appium\",\"bitbar_app\":\"123\",\"newCommandTimeout\":600}";
  var server = "https://appium.bitbar.com/wd/hub/";
  Mobile["ConnectDevice"](server, capabilities);
}

On mobile devices managed by a private server

From the Object Browser

  1. In TestComplete, open the Object Browser.

  2. In the object tree, right-click the top-level Mobile item and then click Connect to Device.

  3. In the resulting Connect to Device dialog, click Local Appium.

  4. In the Server URL text box, enter the URL address of your Appium server. For Appium 2.x, the format of the URL should be http://localhost:4723 and for Appium 1.x the format should be http://localhost:4723/wd/hub.

  5. In the Application Path text editor, specify the full path to the application that you want to install on the target mobile device and from which you want to open a testing session. If your application is added to the list of tested applications in your TestComplete project, you can click the down-arrow button and select the application path from the drop-down list. You can also type the path manually, or you can click the ellipsis button and browse for the needed application file.

    Specify the application path relatively to the Appium server location.

    You can also specify the application path using the app capability in the Parameters editor. The app capability value will override the Application Path value.

  6. In the Parameters editor, enter the capabilities that describe a testing session you want to open, in the JSON format. The dialog will validate the JSON code as you are typing.

    View required capabilities

    For information on all available capabilities, see Appium Desired Capabilities.

  7. Click OK.

From the Mobile Device Screen window

  1. Click Show Mobile Screen on the TestComplete toolbar.

    Note: If the button is hidden, you can make it visible as it is described in Customizing Toolbars and Menus.

  2. TestComplete will open the Mobile Device Screen and then show the Select BitBar Device dialog.

  3. In the dialog, click Local Appium.

  4. In the Server URL text box, enter the URL address of your Appium server. For Appium 2.x, the format of the URL should be http://localhost:4723 and for Appium 1.x the format should be http://localhost:4723/wd/hub.

  5. In the Application Path text editor, specify the full path to the application that you want to install on the target mobile device and from which you want to open a testing session. If your application is added to the list of tested applications in your TestComplete project, you can click the down-arrow button and select the application path from the drop-down list. You can also type the path manually, or you can click the ellipsis button and browse for the needed application file.

    Specify the application path relatively to the Appium server location.

    You can also specify the application path using the app capability in the Parameters editor. The app capability value will override the Application Path value.

  6. In the Parameters editor, enter the capabilities that describe a testing session you want to open, in the JSON format. The dialog will validate the JSON code as you are typing.

    View required capabilities

    For information on all available capabilities, see Appium Desired Capabilities.

  7. Click OK.

From a keyword test

Use the Run Remote Device operation:

  1. When configuring the operation, click Local Appium.

  2. In the Server URL text box, enter the URL address of your Appium server. For Appium 2.x, the format of the URL should be http://localhost:4723 and for Appium 1.x the format should be http://localhost:4723/wd/hub.

  3. In the Application Path text editor, specify the full path to the application that you want to install on the target mobile device and from which you want to open a testing session. If your application is added to the list of tested applications in your TestComplete project, you can click the down-arrow button and select the application path from the drop-down list. You can also type the path manually, or you can click the ellipsis button and browse for the needed application file.

    Specify the application path relatively to the Appium server location.

    You can also specify the application path using the app capability in the Parameters editor. The app capability value will override the Application Path value.

Connecting to an Appium automated testing session from a keyword test

Click the image to enlarge it.

From a script test

Write a script code that will connect to your private server managed by Appium and start a testing session there. You can write the code manually, or you can use the Generate Run Code dialog:

  1. Click on the Code Editor toolbar.

  2. In the resulting Generate Run Code dialog, click Local Appium.

  3. In the Server URL text box, enter the URL address of your Appium server. For Appium 2.x, the format of the URL should be http://localhost:4723 and for Appium 1.x the format should be http://localhost:4723/wd/hub.

  4. In the Application Path text editor, specify the full path to the application that you want to install on the target mobile device and from which you want to open a testing session. If your application is added to the list of tested applications in your TestComplete project, you can click the down-arrow button and select the application path from the drop-down list. You can also type the path manually, or you can click the ellipsis button and browse for the needed application file.

    Specify the application path relatively to the Appium server location.

    You can also specify the application path using the app capability in the Parameters editor. The app capability value will override the Application Path value.

  5. In the Parameters editor, enter the capabilities that describe a testing session you want to open, in the JSON format. The dialog will validate the JSON code as you are typing.

    View required capabilities

    For information on all available capabilities, see Appium Desired Capabilities.

  6. Copy the code that the dialog generates and insert it into your script test.

Adding code that connects to a private Appium server and opens a testing session

Click the image to enlarge it.

The example below shows a code snippet that connects to a mobile device managed by a private Appium server and opens a testing session on it:

JavaScript
Python
VBScript
DelphiScript
C++Script, C#Script
Copy Code

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

}

Select a device to connect

Instead of connecting to an exact BitBar device you specify in your test, you can connect to any device that is currently available and that meets the criteria you specify:

  • In keyword tests, select the Connect to another device when the selected one is not available check box of the Run Remote Device operation.

  • In script tests, add the bitbar_findDevice capability set to true to the list of capabilities that the Mobile.ConnectDevice method uses.

  • In the Connect to Device or in the Select BitBar Device dialog, select the Connect to another device when the selected one is not available check box.

To search for a device, TestComplete uses the criteria that you can specify on the Project Properties > Device Cloud > Mobile page of your project:

  1. Open the Properties page of the current TestComplete project. You can do it, for example, by selecting Tools > Current project properties from the TestComplete main menu.

  2. Select Mobile Devices > Mobile in the tree on the left.

  3. The Criteria for finding BitBar device section shows the search criteria for iOS devices and Android devices.

  4. To edit criteria, click Edit iOS criteria or Edit Android criteria correspondingly.

  5. In the resulting Edit Criteria for Finding Device dialog, specify the criteria.

    The criteria include one or several conditions combined with the AND operation:

    Specifying criteria to search for replacement devices

    Click the image to enlarge it.

  6. Click OK to save the specified criteria.

When TestComplete is not able to connect to an exact BitBar device you have selected in a dialog or specified in the test, it will search for a suitable replacement device and connect to it instead. If no suitable device can be found, TestComplete will report an error.

After the session is open

Your tested mobile application will become available to TestComplete. You can:

Disconnecting from the server

When you no longer need to be connected to the testing session, you can terminate it and disconnect from the device.

From the Object Browser

In the Object Browser, under the Mobile node, find the Device node that corresponds to a testing session from which you want to disconnect. Right-click the node and then click Disconnect.

From the Mobile Device Screen window

Click on the Mobile Device Screen window toolbar.

From a script test

To close the session, use the Mobile.Device(DeviceName).Disconnect method.

From a keyword test

Call the Mobile.Device(DeviceName).Disconnect method from your test by using the Call Object Method, Run Code Snippet, or Run Script Routine operation.

On timeout

A mobile device waits for commands from TestComplete for the period that the New command timeout project property specifies. The default value is 5 minutes. If no commands are sent to the device until the period elapses, the device will be disconnected.

Note: This timeout does not affect exploring tested mobile applications by using the Object Browser or Object Spy. The device will remain connected even if you leave it idle.

Reconnecting to BitBar devices

By default, after you disconnect from a BitBar device, the testing session on it is closed, and the device is restored to its initial state. Until the device is restored, it is unavailable.

To be able to reconnect to the same device, select the Keep the device available for quick reconnection option. After you disconnect from the device, it will remain available for up to 60 seconds.

See Also

About Mobile Tests

Highlight search results