HeadSpin Documentation

UI Master Guide

Navigating the HeadSpin Platform

You signed up for HeadSpin so that you can test, debug, and gather data for your apps as quickly and efficiently as possible--and we want to help! To that end, this guide exists to help you become familiar with the layout of the HeadSpin UI and give you a high-level understanding of the tools at your disposal within our platform.


The HeadSpin portal functions through our remote cloud network. To access the platform, navigate to the HeadSpin URL and log in to your account.

User Login Panel

Welcome to the HeadSpin platform! After logging into the portal, the Home page will be the first thing you see. Before getting into the details of the Home page, there are a couple items we want to cover first: the User Login panel accessed from the top-right corner of the screen, and the HeadSpin informational toggle in the top-left corner of the screen. These items will appear regardless of which page of the HeadSpin platform you are currently viewing. We’ll also cover the Navigation Bar to the left of your screen before diving deeper into each of the HeadSpin pages.

Panerls Overview

In the upper-right corner, your username, the org your account is associated with, and your role will be displayed. The User Login panel appears on the right side of the screen once you click on your name.

User login
user login panel

The User Login panel displays some basic user information, such as the email address connected to the account, as well as the HeadSpin organizations this account is associated with. If you have access to multiple organizations, you can search for a particular organization within the ‘Search Orgs…’ search bar. To log out of your current account, click the red ‘Sign Out’ button at the bottom of the panel. Typically, customers will only need access to an Enterprise/default account, which looks like this:

Enterprise account panel

However, if your organization should need an additional org account, please feel free to contact HeadSpin for further discussion.

From the User Login panel, you can navigate to user settings by clicking the blue ‘Settings’ button at the top of the panel.

user settings

Within the Settings page you can find your unique API token (for more information see the API Tokens document here), find the contact email for HeadSpin support, enable desktop notifications from HeadSpin, and find a list of helpful downloadable programs such as our HeadSpin CLI or the Appium IDE.

If you have administrative privileges and access to more than one organization account, the HeadSpin toggle in the upper-left corner of any HeadSpin page displays the HeadSpin logo with a dropdown arrow.

admin tools

Clicking this dropdown arrow will bring up a helpful window that reminds you which physical HeadSpin system/environment you are currently working in, which role your account has been assigned, and a brief description of what that role allows as far as permissions go. If you need to view or adjust permissions as an administrator, we invite you to open a discussion with your customer success manager.

Nav Bar

nav bar

The Navigation Bar, or Nav Bar, contains shortcut links in the form of icons that will take you to different parts of the HeadSpin UI. From top to bottom, those links are:

  • Org Dashboard/Team Settings
  • Usage
  • Home
  • Remote Control
  • Performance Sessions
  • Performance Monitoring
  • Dashboards
  • Product Tour (where applicable)
  • Documentation
  • Copyright

Let’s take a closer look at each of these areas of the HeadSpin platform.

ADMINISTRATIVE PAGES - Org Dashboard and Usage Page


The first two icons in the Nav Bar will take you to the Org Dashboard/Team Settings Page and Usage Page respectively.

Org Dashboard/Team Settings

The Org Dashboard page is where an organization owner can view information regarding how the company’s HeadSpin instance is organized for your user accounts and user groups; if you are not an org owner (meaning you have the role of an admin or a team member), this icon navigates to the Team Settings Page instead. For non-org owner accounts, this page will only display information for your assigned team.

team settings

For organization owner accounts, the Team Settings icon changes to the Org Dashboard icon (note the change in the screenshot below). Org Dashboard has the following tabs for navigation displayed at the top of the page:

  • Teams: View information about all teams/user groups for this org.
  • Users: View information regarding all user accounts in this org.
  • Owners: View information for your org owner account(s).
  • Hosts: View information regarding host machines assigned to this org and their locations.
  • Devices: View all devices listed for your organization and associated details.
  • SSO: View and modify settings for your SSO configuration, including OAuth and SAML.

The Teams, Users, and Owners tabs also contain the option to create a new instance of the item with which that tab is associated; for example, the Teams tab allows you to create a new team, and the owners tab allows you to create a new Org Owner. Each tab (with the exception of SSO) has a specific search bar that will allow you to search the contents of your org for a specific item (such as a particular user account or device).


The Usage icon takes you to the Usage page, which displays your device usage metrics. The Usage tab displays a collection of graphs detailing your organization’s device usage metrics. There are graphs measuring usage in terms of total hours, number of days or number of sessions, average duration of sessions, and more. You can also modify the window of time these graphs measure; the default settings display usage over the course of the last 30 days (ending with the current date), but you can change these dates to reflect the time you would like to review. The Export button exports your usage metrics data as a .csv file.

device usage dashbaord

The Device Usage tab of the Usage page displays recent device usage data in something more like a list format. Devices will be listed by Device ID, but can also be arranged according to hostname, manufacturer, model, or device type; the default list of these recently used devices is ordered chronologically. You can filter the device list by ID types not included in these default categories (such as user ID of the tester account) or search for a specific ID to view usage data for a specific device.

recent device usage

TESTING PAGES - Home, Remote Control, Performance Sessions, Performance Monitoring, and Dashboards

testing pages icons

The five icons in the middle of the Nav Bar will take you to the pages within the HeadSpin UI that handle executing tests, retaining devices, and analyzing data. The first icon takes you to the Home page; let's start there.


dashboard home

The Home page is the default page your browser will navigate to once you’ve logged in to HeadSpin. The Home page displays several useful things, including helpful shortcuts or information regarding common testing, information about your testing user flows, and--perhaps most important for new users of HeadSpin--an onboarding checklist to guide a new user in the various activities they should become familiar with in the use of HeadSpin. (To clarify: a user flow is essentially a group of tests with the same user intention, such as a suite of tests to gauge network response time in an application when a hypothetical user is accessing a particular page within the app.) The checklist also tracks your progress in completing these tasks and will reflect when you have completed one of the recommended tasks in the list.

Remote Control

remote device lists

The Remote Control page is arguably where you will conduct the bulk of your testing activities. By default, the Remote Control page loads on the Devices tab, the second of three tabs. The three tabs found on this page are:

  • Hosts: View info about the available host machines and their geographic locations.
  • Devices: View a list of devices and their associated information, such as device status and ID.
  • Remote: This tab will only activate once a session has been opened on a device. Once you open a session, this tab displays a live interactive view of the selected device and allows you to perform a manual test on that device.

Both the Hosts and Devices pages have search bars located near the top of the page to assist you in locating specific host or device machines. On the Devices tab page, you can add a new device to your device list. You can also choose how you want to launch a session on a device from your device list: the ‘Start’ button will take you to the live device view in the Remote tab (what could be considered a standard session), while the Appium logo button to the right of the ‘Start’ button will open an Appium session on the device.

The Remote tab contains a panel to the left side of the page displaying a live view of the device; this display is also interactive, receiving and responding to touch, swipe, and virtual keyboard prompts as a device in hand would do. The right panel contains several tools and settings options you can use during your test, including the capture of screenshots, logs, and automation configuration data. If you open an Appium session, rather than a standard manual one, HeadSpin will take you to the Remote tab like normal and have the same options as a standard session, but additionally you will see the Appium Inspector integration panel and be able to interact with the device using the various tools provided by the Inspector. (For more information on the Appium Inspector, click here.)

remote device dashbaord

On any tab of the Remote Control page, you will see an icon at the bottom of the screen called ‘Device Tray’.

device tray

Clicking this button brings up the HeadSpin device tray, which shows any devices you have an active session on, as well as any devices recently used in a session by the currently logged-in user. These can be used for reference in capturing multiple devices for automated tests. A device upon which a session is launched will automatically be added to your device tray; if you wish to add a particular device to your tray, click the ‘+’ button to the left of a device’s listing. To remove a device from your tray, you can click the Clear button within the tray (this will remove all devices from the tray), click the ‘X’ button beneath a specific device within the tray, or find the device in the device list and click the ‘X’ icon to the left of the Start button on the device’s listing. (The ‘+’ button transforms into the ‘X’ button once a device is in your tray.)

device tray dashbaord

Performance Sessions

performance session dashboard

The Performance Sessions tab (“P” tab) displays a list of sessions in chronological order, beginning with the most recent, and contains general information about each session in the list. This information includes the device model, its location/host machine, the start time of the session, any test user flows applied during the session, and network events or issues detected during the session. If any tags are assigned to a session, these are displayed as well; you can filter the displayed session list by tags in the ‘Filter sessions’ bar. Each session also has the option (once it is completed) to view its data in Waterfall UI or Burst UI mode. Waterfall UI provides a comprehensive package of data captured during your session, including session-wide metrics, timeseries statistics and data, and detected issues listed according to impact time. Issue UI delivers data regarding network performance issues specifically.

Performance Monitoring

performance monitoring dashboard

The Performance Monitoring tab ("M" tab) displays information regarding your user flows, containing the majority of the data you will want to use in drawing conclusions from your testing. The Monitoring page informs you of each user flow’s name, description (if provided), and creation time. You can create a new user flow from this page, or you can review the details of a particular user flow by clicking on the flow’s hyperlinked name.

performance monitoring UF

Upon clicking a user flow’s name, you are redirected to an interactive data page for that user flow, where you can select a data set, device, and locations for data comparison. You can also interact with regressions for selected issues and review the associated Replica data for your chosen user flow. Replica databases allow you to create tables of custom queries to make your data even more specific to your use case; the tables allow you to create queries for sessions inside user flows as well as across user flows. Replica data can then be displayed in custom Replica Dashboards, described below.



The Dashboards page gives you the opportunity to set up and view helpful information at a glance for your more common testing queries or needs. HeadSpin uses Grafana to create these dashboard instances. HeadSpin can automatically provision a Grafana account that will link to the Replica database with exported user flows and custom query tables, which can then be used to create unique dashboards. These custom data collections will better assist you in monitoring various KPIs and simplifying the collection and synthesis of other business intelligence.

HeadSpin University

headspin university

Created by Jonathan Lipps, Appium project lead and architect, HeadSpin University is our educational tool to provide additional context for and assistance with testing tools such as Appium and Selenium. Using these courses you can gain hands-on training in various topics, and upon completion of the courses you will be awarded with certification appropriate to the course.

university course page

The University page displays a selection of courses on offer, as well as the news feed for the HeadSpin University program and a link at the bottom of the page to assist you with signing up/enrolling in HeadSpin University.

INFORMATIONAL PAGES - Product Tour, Documentation, Copyright

informational page icons

The three icons at the bottom of the Nav Bar are for informational purposes. (Note that the Product Tour icon will only appear on relevant pages, so in some parts of the UI it may look like only two icons are available.) The topmost icon is the Product Tour icon.

Product Tour

product tour
product tour progress

The Product Tour icon in the Nav Bar doesn’t actually lead you to a unique page--rather, this icon appears for certain pages within the HeadSpin space to act as an educational guide and teach you how to use the HeadSpin tech in real time. The Product Tour appears when you are on the Org Management, Remote Control, Performance Sessions, Performance Monitoring, and Dashboard pages. While on any of these pages, click the Tour icon to launch a task pane on the left side of the screen that shows you the areas the tour will teach you about. While the tour is active, click the orange circle icon (it will be found in various places on the screen depending on which section of the tour you’re in) to progress. You can exit the tour at any time by clicking the ‘End tour’ button, or by clicking the white ‘X’ icon in the upper left corner of the tour task pane.


Docs page

The Documentation icon will take you to our documentation page, hosted alongside our product. The various documents we have regarding our platform, toolsets, assistance with automation, and release notes can be found there. This section also contains our license agreement, should that be necessary for legal purposes for your organization.


HeadSpin platform onboarding checklist

Like the Product Tour icon, this icon also does not technically launch a standalone page; instead, clicking this icon from any page in the HeadSpin space will display the HeadSpin copyright information at the bottom of the screen, as well as our Terms of Use and Privacy Policy.

This concludes the general overview of the HeadSpin platform. If you have any questions, please feel free to contact us at helpdesk@headspin.io, or visit our Documentation page for more information.