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.

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

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.

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.

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