Documentation structure for LLMs (llms.txt)
CircleCI Logo

Android images with the machine executor

5 days ago
Cloud Server v4+

Overview

You access the Android machine image through the Linux Machine Executor, like other Linux machine images on CircleCI. The Android machine image supports nested virtualization and x86 Android emulators, so you can use it for Android UI testing. It also comes with the Android SDK pre-installed.

Using the Android machine image

You can configure the Android image in your configuration using Orbs, or manually. The Android orb simplifies your configuration. More complex and custom configurations may work better with manual configuration instead of the orb. This document covers both use cases. Refer to the Examples section below for more details.

Available resource classes

Gen1

Class vCPUs RAM Disk Size Cloud Server

medium

2

7.5 GB

150GB

Yes

Yes

large

4

15 GB

150GB

Yes

Yes

xlarge

8

32 GB

150GB

Yes

Yes

2xlarge

16

64 GB

150GB

Yes

Yes

2xlarge+

32

64 GB

150GB

Yes

Yes

Gen2

Class vCPUs RAM Disk Size Cloud Server

medium.gen2

2

8 GiB

150GB

Yes

No

large.gen2

4

16 GiB

150GB

Yes

No

xlarge.gen2

8

32 GiB

150GB

Yes

No

2xlarge.gen2

16

64 GiB

150GB

Yes

No

2xlarge+.gen2

32

128 GiB

150GB

Yes

No

View resource usage

To view the compute resource usage for the duration of a job in the CircleCI web app:

  1. In the CircleCI web app, select your org from the org cards on your user homepage.

  2. Select Pipelines from the sidebar and locate your pipeline from the list. You can use the project, branch, date, and status search options to help.

  3. Select the job you want to access by selecting the job name.

  4. Select the Resources tab to view CPU and RAM usage for the duration of the job.

You can use these insights to decide whether to make changes to the job’s configured resource class.

Resources tab
Figure 1. Resources tab in web app for a job

Android machine image generations

Gen2

Resource classes running on gen2 infrastructure offer significant performance and cost improvements over their gen1 equivalents.

Performance improvements

Using more modern compute, gen2 instances deliver up to 47% faster performance compared to gen1 equivalents.

On a per-resource-class basis, gen2 pricing can be higher or lower than its gen1 equivalent. See our Pricing Page for details.

Using gen2

All Android gen1 resource classes are also available as gen2. Gen2 images use the current tag instead of the default tag used by gen1, to stay consistent with the Linux VM tagging convention. To use a gen2 resource class, specify the current tag along with a large.gen2 or equivalent resource class in your job configuration:

version: 2.1
jobs:
  build:
    machine:
      image: android:current
    resource_class: large.gen2
    steps:
      # ... steps for your job
Gen2 resource classes for the Android machine image are available on CircleCI Cloud only.

Pre-installed software

View the latest update announcement on our Discuss page for a list of current pre-installed software.

Examples

The following examples show how to use the Android machine image, both with and without orbs.

Simple orb usage

The below sample uses the Android orb to run a single job.

Make sure to replace any placeholder versions in the example. 
# .circleci/config.yaml
version: 2.1
orbs:
  android: circleci/android@3.1.0
  # https://circleci.com/developer/orbs/orb/circleci/android for latest version
workflows:
  test:
    jobs:
      # This job uses the Android machine image by default
      - android/run-ui-tests:
          # Use pre-steps and post-steps if necessary
          # to execute custom steps before and after any of the built-in steps
          system-image: system-images;android-29;default;x86
          executor:
            name: android/android_machine
            resource-class: large
            tag: default

More complex orb usage

This example shows how you can use more granular orb commands to achieve what the start-emulator-and-run-tests command does.

Make sure to replace any placeholder versions in the example. 
# .circleci/config.yml
version: 2.1
orbs:
  android: circleci/android@3.1.0
  # https://circleci.com/developer/orbs/orb/circleci/android for latest version
jobs:
  test:
    executor:
      name: android/android_machine
      resource-class: large
      tag: default
    steps:
      - checkout
      # Create an AVD named "myavd"
      - android/create-avd:
          avd-name: myavd
          system-image: system-images;android-29;default;x86
          install: true
      # By default, after starting up the emulator, a cache will be restored,
      # "./gradlew assembleDebugAndroidTest" will be run and then a script
      # will be run to wait for the emulator to start up.
      # Specify the "post-emulator-launch-assemble-command" command to override
      # the gradle command run, or set "wait-for-emulator" to false to disable
      # waiting for the emulator altogether.
      - android/start-emulator:
          avd-name: myavd
          no-window: true
          restore-gradle-cache-prefix: v1a
      # Runs "./gradlew connectedDebugAndroidTest" by default.
      # Specify the "test-command" parameter to customize the command run.
      - android/run-tests
      - android/save-gradle-cache:
          cache-prefix: v1a
workflows:
  test:
    jobs:
      - test

No-orb example

The following example uses the Android machine image without the circleci/android orb. These steps match what runs when you use the run-ui-tests job of the orb.

# .circleci/config.yml
version: 2.1
jobs:
  build:
    machine:
      image: android:default
    # To optimize build times, we recommend "large" and above for Android-related jobs
    resource_class: large
    steps:
      - checkout
      - run:
          name: Create avd
          command: |
            SYSTEM_IMAGES="system-images;android-29;default;x86"
            sdkmanager "$SYSTEM_IMAGES"
            echo "no" | avdmanager --verbose create avd -n test -k "$SYSTEM_IMAGES"
      - run:
          name: Launch emulator
          command: |
            emulator -avd test -delay-adb -verbose -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim
          background: true
      - run:
          name: Generate cache key
          command: |
            find . -name 'build.gradle' | sort | xargs cat |
            shasum | awk '{print $1}' > /tmp/gradle_cache_seed
      - restore_cache:
          key: gradle-v1-{{ arch }}-{{ checksum "/tmp/gradle_cache_seed" }}
      - run:
          # run in parallel with the emulator starting up, to optimize build time
          name: Run assembleDebugAndroidTest task
          command: |
            export TERM=dumb
            ./gradlew assembleDebugAndroidTest
      - run:
          name: Wait for emulator to start
          command: |
            circle-android wait-for-boot
      - run:
          name: Disable emulator animations
          command: |
            adb shell settings put global window_animation_scale 0.0
            adb shell settings put global transition_animation_scale 0.0
            adb shell settings put global animator_duration_scale 0.0
      - run:
          name: Run UI tests (with retry)
          command: |
            MAX_TRIES=2
            run_with_retry() {
               n=1
               until [ $n -gt $MAX_TRIES ]
               do
                  echo "Starting test attempt $n"
                  ./gradlew connectedDebugAndroidTest && break
                  n=$[$n+1]
                  sleep 5
               done
               if [ $n -gt $MAX_TRIES ]; then
                 echo "Max tries reached ($MAX_TRIES)"
                 exit 1
               fi
            }
            run_with_retry
      - save_cache:
          key: gradle-v1-{{ arch }}-{{ checksum "/tmp/gradle_cache_seed" }}
          paths:
            - ~/.gradle/caches
            - ~/.gradle/wrapper
workflows:
  build:
    jobs:
      - build

Using the Android image on server

Android machine images are only available on server installations on Google Cloud Platform (GCP).

CircleCI Server 3.4+ supports Android machine images for installations on GCP. To use the Android image in your projects, set the image key to android-default in your jobs.

version: 2.1

jobs:
  my-job:
    machine:
      image: android-default
    steps:
    # job steps here

You can also use the Android orb, as shown above, for cloud. Your server administrator needs to import the orb first. You also need to define the android-default image for the machine executor, as shown in the example below, rather than using the default executor built into the orb. View the CircleCI Server Orbs page for instructions on importing orbs.

This example shows how you can use granular orb commands to achieve what the start-emulator-and-run-tests command does.

Make sure to replace any placeholder versions in the example. 
# .circleci/config.yml
version: 2.1
orbs:
  android: circleci/android@x.y.z
  # https://circleci.com/developer/orbs/orb/circleci/android for latest version
jobs:
  test:
    machine:
      image: android-default
    steps:
      - checkout
      # Create an AVD named "myavd"
      - android/create-avd:
          avd-name: myavd
          system-image: system-images;android-29;default;x86
          install: true
      # By default, after starting up the emulator, a cache will be restored,
      # "./gradlew assembleDebugAndroidTest" will be run and then a script
      # will be run to wait for the emulator to start up.
      # Specify the "post-emulator-launch-assemble-command" command to override
      # the gradle command run, or set "wait-for-emulator" to false to disable
      # waiting for the emulator altogether.
      - android/start-emulator:
          avd-name: myavd
          no-window: true
          restore-gradle-cache-prefix: v1a
      # Runs "./gradlew connectedDebugAndroidTest" by default.
      # Specify the "test-command" parameter to customize the command run.
      - android/run-tests
      - android/save-gradle-cache:
          cache-prefix: v1a
workflows:
  test:
    jobs:
      - test