Get Started with Appium Analytics

Install @testrelic/appium-analytics in your WebdriverIO + Appium project and start capturing Android and iOS test analytics in minutes.

Requirements

Requirement	Minimum version
Node.js	18 (Appium 3.x requires ≥ 20.19)
WebdriverIO	9.0.0
Appium	3.x
Android driver	UiAutomator2 (for Android testing)
iOS driver	XCUITest on macOS 13+ with Xcode 15+

iOS requirement

iOS testing requires macOS 13+ with Xcode 15+. iOS tests cannot run on Windows or Linux.

---

For AI agents

Set up with an AI assistant

Copy any prompt below and paste it into your AI coding assistant. Each prompt is self-contained.

---

Full setup (one prompt, does everything)

AI Prompt — Full Appium setup

Set up @testrelic/appium-analytics in this WebdriverIO project:

1. Run: npm install @testrelic/appium-analytics
2. Run: npm install --save-dev webdriverio @wdio/reporter
3. Open (or create) wdio.conf.ts and add:
   - Import TestRelicService from '@testrelic/appium-analytics/service'
   - Import TestRelicReporter from '@testrelic/appium-analytics'
   - Add TestRelicService to the services array with options:
       includeDeviceLogs: true, includeNetworkLogs: true, screenshotOnEvery: 'failure'
   - Add TestRelicReporter to the reporters array with options:
       outputPath: './test-results/testrelic-timeline.json', openReport: true
   - Add an onComplete hook that calls: await TestRelicReporter.finalize(process.cwd())

Show me the complete updated wdio.conf.ts.

---

Step-by-step prompts

Step 1 — Install packages:

AI Prompt — Step 1: Install

Run the following in my project terminal:
npm install @testrelic/appium-analytics
npm install --save-dev webdriverio @wdio/reporter

Step 2 — Configure wdio.conf.ts:

AI Prompt — Step 2: Configure WDIO

Update my wdio.conf.ts to include @testrelic/appium-analytics.

Add these imports at the top:
  import { TestRelicService } from '@testrelic/appium-analytics/service';
  import { TestRelicReporter } from '@testrelic/appium-analytics';

Add to services:
  [TestRelicService, {
    includeDeviceLogs: true,
    includeNetworkLogs: true,
    screenshotOnEvery: 'failure',
  }]

Add to reporters:
  [TestRelicReporter, {
    outputPath: './test-results/testrelic-timeline.json',
    openReport: true,
  }]

Add the onComplete hook:
  async function onComplete() {
    try {
      await TestRelicReporter.finalize(process.cwd());
    } catch (err) {
      process.stderr.write('[TestRelic] Finalization failed: ' + err + '\n');
    }
  }

Show me the complete updated file.

Step 3 — Run the tests:

AI Prompt — Step 3: Run tests

Show me how to start the Appium server and run my WebdriverIO tests.
My WDIO config file is wdio.conf.ts.

---

iOS capability swap

AI Prompt — iOS capabilities

Update the capabilities in my wdio.conf.ts to target an iOS simulator:
  platformName: 'iOS'
  'appium:automationName': 'XCUITest'
  'appium:deviceName': 'iPhone 15'
  'appium:platformVersion': '17.0'
  'appium:app': path to my .app bundle

Show me the updated capabilities block.

For Human

Step 1 — Install the package and peer dependencies

npm install @testrelic/appium-analytics
npm install --save-dev webdriverio @wdio/reporter

Install Appium and the required drivers globally:

# Install Appium
npm install -g appium@latest

# Android driver
appium driver install uiautomator2

# iOS driver (macOS only)
appium driver install xcuitest

---

Step 2 — Configure your WDIO project

Add TestRelicService to services and TestRelicReporter to reporters in your wdio.conf.ts. Call TestRelicReporter.finalize() in the onComplete hook to flush any queued data:

wdio.conf.ts

import { join } from 'node:path';
import { TestRelicService } from '@testrelic/appium-analytics/service';
import { TestRelicReporter } from '@testrelic/appium-analytics';

const REPORT_DIR = join(process.cwd(), 'test-results');

async function onComplete() {
  try {
    await TestRelicReporter.finalize(process.cwd());
  } catch (err) {
    process.stderr.write(`[TestRelic] Finalization failed: ${err}\n`);
  }
}

export const config = {
  runner: 'local',
  port: 4723,
  path: '/',

  specs: ['./tests/**/*.test.ts'],
  maxInstances: 1,

  capabilities: [{
    platformName: 'Android',
    'appium:automationName': 'UiAutomator2',
    'appium:deviceName': 'emulator-5554',
    'appium:app': join(process.cwd(), 'apps', 'MyApp.apk'),
  }],

  framework: 'mocha',
  mochaOpts: { ui: 'bdd', timeout: 60000 },

  services: [
    [TestRelicService, {
      includeDeviceLogs: true,
      includeNetworkLogs: true,
      screenshotOnEvery: 'failure',
    }],
  ],

  reporters: [
    'spec',
    [TestRelicReporter, {
      outputPath: join(REPORT_DIR, 'testrelic-timeline.json'),
      openReport: true,
    }],
  ],

  onComplete,
};

The TestRelicService and TestRelicReporter work together: the service collects raw data during each test (device logs, commands, network traffic, screenshots), and the reporter writes the structured report file after all tests complete.

---

Step 3 — Run your tests

Start the Appium server in one terminal, then run your WDIO tests:

# Terminal 1 — start Appium
appium --address 127.0.0.1 --port 4723

# Terminal 2 — run your tests
npx wdio run wdio.conf.ts

The interactive HTML report is written to ./test-results/testrelic-timeline.html (derived from outputPath) and opened automatically in your browser when openReport: true.

---

iOS configuration

For iOS, change the capability block in your wdio.conf.ts:

capabilities: [{
  platformName: 'iOS',
  'appium:automationName': 'XCUITest',
  'appium:deviceName': 'iPhone 15',
  'appium:platformVersion': '17.0',
  'appium:app': join(process.cwd(), 'apps', 'MyApp.app'),
}],

---

Common setup errors

Cannot find module '@testrelic/appium-analytics/service' Ensure you installed the package: npm install @testrelic/appium-analytics. The /service subpath export requires version ≥ 1.0.0.

Error: UiAutomator2 driver not found Run appium driver install uiautomator2 and verify with appium driver list --installed.

SessionNotCreatedException: An unknown server-side error occurred The Appium server is not running or is not reachable on port 4723. Ensure appium --address 127.0.0.1 --port 4723 is running before starting your tests.

TestRelicReporter.finalize is not a function Ensure the onComplete hook calls TestRelicReporter.finalize(). Without this call, any pending cloud uploads will not be submitted.

Device logs are empty on iOS iOS device log capture requires the safariConsole or syslog log source. Ensure your device is unlocked and the app is foregrounded during the test.

---

What to do next

• Full configuration reference — all AppiumReporterConfig options with defaults
• Cloud quickstart — upload results to the TestRelic platform
• @testrelic/appium-analytics package reference — complete API docs, Android/iOS platform setup, and CLI usage