Running Mobile Tests on DeviceLab

The Test Node executes automated mobile tests on devices connected to your DeviceLab private device farm. This guide covers running tests using Maestro, Appium, Espresso, and XCUITest frameworks on real Android and iOS devices. You’ll learn how to configure test runs, select devices, run tests in parallel, and integrate with CI/CD pipelines.

Before running tests, make sure you have connected your devices to DeviceLab.

Quick Start

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework maestro \
  --app ./app.apk \
  --tests ./tests/

Replace YOUR_ORG_KEY with your organization ID from the DeviceLab dashboard.

Command Line Options

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- [OPTIONS]

Options:
  --name           Custom name for this test run
  --framework      Test framework: maestro, appium, espresso, xcuitest
  --app            Path to app file (.apk, .ipa, .aab, .app)
  --tests          Path to test files or directory
  --suite          Specific suite file (Maestro only)
  --platform       Target platform: ios or android
  --device-names   Comma-separated specific device names
  --device-count   Number of devices to use (default: 1)
  --test-timeout   Timeout in minutes per test
  --cli-params     Parameters to pass to test framework

For the complete CLI reference, see Test Node CLI Reference.

Supported Frameworks

Framework --app --tests Platform Docs
maestro Required Required (directory) Android, iOS Maestro Docs
appium Required Not used Android, iOS Appium Docs
espresso Required (APK) Required (test APK) Android Espresso Docs
xcuitest Required Required (test bundle) iOS XCUITest Docs

Note: For Appium, you run your tests separately after starting the test node. See Appium Testing Guide.

Device Selection

DeviceLab acts as your private device farm for running automated tests. You can target specific devices or run on any available device.

Parallel Testing on Multiple Devices

Run tests simultaneously across multiple devices for faster execution:

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework maestro \
  --app app.apk \
  --tests flows/ \
  --device-count 5

This distributes your test suite across 5 devices, significantly reducing total execution time.

Specific Devices

Request specific devices by name:

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

Default (Single Device)

If neither --device-count nor --device-names is specified, tests run on 1 available device:

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework maestro \
  --app app.apk \
  --tests flows/

Platform Auto-Detection

Platform is auto-detected from app file extension:

Extension Platform
.apk, .aab Android
.ipa, .app iOS

Override with --platform:

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework maestro \
  --app app.apk \
  --tests flows/ \
  --platform android

Framework Examples

Maestro

bash 
# Basic
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework maestro \
  --app app.apk \
  --tests maestro-tests/

# With suite file
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework maestro \
  --app app.apk \
  --tests maestro-tests/ \
  --suite regression.yaml

# With environment variables
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework maestro \
  --app app.apk \
  --tests maestro-tests/ \
  --cli-params "-e USERNAME=test -e PASSWORD=secret"

# Parallel testing on multiple devices
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework maestro \
  --app app.apk \
  --tests maestro-tests/ \
  --device-count 5

See Maestro Testing Guide for more details.

Appium

Appium works differently - you start the test node, then run your tests separately:

Terminal 1 - Start Appium server:

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework appium \
  --app app.apk

Terminal 2 - Run your tests:

bash 
mvn clean test   # Java
pytest           # Python

Your tests connect to http://localhost:4723/wd/hub. See Appium Testing Guide for details.

Espresso

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework espresso \
  --app app.apk \
  --tests app-test.apk

XCUITest

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework xcuitest \
  --app MyApp.ipa \
  --tests MyAppUITests.xctest

Test Timeout

Set timeout per test (in minutes):

bash 
curl -fsSL https://app.devicelab.dev/test-node/YOUR_ORG_KEY | sh -s -- \
  --framework maestro \
  --app app.apk \
  --tests flows/ \
  --test-timeout 30

Default timeouts vary by framework.

CI/CD Integration

DeviceLab integrates seamlessly with popular CI/CD platforms. Store your DEVICELAB_ORG_KEY as a secret in your CI system.

GitHub Actions

yaml 
name: Mobile Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

GitLab CI

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

Jenkins

groovy 
pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                sh '''
                    curl -fsSL https://app.devicelab.dev/test-node/${DEVICELAB_ORG_KEY} | sh -s -- \
                      --framework maestro \
                      --app app.apk \
                      --tests maestro-tests/
                '''
            }
        }
    }
}

Troubleshooting

“No devices available”

  • Ensure the Device Node is running on your device host machine
  • Verify devices appear in the DeviceLab dashboard
  • Check that devices match the requested platform (Android vs iOS)
  • See Connecting Devices for setup help

“App installation failed”

  • Verify app is signed correctly for the target device
  • For iOS physical devices, check provisioning profile includes the device UDID
  • For Android, ensure USB debugging is enabled
  • Try installing the app manually first to verify it works

“Tests not found”

  • Verify path exists: ls -la ./maestro-tests/
  • Use absolute path if relative path fails
  • Check file permissions on the test directory
  • For Maestro, ensure .yaml flow files are in the directory

“Connection timeout”

  • Check network connectivity between test node and device node
  • Verify firewall allows WebRTC connections
  • Check Environment Variables for proxy settings

“Test execution slow”

  • Use parallel testing with --device-count to distribute tests
  • Check device performance (free up device memory/storage)
  • Review test design for unnecessary waits

Viewing Test Results

All test results, logs, screenshots, and video recordings are available in the DeviceLab dashboard. You can also export results in JUnit XML format for CI/CD integration.

Frequently Asked Questions

What test frameworks does DeviceLab support?

DeviceLab supports Maestro, Appium, Espresso (Android), and XCUITest (iOS). Your existing tests work without code changes.

How do I run tests in parallel on multiple devices?

Use the --device-count flag to specify how many devices to use. For example, --device-count 5 runs your tests across 5 devices simultaneously.

Can I run DeviceLab tests in CI/CD pipelines?

Yes. DeviceLab integrates with GitHub Actions, GitLab CI, Jenkins, and any CI system that can run shell commands. Just add your org key as a secret.

How do I debug failed tests on DeviceLab?

Check the DeviceLab dashboard for test logs, screenshots, and video recordings. Use --cli-params to pass verbose flags to your test framework.

What’s the difference between DeviceLab and cloud device farms?

DeviceLab runs on YOUR devices in YOUR network. Data never leaves your infrastructure, you control the hardware, and there are no per-minute charges.

Next Steps