About Running Mobile Tests in Mobile Device Clouds

Applies to TestComplete 14.74, last modified on April 22, 2021

In TestComplete, you can connect to mobile device clouds and create and run automated tests using real mobile devices and emulators in that cloud. This way you can do the following:

  • Create automated mobile tests easier in the familiar TestComplete IDE.

  • Explore your tested application internal hierarchy by using the Object Browser.

  • Use various TestComplete features for your testing benefits:

  • Run tests on a wide range of mobile devices without connecting those devices to your TestComplete workstation directly.

Note: Currently, you write script instructions that connect to mobile devices and simulate user actions on them manually. Recording user actions over mobile devices will be implemented in one of the future TestComplete releases.

Requirements

Mobile device cloud

To run automated mobile tests in various mobile environments, you must have a proper mobile device cloud. It can be:

  • 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:

    bitbar.com/signup

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

    To learn how to install your tested application to the target device in the cloud, see the Prerequisites section.

– or –

  • A private mobile device cloud.

If you use a mobile device cloud provided as a service by a third-party provider, for instance BitBar, you may be charged for using cloud resources when creating and running tests. Please check the pricing policy of your provider.

TestComplete

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

  • The TestComplete workstation (the computer on which TestComplete is installed) must have access to your mobile device cloud.

Tested application

  • Your tested mobile application must be compiled with accessibility information. To learn more, see the documentation for the IDE used to develop the application.

  • Your tested mobile application must be accessible to the mobile device on which you will run tests. See the Prerequisites section.

Supported mobile devices

  • Android and iOS devices.

    Android OS versions prior to 5.0 are not supported.

  • Real devices and emulators.

Prerequisites

If you use BitBar

1. Get the API Key

To access the BitBar mobile cloud from TestComplete tests, use the API key assigned to your BitBar account:

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

  2. Click  > My Account at the top right of the page.

  3. In the My Integrations section, click API.

  4. On the resulting page, click to copy your API key to the clipboard.

Copying the BitBat API key

Click the image to enlarge it.

2. Upload the tested app and get the app ID

To open a testing session on a mobile device in a cloud, specify the ID of the application for which the session will be opened. To get the ID, upload the application file (.apk or .ipa) to the BitBar Files Library:

Via the BitBar website

  1. Log in to BitBar using your BitBar account.

    If you still do not have a BitBar account, you can sign up for a free trial.

  2. Click My Files Library on the top of the page.

  3. Click Upload file and browse for the application file you want to upload. For iOS, it must be an .ipa file. For Android, it must be an .apk file.

  4. After the file is uploaded, you can view its ID in the info panel at the bottom:

    Getting the application ID

    Click the image to enlarge it.

From the TestComplete IDE

  1. Open the TestComplete project that you will use to run tests in the mobile device cloud.

  2. Add the application file to the Tested Applications collection of the project.

  3. Select the application in the Tested Applications collection and click Upload to BitBar:

    Uploading a mobile application to the BitBar Files Library from the Tested Applications collection

    Click the image to enlarge it.

  4. When generating code to open a testing session via the Generate Run Code dialog, in the Application drop-down list, select the application in the list.

    If the application is not uploaded to the BitBar Files Library yet, click Upload and select:

    Uploading a mobile application to the BitBar Files Library from the Generate Run Code dialog

    Click the image to enlarge it.

    If the application is already uploaded, click Select.

    Getting the app ID in the Generate Run Code dialog

    Click the image to enlarge it.

    The dialog will add the application ID to the generated code that will open a testing session:

    App ID in the generated code

    Click the image to enlarge it.

If you use a private mobile device cloud

Place your tested application to a location available to your mobile cloud. For example, you can place the application file (.apk, .app or .ipa) to a shared network location. To install the application to the target device, use the app capability. For information on how to install the application upon opening a testing session, see Connecting to Mobile Device Clouds and Opening Testing Sessions.

How it works

  1. In TestComplete, connect to a mobile device cloud (for example, provided by BitBar or a private cloud managed by Appium), open a testing session, and launch your tested mobile application. You can do it:

    See Connecting to Mobile Device Clouds and Opening Testing Sessions.

  2. Your tested mobile application becomes available to TestComplete. You can explore the application in the Object Browser.

  3. In TestComplete, create a test for your mobile application. In your tests, you can:

    • Simulate touches and long touches of application objects.

    • Simulate swipes.

    • Input text.

    • Verify objects and their properties.

    You write script instructions that simulate user actions manually. See Creating and Running Tests for Mobile Applications Running in Mobile Device Clouds. Recording such instructions will be implemented in one of the future TestComplete releases.

  4. You run your test. The test engine connects to the testing session and simulates user actions over your tested application in it.

  5. After the test is over, you can view the test results in TestComplete.

You can find detailed instructions on creating tests in Creating and Running Tests for Mobile Applications Running in Mobile Device Clouds.

Object hierarchy and object properties

You can view and explore your tested mobile application and its internal objects in the Object Browser in TestComplete:

Explore your tested mobile application in Object Browser

Click the image to enlarge it.

For TestComplete to access your mobile device, there must have a testing session opened on it.

The top-level object for mobile applications running in a mobile device cloud is Mobile. It contains methods and properties for accessing mobile devices to which your TestComplete is connected.

All devices to which TestComplete is connected (on which a testing session is opened) are listed as child Device items of the Mobile node. Properties of these items describe the device and the operating system installed on them. Use methods of these items to simulate user actions over your tested device (for example, touches or swipes).

Process objects correspond to tested applications running on your devices and are shown as child items of your Device nodes.

The hierarchy of objects below the Process node reflects the hierarchy of objects in the appropriate tested application. Names that TestComplete assigns to these objects in the hierarchy are based on the object type, class name, ID, text content (if any).

The objects also have a unique identifier you can use to get them in your tests. You can view the identifier in the Object Browser. It has the same value as the FullName property of the object. The identifier relies on various FindElement methods to get the object:

The unique identifier of an object in a tested mobile application

Click the image to enlarge it.

Addressing objects in tested mobile applications

Before you can simulate user actions over objects in your tested application, you must locate that object. To do this, you can use various FindElement methods:

You can also use various WaitElement methods to pause the test run until the tested object becomes available and various FindElements methods to get all the objects that match the search condition rather than a single object. To learn more, see Addressing Objects in Mobile Applications Running in Mobile Device Clouds.

To locate tested objects in keyword test, you use one of the FindElement methods when specifying the target object of a keyword test operation:

Locating objects in keyword test operations

Click the image to enlarge it.

Currently, name mapping of objects in mobile applications running in device clouds is not supported.

Simulating user actions in tests

To simulate user actions over your tested application, you use methods that TestComplete provides for objects it recognizes in mobile applications:

  • Click

  • Keys

  • Touch

  • LongTouch

  • Drag

Mobile Screen window

In TestComplete, you can use the Mobile Screen window to view and interact with your tested mobile device (be it an emulator or a real device):

View your tested mobile application in the Mobile Screen window

Click the image to enlarge it.

When you interact with your tested mobile device in this window, for example, touch UI elements, perform swipes, or enter text, TestComplete sends the actions to the tested device. The same way, any interactions with the actual device are tracked in this window. This way, you can use the Mobile Screen window to interact with your tested device without accessing it directly.

Supported capabilities

To open a testing session in a mobile device cloud, you use desired capabilities: a collection of key-value pairs that describe the mobile device on which you want to open the session, the application you want to test, and other parameters.

BitBar capabilities

Capability Description Sample value for iOS Sample value for Android
bitbar_apiKey The API key assigned to your BitBar account.

To get the BitBar API key

 CAF22AFB
bitbar_device The name of the mobile device on which you want to run your tests.

You can view the list of devices available to your BitBar account on the Devices page of the BitBar website.

 Apple iPhone 7 Plus 12.1 -US Samsung Galaxy A7 SM-A700F
bitbar_target The type of the automated test: Android or iOS. ios android
bitbar_app The ID of the tested application to be installed on the target mobile device. To get the ID, upload the application file (.apk for Android, .ipa for iOS) to the BitBar storage.

Get the app ID

 1234

Appium capabilities

The following capabilities are applicable to any mobile device cloud managed by Appium (both the BitBar cloud and private clouds):

Capability Description Sample value for iOS Sample value for Android
platformName The name of the mobile OS where you want to open a testing session. iOS android
platformVersion The version of the mobile OS where you want to open a testing session. 14.0 11
deviceName The mobile device or emulator on which you want to run your test. iPhone Simulator Galaxy Z41
udid 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. Hxs7pLHkUZ2O3R74 80A7FO960a61Ye3h
automationName The test automation framework to use. XCUITest UIAutomator2
app 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)		 .apk

More

Available capabilities are not limited to those described above. To learn about other capabilities you can use, please see:

Known issues and limitations

  • Recording user actions is not supported. To learn how to add user actions to tests manually, see Creating and Running Tests for Mobile Applications Running in Mobile Device Clouds.

  • Recording and playing back gestures (multi-touch events) is not supported.

  • Simulating the TouchRelease action on Android devices without simulating the TouchPress action first is not supported.

  • TestComplete may fail to simulate moving a fingertip on an iOS device by using the combination of the TouchPress, Move, and TouchRelease methods.

  • When simulating entering text into a control on an iOS device by using the Keys method, TestComplete may change the state of the target control or clear some of the control’s existing text unexpectedly.

  • When simulating entering text into a control on an iOS device, TestComplete may fail to simulate pressing special keys, like SHIFT, CTRL, or ALT.

See Also

Testing Mobile Applications

Highlight search results