Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 37 ยท CI and Best Practices

Appium in CI: GitHub Actions and Emulators

Run Appium tests in continuous integration: install the server and drivers, start an Android emulator or iOS simulator, wait for readiness, and upload artifacts.

Tests that run only on someone's laptop protect nobody. Continuous integration (CI) runs them automatically on every pull request or nightly, on a clean machine, so a broken build is caught within minutes. Mobile CI is more demanding than web CI because you need an emulator or simulator, the Appium server with the right drivers, and a build of the app. This lesson walks through a pipeline step by step with GitHub Actions as the example; the ideas carry over to GitLab CI, Jenkins, CircleCI, Bitrise or Azure Pipelines.

None of this can run on this site, so the workflow files are read-only. The runnable stand-ins check a configuration and parse a server log, which are the kinds of small scripts that keep pipelines healthy.

The pipeline at a glance

flowchart LR
    A["Checkout"] --> B["Build app"]
    B --> C["Install Appium + drivers"]
    C --> D["Start emulator or simulator"]
    D --> E["Start Appium server"]
    E --> F["Run tests"]
    F --> G["Upload videos, logs, reports"]

Every step must finish, or fail loudly, before the next begins.

Choosing the runner

  • Android on Linux: GitHub's Ubuntu runners support hardware acceleration (KVM) for emulators. This is the cheapest and fastest option.
  • iOS: you need macOS runners with Xcode and simulators installed. They cost more and queue longer, so run a smaller iOS set per pull request.
  • Android on macOS or Windows runners works but is slower; avoid unless you must.
  • Self-hosted runners with real devices attached give control at the price of maintenance.

An Android workflow

YAML
name: android-ui-tests
on:
  pull_request:
  schedule:
    - cron: "0 3 * * *"

jobs:
  android:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with: { distribution: temurin, java-version: 17 }

      - uses: actions/setup-node@v4
        with: { node-version: 22 }

      - name: Build debug APK
        run: ./gradlew assembleDebug

      - name: Install Appium and the driver
        run: |
          npm install -g appium
          appium driver install uiautomator2
          appium driver list --installed

      - name: Enable KVM
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules
          sudo udevadm trigger --name-match=kvm

      - name: Run tests on an emulator
        uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 34
          arch: x86_64
          profile: pixel_6
          disable-animations: true
          script: |
            appium --log-level info > appium.log 2>&1 &
            npx --yes wait-on http://127.0.0.1:4723/status
            pip install -r requirements.txt
            pytest tests --junitxml=report.xml

      - name: Upload evidence
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: android-results
          path: |
            report.xml
            appium.log
            artifacts/

Points worth noticing:

  • timeout-minutes stops a hung emulator from burning an hour of runner time.
  • The Appium server is started in the background (&), and wait-on polls its /status endpoint until it answers. Never start tests after a fixed sleep.
  • disable-animations: true removes a whole class of timing flakes.
  • if: always() uploads logs and screenshots even when tests fail, which is exactly when you need them.
  • Pin versions (appium@3, Node, API level) so a new release does not break the pipeline overnight; upgrade deliberately.

An iOS job

YAML
  ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - name: Build for simulator
        run: xcodebuild -scheme Shop -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath build
      - name: Boot a simulator
        run: |
          xcrun simctl boot "iPhone 16" || true
          xcrun simctl bootstatus "iPhone 16" -b
      - name: Appium and tests
        run: |
          npm install -g appium
          appium driver install xcuitest
          appium > appium.log 2>&1 &
          npx --yes wait-on http://127.0.0.1:4723/status
          pytest tests --platform ios --junitxml=report.xml

simctl bootstatus -b blocks until the simulator has finished booting, which is the iOS counterpart of waiting for an Android emulator to report sys.boot_completed.

Cloud devices in CI

When tests run on a cloud farm, the job needs no emulator or Appium install. It uploads the app, exports the hub URL and credentials from the CI secret store, and runs the tests (see Connecting to a Cloud Grid). This also works on cheap Linux runners for iOS tests.

Stand-in: wait for the server to be ready

This runnable example simulates the readiness loop (wait-on) against a fake server that becomes ready after a few polls.

Python Waiting for the Appium server (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Reading the Appium log in CI

When a CI run fails, the Appium log tells the story. Every command appears with its HTTP verb and result. This stand-in extracts the failures from a sample log:

Python Finding errors in an Appium log (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A 404 on /element taking 31 seconds means a wait or implicit timeout elapsed before the element was reported missing, a clue to look at your waits (see Waits and Synchronization).

Keeping CI fast and stable

  • Cache Gradle, npm and Python packages between runs.
  • Run a smoke set per pull request, the full suite nightly.
  • Shard the suite across jobs with a matrix (see Parallel Runs and the Device Matrix).
  • Fail on infrastructure errors early: a job where the emulator never boots should stop in two minutes, not forty.
  • Keep secrets out of logs: mask them, and never print capabilities containing keys.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why poll the Appium /status endpoint instead of sleeping?

    A readiness check is both faster and more reliable than a fixed delay.
  2. 2. Which runner type is required for iOS simulator tests?

    iOS simulators and Xcode need macOS.
  3. 3. What does if: always() on the upload step ensure?

    Failure evidence is the most valuable evidence.
  4. 4. Why pin Appium, Node and API level versions in CI?

    Floating versions can break the pipeline without any change in your code.

Summary

  • A mobile CI pipeline builds the app, installs Appium and drivers, boots a device, waits for readiness, runs tests and uploads evidence.
  • Android emulators run well on Linux with KVM; iOS simulators need macOS runners.
  • Start the server in the background and poll /status; disable animations and set job timeouts.
  • Upload logs, videos and reports with always(); pin tool versions.
  • Cloud farms remove the emulator and Appium setup from the job.

Next: Flaky Tests, Retries and Quarantine