Getting Started with HeadSpin: Setup and First Performance Test

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:

  1. Go to headspin.io and request a trial or demo
  2. After your account is provisioned, log into the HeadSpin dashboard
  3. Navigate to Settings → API Tokens
  4. 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\activate

Install required packages:

pip install Appium-Python-Client pytest requests

Verify 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-mum

Pick 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 -v

Expected output:

test_first.py::test_app_launches PASSED
test_first.py::test_basic_navigation PASSED

2 passed in 47.3s

The 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:

  1. Go to Sessions in the left sidebar
  2. Find your session — it will be labeled "First Test" from the headspin:testName capability
  3. 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:

  1. Tag sessions systematically — add branch and build number tags from CI environment variables
  2. Establish a baseline — run your test suite 10 times to build the Performance AI baseline
  3. Set up CI integration — add HeadSpin tests to your GitHub Actions or Jenkins pipeline
  4. Add custom performance markers — instrument business-critical flows for focused AI monitoring
  5. 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.

Read more

Start now free