Remote Debugging

HeadSpin supports any test framework by exposing HeadSpin platform devices as locally connected devices. Once a device is connected, you can interact with it through Xcode, Android Studio and any other tool^[1] as if the device was physically connected to the local machine.

Prerequisites

Remote debugging requires our proprietary CLI. Please follow the instructions and install the latest version of the CLI for your platform.

You will also need a HeadSpin API token. Please read more on how to get your API token.

iOS

Note Regarding iOS 17

Currently HeadSpin does not support the full use of our toolset with devices running iOS 17. This includes limitations to our CLI commands, pintap tools, and biometric testing. When this functionality is enabled, this section will be updated. For more information on what is and is not supported on iOS 17 devices, please see our iOS 17 support documentation.

Windows Users and iOS

A note for users testing iOS on Windows machines: In order to properly support iOS device testing on a Windows machine, you will need to install iTunes for Windows. However, iTunes MUST NOT be installed from the Microsoft Store; this version of the program will not have the necessary support components. Please only install iTunes from Apple’s support page using one of the links under “If you can’t access the Microsoft Store”. By default, Apple will offer the current version of iTunes for download; we recommend installing this, rather than looking for a legacy version of iTunes. (If you are using an older version of iTunes, we also recommend updating to the most up-to-date version compatible with your Windows OS.) After this is done, iOS devices can be attached to Windows. They will not be visible in iTunes itself, but they will be connected as network devices and can be seen following the proper steps with the our CLI tool.

Connecting an iOS device to your local machine

The easiest way to connect an iOS device to your local machine is to retrieve the correct CLI command from the HeadSpin UI. You can access the command by opening the remote control view for the iOS device you'd like to use and looking for the Remote Debug section in the Overview tab. It shows the exact command that you should run. After running the command, you should see output similar to:

$ hs connect -t <your_api_token> 036171ce957c7ef68c021f388febe4f0ac7c0ba0@proxy-us-mvo-6.headspin.io
1/1 036171ce957c7ef68c021f388febe4f0ac7c0ba0@proxy-us-mvo-6.headspin.io  connected
==> 036171ce957c7ef68c021f388febe4f0ac7c0ba0 available locally

You can verify that the device is connected by opening Xcode, accessing the Window menu from Xcode's top menu bar, and selecting Devices and Simulators. The connected device should appear in the side bar. Note that when a device is connected for the first time, Xcode must prepare the device before it can be used. This is covered in the next section.

If you wish to do the same programmatically, you will need to know the HeadSpin device address of the device you'd like to use. These can be retrieved from the UI or via the API. Device addresses in general do not change unless the physical device is moved to a different host, so you can keep using the same device address for the same device. Device IDs as well as other selectors can also be used but they are not guaranteed to be unique among a pool of devices. If a selector matches multiple devices, all matching devices that are available are connected. The format for the command is:

$ hs connect -t <your_api_token> SELECTOR

Use HeadSpin devices with Xcode

Note that when a device is connected to a machine for the first time, Xcode must download a set of debug symbols from the device. This is a one time operation per device. You can see whether the symbol download is still in progress by accessing the Window menu from Xcode's top menu bar, and selecting Devices and Simulators. The connected device should appear in the side bar. After selecting the device from the side bar, if the symbol download is still in progress, you will see a light yellow panel at the top of the window, saying that the device is busy. Unfortunately Xcode does not report exact progress during the download, only whether it is still in progress or not. The time to complete the symbol download depends on network conditions but is expected to take at least a few minutes.

After selecting a working project, remote devices can be found in Xcode's top bar.

Click on the Test button see a list of available devices. The device name shown in Xcode varies by device. You can see the device UDID in the Devices and Simulators window.

Now you can run tests and debugging on remote devices from Xcode per Apple's XCTest framework's documentation.

Android

Note that you must have Android Studio (or ADB installed separately) in order to use Android devices. HeadSpin requires adb 1.0.41 or newer. If you use an older version you may encounter failed app installs as well as other issues. You can check your local ADB version by running <code class="dcode">adb version</code>.

Connecting an Android device to your local machine

The easiest way to connect an Android device to your local machine is to retrieve the correct CLI command from the HeadSpin UI. You can access the command by opening the remote control view for the Android device you'd like to use and looking for the Remote Debug section in the Tools tab. It shows the exact command that you should run. After running the command, you should see output similar to:

$ hs connect -t <your_api_token> 066add630acc41a8@proxy-us-mvo-5.headspin.io
1/1 066add630acc41a8@proxy-us-mvo-5.headspin.io  connected
==> Nexus-5-066add630acc41a8.proxy-us-mvo-5.hs.headspin.io:55095 available locally

You can verify that the device has been connected by running <code class="dcode">adb devices</code>:

$ adb devices
List of devices attached
Nexus-5-066add630acc41a8.proxy-us-mvo-5.hs.headspin.io:55095  device

If you wish to do the same programmatically, you will need to know the HeadSpin device address of the device you'd like to use. These can be retrieved from the UI or via the API. Device addresses in general do not change unless the physical device is moved to a different host, so you can keep using the same device address for the same device. Device IDs as well as other selectors can also be used but they are not guaranteed to be unique among a pool of devices. If a selector matches multiple devices, all matching devices that are available are connected. The format for the command is:

$ hs connect -t <your_api_token> SELECTOR

Use HeadSpin devices with Android Studio

After a device has been connected to the local machine, you can run tests on it with adb or use it with Android Studio. To run your app on a remote device, in Android Studio click on the Run App button.

A dialog will appear with the list of devices you have access to. HeadSpin Android devices connected with the remote list can also been seen and selected here.

Note that by default, quitting or restarting Android Studio may also stop <code class="dcode">adb</code>, which then disconnects all devices. If this happens you will have to connect the device or devices again.

1: Tools that require direct access to USB or other hardware interfaces are not supported.