HeadSpin Documentation

Appium Inspector Integration

What is the HeadSpin Appium Inspector Integration?

You are likely familiar with Appium--the popular open-source tool for automating tests against native, hybrid, and web mobile applications. A part of Appium’s popular feature set is the Appium Inspector, an IDE used to identify the UI elements of a mobile app for use in developing Appium automation scripts. Typically, Appium Inspector would need to be used in tandem with either a real device accessed from your local machine or with a simulator (for iOS) or emulator (for Android) to explore the app view hierarchy. However, HeadSpin has developed a feature that can bypass the extra work of preparing simulators/emulators, downloading the apps for testing, and the various other steps that can be involved with setting up an Appium development environment. This feature is the HeadSpin Appium Inspector integration in the HeadSpin device Remote Control UI.

The HeadSpin Appium Inspector feature allows you to develop Appium scripts using the Appium Inspector IDE directly from the device Remote Control UI. Once you’ve launched your Appium session either directly from the HeadSpin Device List or via any Appium client, the Appium Inspector integration will attach to that session automatically, making the IDE available to you as soon as you open the device for viewing. The integrated Appium Inspector offers a fully browser-based Appium script development experience.

How To Use the Appium Inspector Integration

This guide assumes that you are familiar with Appium and have an active Appium session with a HeadSpin device.

1. Navigate to the Device List in the HeadSpin UI

web browser screen

In your web browser, navigate to the HeadSpin UI and log in. Navigate to the remote control device list for your account.

2. Launch an Appium session to retain a device in the HeadSpin cloud

launch session

To launch a device with an Appium session, click on the button to the right of the “Start” button for the device. Once you have successfully retained a device, the icon beside the retained device (to the left of the Start button) will change and a notification will be displayed while the Appium session is being created.

spin up appium

3. Using the Appium Inspector

A device launched with an attached Appium session will automatically display the Appium Inspector in the task pane to the right of the device display.

appium inspector

From here, you can explore your application on the device itself to identify elements, dive into the app source, and use other helpful features of the integrated Inspector to help you develop your Appium script.

Features of the HeadSpin Appium Inspector Integration

The integrated Appium Inspector enables a fully browser-based Appium development experience. Interacting with the elements listed in the Inspector will be reflected in real time on the device--and interacting with the device itself will also translate to the Inspector. This makes for a smoother, more pleasant experience debugging and developing Appium automation scripts with HeadSpin devices.

To illustrate the serviceability of the integrated Appium Inspector, here is a brief overview of the features you will find within it.

The Inspector window, from left to right, breaks down in the following way:

  • Device view pane
  • Controls pane
    • Source tab
      • App Source
      • Selected Element
    • Actions tab

The device view pane displays what the integrated Inspector is currently seeing--its ‘screenshot’, if you like, of the device screen at the time of the inspection capture. The Appium Inspector identifies elements within this capture as unique items, and when your cursor moves over each element, the Inspector will highlight it.

The Controls pane has two tabs you can select to change your view of the tools at your disposal: the Source tab and the Actions tab.

source vs actions

The Actions tab provides a comprehensive list of common actions that can be taken during your manual test session; by selecting said action, HeadSpin will perform it for you, which can significantly cut down on your testing time and effort. Actions are listed according to what the action in question would interact with: Device, Session, Web, and Context. Once you have selected your target category, the list of potential subcategories of action appears in the next field down. In the example below, the Device target category is selected, then the Interaction subcategory. The available actions appear as interactive buttons below the category fields (in this case, shake screen, lock screen, unlock screen, etc.). Each category has a unique subcategory and action selection.

action tab 1
actions tab 2

The Source tab opens two new panes in its view--the App Source pane, where you can drill down through the app source of your current view of the application to explore, identify, and understand the layers of element hierarchy within the application, and the Selected Element pane. The Selected Element pane includes information about your chosen element, including its element ID, class name, and package name, among many other attributes. This pane also displays Appium Inspector’s suggestions/options for locator strategies for your selected element. The series of icons at the top of the selected element pane offer ways to interact with the selected element. Briefly, those icons are (from left to right):

  • Tap: tap once on the element
  • Send keys: send a sequence of keystrokes to an element
  • Clear: clear an element's value
  • Copy attributes to clipboard: copy the element’s attributes to your local machine’s clipboard
  • Get timing: execute Appium’s suggested locator strategies to determine how long each takes to receive a response

The image below displays an example of the element highlighter and the Selected Element pane at work. This image is also an example of something you may encounter in your use of the Appium Inspector: the captured image of the device did not quite match the speed with which the user interacted with the device in the HeadSpin UI, and so the loaded image in the Inspector is incomplete. Should this happen during your inspection, simply refresh the Inspector to recapture the device screen.

element highlighter

At the top of the integrated Inspector is a taskbar; this is the element interaction modes taskbar, and offers the same functions and features as those you find in the Appium Inspector GUI IDE. Here is a quick summary of the taskbar’s options (from left to right):

  • Mode option - native: This is the default mode in which the integrated Inspector will load. In this mode you can view the source for and interact with an application’s native elements.
  • Mode option - web hybrid: In this mode, Appium will try to discover if any web contexts are available in this capture. If an element does contain a web context, you can choose native or web view modes within the selected element pane. By selecting web view mode, the app source for that element will change to display the HTML source in the app source pane.
  • Element interaction - select: In this interaction mode, you can select an element using the cursor.
  • Element interaction - swipe: In this interaction mode, you can swipe on the screen.
  • Element interaction - tap by coordinates: In this interaction mode, you can tap on an element, which will send the interaction to the device using the coordinates of the touch gesture.
  • Appium command - back (left arrow): Appium’s back command; functions the same as a back button in a browser.
  • Appium command - refresh screen (cycle icon): The Inspector’s device view does not automatically update (a necessary limitation to preserve network demands and other resources), so this icon can be used to refresh the source and screenshot the Inspector is capturing.
  • Appium command - record (eye icon): This launches the Appium recorder and opens the recorder window. Here, you can perform actions, which Appium will record and translate into code. The code’s language or framework can be changed for your convenience. This code can be used in a copy and paste, but please be mindful: these generated codes do not always follow the same best practices a developer would use in writing code.
  • Appium command - search (spyglass icon): This action searches for an element; this can be used as a back-up plan in the event that Appium fails to identify an element with its highlight capability. With this search you can use several strategy options and selector values.

How to Launch Appium Sessions in HeadSpin Using Deep Links

HeadSpin offers the ability for any HeadSpin user to deep link into a device remote control interface with an active automation session. The deep link enables any HeadSpin user with access to the device to the target device(s) to quickly launch an automation session for interactive development or debugging of automation scripts.

1. Navigate to the deep link builder UI here.

deep link builder

2. Select a driver URL from the dropdown menu and enter the desired automation capabilities for the automation session. The driver URL may target hosts with Appium- or Selenium-driven devices or the HeadSpin load balancer.

To target a specific device, use the driver URL and capabilities from the automation configuration for that device in the device list.

The automation configuration may be accessed from the context menu labeled “More Actions”.

more actions
load balanced config

Click on the “Load Balanced Configuration” tab in this menu to see the corresponding load balancer URL and capabilities to target this device model.

3. Customize your capabilities. For example, to enable interacting with the device directly in the remote control UI, add the <code class="dcode">"headspin:controlLock": true</code> capability. For documentation on available capabilities see our Appium, Selenium, and Load Balancer capabilities docs.

control lock cap

Using the control lock capability will open the device in an interactive debugging mode with Appium Inspector (where available).

remote control device

4. To automatically launch the automation session directly when navigating to the deep link, check the “Auto start session” checkbox.

5. Copy the deep link to embed or share.

Known issues