Appium Cloud Quickstart

Connect your Appium/WDIO project to the TestRelic cloud platform in under 10 minutes. You will create an account, generate an API key, configure the reporter, and explore your first mobile test run in the cloud dashboard.

Prerequisites

• An existing Appium/WDIO project with @testrelic/appium-analytics installed and working locally
• A testrelic.ai account (create one for free below)

If you have not set up the reporter locally yet, start with the Appium Installation guide.

---

Step 1 — Create your account

1. Go to testrelic.ai and click Sign Up.
2. Enter your name, email address, and a password.
3. Check your inbox for a verification code and enter it on the verification screen.

Onboarding wizard

After verifying your email, the onboarding wizard walks you through setting your profile, choosing Appium as your framework, and generating your first API key. See the Onboarding guide for the full walkthrough.

---

Step 2 — Generate an API key

1. In the TestRelic platform, navigate to Settings → API Keys.
2. Click Create new key, give it a name (e.g. my-appium-project), and copy the key value.
3. Store it securely — the key is shown only once.

---

Step 3 — Configure cloud upload

For AI agents

Configure with an AI assistant

AI Prompt — Add cloud config to wdio.conf.ts

Update my wdio.conf.ts to enable TestRelic cloud upload.

1. Add 'import dotenv/config' at the top of the file (install dotenv if not present: npm install --save-dev dotenv).
2. Add the cloud key to the TestRelicReporter options:
   cloud: {
     apiKey: process.env.TESTRELIC_API_KEY,
   }
3. Create a .env file in the project root with:
   TESTRELIC_API_KEY=my_key_here
4. Add .env to .gitignore.

Show me the updated reporter options and the .env file.

---

Set up CI with an AI assistant

GitHub Actions

AI Prompt — GitHub Actions for Appium

Create a GitHub Actions workflow file at .github/workflows/appium.yml that:
1. Runs on push and pull_request
2. Uses node 20
3. Runs npm ci
4. Starts the Appium server in the background: npx appium --address 127.0.0.1 --port 4723 &
5. Runs WDIO tests: npx wdio run wdio.conf.ts
6. Passes TESTRELIC_API_KEY from GitHub secrets as an environment variable

Show me the complete workflow file.

GitLab CI

AI Prompt — GitLab CI for Appium

Create a GitLab CI configuration (.gitlab-ci.yml) for my Appium project that:
1. Uses the node:20 image
2. Passes TESTRELIC_API_KEY from GitLab CI variables
3. Runs npm ci in before_script
4. Starts Appium in the background: npx appium --address 127.0.0.1 --port 4723 &
5. Runs: npx wdio run wdio.conf.ts

Show me the complete .gitlab-ci.yml file.

For Human

Add the cloud config to your WDIO reporter

Add the cloud key to your TestRelicReporter options in wdio.conf.ts:

wdio.conf.ts (cloud config)

import { TestRelicReporter } from '@testrelic/appium-analytics';

// ... rest of your config

reporters: [
  'spec',
  [TestRelicReporter, {
    outputPath: './test-results/testrelic-timeline.json',
    cloud: {
      apiKey: process.env.TESTRELIC_API_KEY,
    },
  }],
],

Store the API key in a .env file in the root of your project (never commit this file):

.env

# Never commit this file — add .env to .gitignore
TESTRELIC_API_KEY=your_api_key_here

Load the .env file at the top of wdio.conf.ts:

wdio.conf.ts (top)

import 'dotenv/config';

Or install and use dotenv: npm install --save-dev dotenv.

---

CI configuration

GitHub Actions

Add TESTRELIC_API_KEY as a repository secret in Settings → Secrets and variables → Actions, then reference it in your workflow:

.github/workflows/appium.yml

name: Appium Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Start Appium
        run: npx appium --address 127.0.0.1 --port 4723 &
      - name: Run WDIO tests
        run: npx wdio run wdio.conf.ts
        env:
          TESTRELIC_API_KEY: ${{ secrets.TESTRELIC_API_KEY }}

GitLab CI

.gitlab-ci.yml

appium:
  image: node:20
  variables:
    TESTRELIC_API_KEY: $TESTRELIC_API_KEY
  before_script:
    - npm ci
    - npx appium --address 127.0.0.1 --port 4723 &
  script:
    - npx wdio run wdio.conf.ts

---

Step 4 — Run your tests

Start Appium and run your WDIO tests as usual:

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

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

After the run completes and TestRelicReporter.finalize() is called in onComplete, the reporter uploads the test data to the cloud platform. You should see a confirmation in the terminal output:

✓ TestRelic: Run uploaded — https://testrelic.ai/dashboards/test-runs/<runId>

---

Step 5 — Explore the result in the platform

1. Click the URL printed by the reporter, or navigate to the Test Runs dashboard.
2. Click your run to open the Run Detail view.
3. Click any test case row to open the Session Workspace — device commands, logs, screenshots, network traffic, and timeline.

---

Troubleshooting

"API key invalid" error Double-check the TESTRELIC_API_KEY value in your environment. Ensure there are no extra spaces. Verify the key is active in API Keys settings.

No run appears in the dashboard Ensure TestRelicReporter.finalize() is called in the onComplete hook. Without this call the upload does not complete. Also ensure your network can reach platform.testrelic.ai.

Run appears but device logs are missing Enable includeDeviceLogs: true in your TestRelicService options. For iOS, ensure preferBiDi: true (default) and that the device is a physical device or simulator running on macOS.

Network traffic not captured Set includeNetworkLogs: true in TestRelicService options. Network capture uses BiDi by default (preferBiDi: true). If BiDi is not available for your Appium version or driver, the reporter falls back to a proxy-based interceptor automatically.

Upload fails with a network error The reporter queues failed uploads locally and retries on the next run. The queue directory defaults to a system temp path — configure queueDirectory in the cloud options if you need a specific path. Queue entries expire after 7 days by default (configurable via queueMaxAge).

---

What to explore next

Feature	What to try
Session Workspace	Inspect device commands, console logs, screenshots, and network traffic
AI Insights	On a failing test, check the Insights tab for AI-generated defect analysis
Repositories	View repo-level health metrics and pass rates
Full configuration reference	All AppiumReporterConfig options