Frequently Asked Questions

Common questions about DeviceLab. Find answers about device setup, test frameworks, CI/CD integration, and troubleshooting.

General

What is DeviceLab?

DeviceLab is a distributed mobile device testing platform that lets you run automated tests on physical devices, emulators, and simulators. It supports multiple test frameworks including Maestro, Appium, Espresso, and XCUITest.

What platforms are supported?

  • Android: Physical devices, emulators
  • iOS: Physical devices, simulators (macOS required for iOS)

What test frameworks are supported?

Framework Android iOS
Maestro ✅ ✅
Appium ✅ ✅
Espresso ✅ -
XCUITest - ✅

How does DeviceLab work?

  1. Device Node connects your devices to DeviceLab
  2. Test Node runs tests on allocated devices
  3. Server coordinates everything and stores results

Device Node

How do I connect my devices?

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh

Replace YOUR_ORG_KEY with your organization ID from the DeviceLab dashboard.

Can I use simulators/emulators?

Yes! Use the --simulators and --emulators flags:

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --name "Austin-QA-Lab-MacMini-1" \
  --simulators "iPhone 16,iPad Pro" \
  --emulators "Pixel_8"

Why aren’t my devices showing up?

  1. Android: Ensure USB debugging is enabled and device is authorized

    bash 
    adb devices  # Should show your device

  2. iOS: Ensure device is trusted

    bash 
    xcrun xctrace list devices  # Should show your device

  3. Check Device Node is running and connected to server

What is TURN relay and when do I need it?

TURN relay routes traffic through servers when direct connection isn’t possible (symmetric NAT, strict firewalls). Enable with:

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --name "Tokyo-Office-MacMini" \
  --enable-turn

Only use if direct connection fails.

How do I run Maestro tests on iOS physical devices?

Set your Apple Team ID:

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --name "SF-QA-Lab-MacPro" \
  --apple-team-id "ABCD1234EF"

Find your Team ID in Xcode → Preferences → Accounts.

Test Node

How do I run tests?

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --name "GitHub - Alpha Release Pipeline" \
  --framework maestro \
  --app ./app.apk \
  --tests ./maestro-tests/

How do I run tests on multiple devices?

Use --device-count:

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --name "GitLab - Nightly Regression Tests" \
  --framework maestro \
  --app ./app.apk \
  --tests ./tests/ \
  --device-count 5

How do I target specific devices?

Use --device-names:

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --name "Jenkins - Cross-Platform Smoke Tests" \
  --framework maestro \
  --app ./app.apk \
  --tests ./tests/ \
  --device-names "Pixel 8,iPhone 15 Pro"

How do I pass environment variables to tests?

Use --cli-params:

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --name "CircleCI - Staging Environment Tests" \
  --framework maestro \
  --app ./app.apk \
  --tests ./tests/ \
  --cli-params "-e USERNAME=test -e PASSWORD=secret"

Maestro

How do I create a Maestro test?

Create a YAML file in your tests directory:

yaml 
# tests/login.yaml
appId: com.example.app
---
- launchApp
- tapOn: "Email"
- inputText: "[email protected]"
- tapOn: "Password"
- inputText: "password123"
- tapOn: "Login"
- assertVisible: "Welcome"

How do I run a specific test suite?

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --name "GitHub - Full Regression Suite" \
  --framework maestro \
  --app ./app.apk \
  --tests ./maestro-tests/ \
  --suite regression.yaml

Why do iOS physical device tests take longer the first time?

DeviceLab builds a Maestro iOS runner for your device on first run (~2-5 minutes). Subsequent runs are much faster (~30 seconds) as the runner is cached.

How do I use environment variables in Maestro tests?

In your test:

yaml 
- inputText: ${USERNAME}

When running:

bash 
--cli-params "-e USERNAME=testuser"

Troubleshooting

“No devices available”

  1. Ensure Device Node is running
  2. Check devices appear in DeviceLab dashboard
  3. Verify devices aren’t allocated to other tests

“App installation failed”

Android:

  • Check APK is signed
  • Verify device has enough storage

iOS Physical:

  • Ensure app is built for physical device (arm64), not simulator (x86_64)
  • Check provisioning profile is valid
bash 
# Check architecture
file MyApp.app/MyApp

“Connection timeout”

  1. Check network connectivity
  2. Verify SERVER_URL is correct
  3. Try enabling TURN relay: --enable-turn

“Tests not found”

  1. Verify test directory exists
  2. Use absolute path if relative fails
  3. Check test files have correct extension (.yaml for Maestro)

“Port already in use”

The nodes will automatically find an available port. If you need to specify a different port, you can set environment variables before running the curl command.

How do I view logs?

Device Node:

bash 
tail -f ./log/devicenode.log

Test Node:

bash 
tail -f ./log/testnode.log

CI/CD

How do I integrate with GitHub Actions?

yaml 
- name: Run Tests
  run: |
    curl -fsSL https://app.devicelab.dev/test-node/${{ secrets.DEVICELAB_ORG_KEY }} | sh -s -- \
      --framework maestro \
      --app ./app.apk \
      --tests ./tests/

How do I integrate with GitLab CI?

yaml 
test:
  script:
    - curl -fsSL https://app.devicelab.dev/test-node/$DEVICELAB_ORG_KEY | sh -s --
        --framework maestro
        --app app.apk
        --tests tests/

Can I run tests in parallel in CI?

Yes, use --device-count:

bash 
--device-count 5

Tests will be distributed across 5 devices.

Getting Help