Use the Run Remote Device operation to connect to a mobile device managed either by BitBar or by a private Appium server and open a testing session there. Mobile operations that follow that Run Remote Device operation in a test will run in that opened session and simulate user actions over a tested mobile application there.
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.
Note: Other automation drivers for iOS and Android are not supported.
The operation returns a
Device object that provides access to the mobile device on which the session has been opened.
Note: If the operation is called with the same set of capabilities once more, it will not reconnect to the mobile device. It will reset the state of the tested application on the connected device.
The operation is similar to specifying the desired capabilities of the target platform and starting a testing session by using the
Mobile.ConnectDevice method in script tests.
The operation cannot have child operations.
When you add the operation to your keyword test, TestComplete shows a wizard that contains the following pages:
Run Remote Device
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.
Log in to BitBar with your BitBar account.
If you still do not have a BitBar account, you can sign up for a free trial.
Click > My Account at the top right of the page.
In the My Integrations section, click API.
On the resulting page, click to copy your API key to the clipboard.
If you use a private mobile cloud, click Local Appium.
Depending on the mobile device cloud you use, configure the operation:
Select the mobile device and a tested application for which you want to open a testing session:
You can select devices that have any status in the Status column. However, the selected device must be Available when the test run starts.
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.
If no suitable device is found, the operation will report an error.
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
bundleIdcapability to the list of desired capabilities on the View more BitBar parameters > Custom Parameters tab.
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:
"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.
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.
In the Server URL text box, enter the URL address of your Appium server.
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
appcapability in the Parameters editor. The
appcapability value will override the Application Path value.
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 capabilitiesView required capabilities
Capability Description Sample value for iOS Sample value for Android
The name of the mobile OS where you want to open a testing session. iOS android
The version of the mobile OS where you want to open a testing session. 14.0 11
The mobile device or emulator on which you want to run your test. iPhone Simulator Galaxy Z41
The unique identifier of the mobile device. Compulsory for physical iOS devices. To learn how to get your iOS device UDID, see Get iOS Device UDIDs.
The test automation framework to use. XCUITest UIAutomator2
The full file path or the URL address of your tested mobile application. For iOS devices, it could be a debug version of the application (.app) or a release version of the application (.ipa).
For Android devices, it is .apk files.
.app (for emulators)
.ipa (for physical devices)
For information on all available capabilities, see Appium Desired Capabilities.
On this page, you can specify the following parameters:
Specifies the URL of the server that controls the target mobile device. It can be either the BitBar hub or a private Appium server running on your local computer or on a remote computer in your local network.
Specifies a JSON object that describes a testing session you want to open on your mobile device. For the list of required capabilities, see Supported capabilities.
Specifies the period (in seconds) for which the operation waits for the session to open. The default value is 180 seconds.