Getting Started with HeadSpin: Setup and First Performance Test
Getting from zero to a running HeadSpin test takes about 30 minutes if you already have an Appium setup. If you're starting from scratch, add another 30 minutes for environment setup. This guide walks through the complete process — account setup, local Appium configuration, running your first test on a real device, and reading the performance data that comes back.
Prerequisites
Before starting:
- Python 3.9+ installed
- An APK (Android) or IPA (iOS) file to test — we'll use a sample app in this guide
- Basic familiarity with Appium concepts (desired capabilities, driver commands)
You don't need an Appium server running locally — HeadSpin provides the remote Appium endpoint.
Step 1: Account Setup and API Key
HeadSpin is enterprise software with a sales process — there's no self-serve signup with a credit card. To get access:
- Go to headspin.io and request a trial or demo
- After your account is provisioned, log into the HeadSpin dashboard
- Navigate to Settings → API Tokens
- Create a new API token — copy and store it securely
Your API key is used both as authentication and as part of the Appium endpoint URL, so treat it as a credential.
Store it in your environment:
export HEADSPIN_API_KEY="your-api-key-here"Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist across sessions.
Step 2: Install Python Dependencies
Create a project directory and set up a virtual environment:
mkdir headspin-test && cd headspin-test
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activateInstall required packages:
pip install Appium-Python-Client pytest requestsVerify the Appium client installed:
python -c "import appium; print(appium.__version__)"You should see a version number (2.x or higher). If you see an import error, run pip install --upgrade Appium-Python-Client.
Step 3: Upload Your App to HeadSpin Storage
HeadSpin requires your app to be accessible via URL at test time. You can upload it to HeadSpin's storage or host it yourself (S3, GCS, etc.).
Upload via HeadSpin's storage API:
curl -X POST \
-H "Authorization: Bearer $HEADSPIN_API_KEY" \
-F "file=@/path/to/your/app.apk" \
"https://api-dev.headspin.io/v0/storage/upload"The response contains the URL you'll use in your test capabilities:
{
"url": "https://storage-dev.headspin.io/v0/apps/abc123/your-app.apk",
"app_id": "abc123"
}Save the URL — you'll need it in the next step.
For iOS, you need a .ipa file (not .app). The upload process is identical.
Step 4: Browse Available Devices
Before writing your test, see what devices are available in your HeadSpin account:
import os
import requests
api_key = os.environ["HEADSPIN_API_KEY"]
resp = requests.get(
"https://api-dev.headspin.io/v0/devices",
headers={"Authorization": f"Bearer {api_key}"},
params={"available": True, "platform": "android"}
)
devices = resp.json().get("devices", [])
for d in devices[:10]:
print(f"{d['manufacturer']} {d['model']} — Android {d['os_version']} — {d['location']}")Sample output:
Google Pixel 7 — Android 14 — us-sfo
Samsung Galaxy S24 — Android 14 — us-nyc
Google Pixel 6a — Android 13 — us-sfo
OnePlus 11 — Android 13 — in-mumPick a device for your first test. Note the device_id or use capability-based selection (covered below).
Step 5: Write Your First Test
Create a file test_first.py:
import os
import pytest
from appium import webdriver
from appium.options import AppiumOptions
# --- Configuration ---
API_KEY = os.environ["HEADSPIN_API_KEY"]
APP_URL = os.environ["APP_URL"] # URL from Step 3
APPIUM_ENDPOINT = f"https://{API_KEY}@appium-dev.headspin.io/v0/wd/hub"
# --- Capabilities ---
def get_capabilities():
options = AppiumOptions()
options.platform_name = "Android"
# Standard Appium capabilities
options.set_capability("appium:automationName", "UiAutomator2")
options.set_capability("appium:app", APP_URL)
options.set_capability("appium:newCommandTimeout", 120)
# HeadSpin-specific capabilities
options.set_capability("headspin:capture", True) # Enable video capture
options.set_capability("headspin:capture_network", True) # Enable network capture
options.set_capability("headspin:testName", "First Test") # Label in dashboard
options.set_capability("headspin:tags", ["getting-started", "tutorial"])
# Device selection — capability-based (recommended over hardcoding device ID)
options.set_capability("headspin:selector", {
"os_version": ">=12",
"manufacturer": "google",
"network_type": "wifi"
})
return options
# --- Test Fixture ---
@pytest.fixture(scope="module")
def driver():
options = get_capabilities()
d = webdriver.Remote(APPIUM_ENDPOINT, options=options)
yield d
d.quit()
# --- Tests ---
def test_app_launches(driver):
"""Verify the app starts and the main screen loads."""
# Wait for the app to fully load — adjust the selector for your app
from appium.webdriver.common.appiumby import AppiumBy
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
wait = WebDriverWait(driver, 30)
# Replace with an element that indicates your app has loaded
main_screen = wait.until(
EC.presence_of_element_located((AppiumBy.ID, "com.example.app:id/main_container"))
)
assert main_screen.is_displayed(), "Main screen did not load within 30 seconds"
print("App launched successfully")
def test_basic_navigation(driver):
"""Navigate through a basic user flow."""
from appium.webdriver.common.appiumby import AppiumBy
# Replace with selectors for your app's elements
search_button = driver.find_element(AppiumBy.ID, "com.example.app:id/search_button")
search_button.click()
search_input = driver.find_element(AppiumBy.ID, "com.example.app:id/search_input")
search_input.send_keys("test query")
from selenium.webdriver.common.keys import Keys
search_input.send_keys(Keys.RETURN)
# Verify search results appear
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
results = WebDriverWait(driver, 15).until(
EC.presence_of_element_located((AppiumBy.ID, "com.example.app:id/results_list"))
)
assert results.is_displayed()Update the element locators (com.example.app:id/...) to match your actual app. Use Android Studio's Layout Inspector or Appium Inspector to find element IDs.
Step 6: Run the Test
With your environment set up:
APP_URL="https://storage-dev.headspin.io/v0/apps/abc123/your-app.apk" \
pytest test_first.py -vExpected output:
test_first.py::test_app_launches PASSED
test_first.py::test_basic_navigation PASSED
2 passed in 47.3sThe test takes longer than local testing because it's running on a real device in a remote data center. 40–60 seconds for two simple tests is normal.
Step 7: View Your Session
After the test completes, open the HeadSpin dashboard:
- Go to Sessions in the left sidebar
- Find your session — it will be labeled "First Test" from the
headspin:testNamecapability - Click the session to open the detail view
You'll see:
- Video recording: Full screen capture of the test run
- Network waterfall: Every HTTP request made during the session
- CPU/Memory timeline: Device resource usage throughout the test
- Appium command log: Every command your test sent, with timing
Reading the Performance Data
In the network waterfall, look for:
- Long bars: Slow requests — hover to see exact duration
- Sequential requests: Look for requests that could be parallelized
- Large response sizes: Candidates for compression or lazy loading
In the CPU timeline:
- Sustained high CPU during normal navigation: Often indicates unnecessary computation on the main thread
- Spikes during screen transitions: Expected; investigate if they're longer than 200ms
In the memory graph:
- Monotonic growth over the session: Memory leak candidate
- Sharp drops: Garbage collection events — investigate if they cause visible freezes
Step 8: Understand the Performance Score
HeadSpin assigns a performance score to each session based on key metrics. The score appears in the session detail header and in the sessions list.
Score breakdown:
- App Launch Time: Weight ~25% — cold start to interactive
- Screen Load Times: Weight ~35% — per-screen render performance
- Network Efficiency: Weight ~25% — request count, payload size, latency
- Smoothness: Weight ~15% — frame rate during transitions
A score above 80 is generally good. Below 60 warrants investigation before release.
Common First-Run Issues
"No device available matching selector"
HeadSpin couldn't find a device matching your headspin:selector criteria.
Fix: Broaden the selector — remove the manufacturer constraint, or change os_version to a wider range. Check device availability in the dashboard or via the devices API.
"App installation failed"
The APK URL is inaccessible from HeadSpin's infrastructure, or the APK is corrupt.
Fix: Verify the URL is publicly accessible with curl -I $APP_URL. If using HeadSpin storage, re-upload the file. If the APK was built in debug mode, try a release build — some devices have policies against debug APKs.
"Session timeout after 120 seconds"
Your test spent too long between Appium commands (e.g., waiting for a screen that never loaded).
Fix: Add explicit waits (WebDriverWait) rather than relying on timeouts. Check the session video to see what the device displayed when the timeout occurred.
Test passes locally (emulator) but fails on HeadSpin (real device)
Common reasons:
- Different screen resolution — element locators dependent on position rather than ID
- Real device has different timing characteristics — add longer timeouts
- Network dependency — the test assumes fast localhost responses but gets real network latency
Fix: Replace coordinate-based taps with element ID lookups. Increase wait timeouts. If network-dependent, check whether your test environment's API endpoints are accessible from HeadSpin's PoPs.
Next Steps
Once your first test runs successfully:
- Tag sessions systematically — add branch and build number tags from CI environment variables
- Establish a baseline — run your test suite 10 times to build the Performance AI baseline
- Set up CI integration — add HeadSpin tests to your GitHub Actions or Jenkins pipeline
- Add custom performance markers — instrument business-critical flows for focused AI monitoring
- Configure webhooks — get alerts when Performance AI detects regressions
The investment in the initial setup pays off through the Performance AI layer. Once you have a solid baseline, the platform alerts you automatically when a build introduces a regression — you get the signal without manually reviewing dashboards after every release.