HeadSpin Documentation

TestProject - Using Tricentis' TestProject with HeadSpin

Note Regarding Deprecation:

TestProject will no longer be available for use after March 31, 2023. This document will be located in the Deprecated section of HeadSpin documentation for legacy users' reference.

Overview: HeadSpin and TestProject

TestProject is an open-source end-to-end automation tool developed by our partners at Tricentis, built on Selenium and Appium frameworks to make the testing process easier and more efficient. Combining the use of TestProject’s library with HeadSpin’s easy-access devices and powerful data capture gives you the best of both worlds. To assist you in using HeadSpin and TestProject together, this guide will outline the necessary components and steps to run both programs together.


  • HeadSpin and TestProject accounts
  • Access via HeadSpin interface to the devices you want to use with TestProject
  • TestProject agent downloaded, installed and registered
  • hs CLI tool downloaded and installed
  • HeadSpin API token generated

Please note that in order to have compatibility with iOS devices, you MUST have at least HeadSpin CLI version 202202.50.0. If you have an older version of the CLI installed on your testing machine, please download and install the latest version (to locate the CLI download link, see below).


A note about use of TestProject on Windows machines for iOS compatibility: In order to properly support iOS device testing on a Windows machine, you 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, 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 HeadSpin CLI tool.

Access to your accounts and devices will be managed by your admins. To download and install the TestProject agent, visit this TestProject link.

Both the download link for the HeadSpin CLI tool and your HeadSpin API token can be found in the User Settings area. To access these settings, click on the User Login panel in the upper-right corner of your screen after login.


Within the panel that appears, click the blue 'Settings' button beside your username and email.


The API token is listed in the first box of the settings page; if you would like to generate a new token, click the '+ New Token' button. The HS CLI is the first item listed in the Downloads box further down the settings page, with links to the documentation as well as several different downloads of the program; choose the appropriate file for compatibility with your OS.

Using HeadSpin Android Devices with TestProject

Step 1: Launch a session with your selected device.


Step 2: Get the <code class="dcode">hs connect</code> command from the HS UI in the Tools section of the device’s Remote Control view.


Step 3: Run the <code class="dcode">hs connect</code> command (displayed below as it is found in the UI) in a terminal. (On Windows PowerShell, this command is <code class="dcode">.\hs.exe connect</code>.)


Step 4: Verify the device is connected via ADB by running <code class="dcode">adb devices</code> within your terminal.


Step 5: When the device is connected to ADB, TestProject should automatically pick it up from your local machine via its agent. The device will appear in the TestProject UI under the 'Devices' tab in your navigation sidebar. (TestProject's UI is accessed via browser.)


Before you can use the HeadSpin device with TestProject, you’ll need to authorize its use. Once you have logged in to the TestProject web page, click the Agents tab in the navigation bar at the top of the screen, then click the Devices tab in the sidebar to the left. Find the device in the agents list and click on the blue 'Authorize' button. TestProject will ask for confirmation that you'd like to add the new device to the list of authorized devices. Click 'Yes'.


Now use your device with TestProject just like you would any other!

Using HeadSpin iOS Devices with TestProject

Step 1: If testproject-agent is currently running on your testing system, stop testproject-agent to prevent program interference.

Step 2: Run the command: <code class="dcode">hs exec testproject-agent start</code> in a terminal window. Note that the <code class="dcode">hs exec</code> prefix is essential; if this prefix is not included, HeadSpin iOS devices will not be visible to the TestProject agent. Also note that this program will remain active and running in this terminal window.


Step 3: Launch a session with your selected device.


Step 4: Get the <code class="dcode">hs connect</coded> command from the Overview section of the device’s Remote Control view. Please note that this location is different from the location for the <code class="dcode">hs connect</code> command for Android devices.


Step 5: Run the <code class="dcode">hs connect</code> command in a separate terminal window from the terminal window running the TestProject agent. You will see the device connect with the HeadSpin CLI, and simultaneously, the TestProject agent will detect the device; displayed below, the CLI is in the first image and the TestProject agent is in the second.


As with Android devices described above, iOS devices will need to be authorized in TestProject. If the device you are connecting to is new to the TestProject agent list, you will see the Device Authorization prompt:


Otherwise, navigate to the Devices tab of the Agents section of the TestProject web page as described above, find the device in the agents list, and click on the blue 'Authorize' button. In either case, click 'Yes' to authorize the device.

Important Note: For usage of both iOS and Android devices with TestProject, due to the manner in which the CLI functions, a device presented to TestProject as an agent becomes permanently unavailable for other users on the HeadSpin platform for remote testing or other uses. This is because the device is considered in permanent use by TestProject in order to avoid conflicts with test runs or device usage. Please keep this in mind when selecting which HeadSpin devices you would like to use with TestProject.