Connect to Device Dialog

Applies to TestComplete 15.20, last modified on January 13, 2022

Use the Connect to Device dialog to connect to a mobile device running in the BitBar device cloud or managed by a private Appium server.

Connect to Device dialog

Click the image to enlarge it.

To call the dialog

In the Object Browser of TestComplete, right-click the Mobile item in the object tree and then click Connect to Device:

Opening the Connect to Device dialog from the Object Browser

Click the image to enlarge it.


  • An active license for TestComplete Mobile Module.

  • The Appium Support plugin must be enabled in TestComplete. You can check the plugin state in the File > Install Extensions dialog in TestComplete. You can find the plugin in the Mobile group.

  • Access to the server that manages your mobile devices. It can be one of the following:

    • A mobile device cloud provided as a service by BitBar.

      If you do not have a BitBar account, you can sign up for a free trial on the BitBar website:

      To access the cloud from TestComplete tests, use the API key assigned to your BitBar account. See the Prerequisites section.

    – or –

    • A private server managed by the Appium framework. It can run on your current computer or on a remote computer in your local network. The supported Appium version is 1.18.2.

      To learn how to install and configure one, please see Set up Appium Server.

      Note: Selenium, Selendroid, and other frameworks are not supported.

      For iOS testing: the XCUITest driver must be installed on your Appium server. See

      For Android testing: the UIAutomator2 driver must be installed on your Appium server. See

      Note: Other automation drivers for iOS and Android are not supported.

Enter BitBar API Key

If you use BitBar and there is no BitBar API key specified in the current TestComplete project, enter the API key you will use to run tests and click Apply.

Learn how to get the API Key

If you use a private mobile cloud, click Local Appium.

Connect to device


  1. On the Parameters tab, select the mobile device and a tested application for which you want to open a testing session.

    The Found devices list contains all the devices that are available for you in BitBar and that match the search criteria. If needed, you can filter the list by using the Device Type, OS Version, Resolution and Quick Search filters.

    The Status column shows the status of a device:

    • Ready

    • Occupied

    • On maintenance

    • Subscription only

    Select the device to which you want to connect.

    If the selected device is not available, TestComplete will not be able to connect to it. To connect to any available device rather than to the selected device, you can select the Connect to another device when the selected one is not available check box. TestComplete will search for a suitable device using the criteria that the project settings specify and connect to it instead.

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

    If you are testing an iOS application: 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 Custom Parameters tab.

  3. 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:


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

    The dialog will validate the JSON code 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.

To open the testing session and connect to it, click OK. To close the dialog without connecting any device, click Cancel.

Local Appium

Note: You must have your local Appium server running and available from your TestComplete workstation. For information on how to configure a local Appium server, see Set up Appium Server.

  1. In the Server URL text box, enter the URL address of your Appium server.

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

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

To open the testing session and connect to it, click OK. To close the dialog without connecting any device, click Cancel.

TestComplete will connect to the specified device and open a testing session there. The application running in the mobile device cloud will become available. You can explore it in the Object Browser and write code that will simulate user actions over it.

See Also

About Mobile Tests
Connecting to Mobile Devices and Opening Testing Sessions

Highlight search results