> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/android

Orb for working with Android projects on CircleCI.
Supports running Android emulator UI tests.


## Commands

### accept_licenses

Accept all Android SDK Manager licenses


### change_java_version

Change default java version from OpenJDK v17.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `distribution` | enum | openjdk | The distribution of JDK to change to
 |
| `java_version` | integer | 8 | The version of JDK to change to
 |

### change_malloc

Change default malloc from glibc malloc to jemalloc


| Parameter | Type | Default | Description |
|---|---|---|---|
| `implementation` | enum | jemalloc |  |

### create_avd

Create an AVD.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional args to be passed directly to the avd creation command
You can pass environment variables, using the $ syntax e.g. "$ADDITIONAL_ARGS"
 |
| `avd_name` | string |  | The name of the AVD to create.
You can pass environment variables, using the $ syntax e.g. "$AVD_NAME"
 |
| `background` | boolean | false | Whether to run the creation command in background
 |
| `install` | boolean |  | Whether to first install the system image via sdkmanager
 |
| `system_image` | string |  | Name of system image e.g. "system-images;android-29;default;x86".
It should match the name seen in the "sdkmanager --list" output.
You can pass environment variables, using the $ syntax e.g. "$SYSTEM_IMAGE"
 |

### create_google_play_key

Generate JSON file for your google play key. For use with environment variables.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `google_play_key` | env_var_name | GOOGLE_PLAY_KEY | Your google play key |
| `working_directory` | string | . | Working directory to create google play key in |

### create_keystore_properties

Creates a keystore.properties file for use in deployment steps. For use with environment variables.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `release_key_alias` | env_var_name | RELEASE_KEY_ALIAS | Release key alias |
| `release_key_password` | env_var_name | RELEASE_KEY_PASSWORD | Password for your release key |
| `release_keystore` | string | ./keystore | Points to the location of your decrypted keystore |
| `release_store_password` | env_var_name | RELEASE_STORE_PASSWORD | Password for your keystore |
| `working_directory` | string | . | Working directory to create keystore.properties in |

### decode_keystore

Decodes a keystore that was encrypted in base64. For use with environment variables.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base64_keystore` | env_var_name | BASE64_KEYSTORE | Your base64 keystore |
| `keystore_location` | string | . | The location of your decrypted keystore |

### disable_animations

Disables animations. Requires an emulator to be running.


### fastlane_deploy

Runs fastlane lanes to deploy to Google Play Store


| Parameter | Type | Default | Description |
|---|---|---|---|
| `lane_name` | string | deploy | The name of the lane fastlane will execute |
| `working_directory` | string | . | Working directory to run fastlane commands in |

### install_ndk

Install an Android NDK version using 'sdkmanager'. This command takes one
parameter called 'ndk', which is the NDK version. If the version is already
available, the step will still complete successfully.

This command is designed to be used with the CircleCI Android Docker or
machine images.

Available NDK versions can be found here:
https://github.com/android/compose-samples


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | Version of the NDK to install. Available NDK versions can be found here:
https://github.com/android/compose-samples
 |

### kill_emulators

Terminates any running emulator processes


### restore_build_cache

Restore the build cache. See `save_build_cache` for more information.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache_prefix` | string | v1 | Used to form part of the cache key |

### restore_gradle_cache

Restore gradle cache


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache_prefix` | string | v1 | Used to form part of the cache key |
| `find_args` | string | . -name "build.gradle*" -o -name "settings.gradle*" | Use this to customize how the find command is used to look for relevant
file changes.
 |

### run_tests

Runs tests, with retries supported


| Parameter | Type | Default | Description |
|---|---|---|---|
| `max_tries` | integer | 2 | Max number of tries. To disable retries, set this to 1. |
| `no_output_timeout` | string | 10m | Use this to configure the no_output_timeout value |
| `pre_test_command` | string |   | Command to run prior to runnning the test command
You can pass environment variables, using the $ syntax e.g. "$PRE_TEST_COMMAND"
 |
| `pull_data` | boolean | false | Whether to pull data after running tests
 |
| `pull_data_path` | string | data | Emulator directory to pull data from
 |
| `pull_data_target` | string | . | Location to save pulled data
 |
| `retry_interval` | integer | 5 | Duration in seconds to wait before the next try |
| `test_command` | string | ./gradlew connectedDebugAndroidTest | Command to run in order to run the tests
You can pass environment variables, using the $ syntax e.g. "$TEST_COMMAND"
 |
| `working_directory` | string | . | Working directory to run the tests in |

### save_build_cache

Save the Android build-cache. The build cache stores certain outputs that the Android plugin for Gradle generates when building your project (such as unpackaged AARs and pre-dexed remote dependencies). Your clean builds are much faster while using the cache because the build system can simply reuse those cached files during subsequent builds, instead of recreating them. The build cache also works on continuous integration servers and when running multiple build processes on a single local machine.
See https://developer.android.com/studio/build/build-cache


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache_prefix` | string | v1 | Used to form part of the cache key |

### save_gradle_cache

Save gradle cache


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache_prefix` | string | v1 | Used to form part of the cache key |

### start_emulator

Start an emulator as a background process.
The AVD used should already be created. (See "create_avd" command for how
one could be created)


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional args to be passed directly to the emulator command
 |
| `avd_name` | string |  | The name of the existing AVD to use for the emulator
 |
| `camera_back` | string |  | The value to use for the "-camera-back" flag.
If set to "", the emulator will be run without the -camera-back flag.
 |
| `camera_front` | string |  | The value to use for the "-camera-front" flag.
If set to "", the emulator will be run without the -camera-front flag.
 |
| `delay_adb` | boolean | false | Whether to run the emulator with the -delay-adb flag
 |
| `disable_animations` | boolean | true | Whether to disable animations that may interfere with tests, after the emulator starts up
 |
| `gpu` | string | swiftshader_indirect | The value to use for the "-gpu" flag.
If set to "", the emulator will be run without the -gpu flag.
 |
| `memory` | integer | -1 | The value to use for the "-memory" flag.
If set to -1, the emulator will be run without the -memory flag.
 |
| `no_audio` | boolean | true | Whether to run the emulator with the -noaudio flag
 |
| `no_boot_anim` | boolean | true | Whether to run the emulator with the -no-boot-anim flag
 |
| `no_snapshot` | boolean | true | Whether to run the emulator with the -no-snapshot flag
 |
| `no_window` | boolean | true | Whether to run the emulator with the -no-window flag
 |
| `override_args` | string |  | If this is set to a non-blank value, the emulator command will be
run with the -avd flag and the value of "override_args" (i.e. none of the defaults
provided by the orb command will be used)
 |
| `post_emulator_launch_assemble_command` | string | ./gradlew assembleDebugAndroidTest | If this is set to a non-blank value, the configured command will be run
after the emulator has been launched, and before commencing the
wait for the emulator to finish starting up.
 |
| `post_emulator_wait_steps` | steps |  | Steps to execute after waiting for the emulator to start up
 |
| `pre_emulator_wait_steps` | steps |  | Steps to execute while before beginning to wait for the emulator to start up
 |
| `restore_gradle_cache_find_args` | string | . -name "build.gradle*" -o -name "settings.gradle*" | Use this to customize how the find command is used to look for relevant
file changes.
 |
| `restore_gradle_cache_post_emulator_launch` | boolean | true | Whether to restore the gradle cache after the emulator has been launched,
and before commencing the wait for the emulator to finish starting up.
 |
| `restore_gradle_cache_prefix` | string | v1 | Cache prefix used if the "restore_gradle_cache_post_emulator_launch" parameter
is set to true.
 |
| `run_logcat` | boolean | false | Whether to run with logcat in the background, after the emulator starts up
 |
| `verbose` | boolean | true | Whether to run the emulator with the -verbose flag
 |
| `wait_for_emulator` | boolean | true | Whether to wait for the emulator to start up
 |

### start_emulator_and_run_tests

Creates an AVD, starts an emulator and runs tests.
This is a wrapper command that wraps the
create_avd, start_emulator and run_tests commands.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_avd_args` | string |  | Additional args to be passed directly to the avd creation command.
You can pass environment variables, using the $ syntax e.g. "$ADDITIONAL_ARGS"
 |
| `additional_emulator_args` | string |  | Additional args to be passed directly to the emulator command
 |
| `avd_name` | string | test | The name of the AVD to create.
You can pass environment variables, using the $ syntax e.g. "$AVD_NAME"
 |
| `camera_back` | string |  | The value to use for the "-camera-back" flag.
If set to "", the emulator will be run without the -camera-back flag.
 |
| `camera_front` | string |  | The value to use for the "-camera-front" flag.
If set to "", the emulator will be run without the -camera-front flag.
 |
| `delay_adb` | boolean | false | Whether to run the emulator with the -delay-adb flag
 |
| `disable_animations` | boolean | true | Whether to disable animations that may interfere with tests, after the emulator starts up
 |
| `gpu` | string | swiftshader_indirect | The value to use for the "-gpu" flag.
If set to "", the emulator will be run without the -gpu flag.
 |
| `install_system_image` | boolean | true | Whether to first install the system image via sdkmanager
 |
| `kill_emulators` | boolean | true | Whether to kill the emulators after the tests complete
 |
| `max_tries` | integer | 2 | Max number of tries. To disable retries, set this to 1. |
| `memory` | integer | -1 | The value to use for the "-memory" flag.
If set to -1, the emulator will be run without the -memory flag.
 |
| `no_audio` | boolean | true | Whether to run the emulator with the -noaudio flag
 |
| `no_boot_anim` | boolean | true | Whether to run the emulator with the -no-boot-anim flag
 |
| `no_output_timeout` | string | 10m | Use this to configure the no_output_timeout value of the test run
 |
| `no_snapshot` | boolean | true | Whether to run the emulator with the -no-snapshot flag
 |
| `no_window` | boolean | true | Whether to run the emulator with the -no-window flag
 |
| `override_emulator_args` | string |  | If this is set to a non-blank value, the emulator command will be
run with the -avd flag and the value of "override_args" (i.e. none of the defaults
provided by the orb command will be used)
 |
| `post_emulator_launch_assemble_command` | string | ./gradlew assembleDebugAndroidTest | If this is set to a non-blank value, the configured command will be run
after the emulator has been launched, and before commencing the
wait for the emulator to finish starting up.
 |
| `post_emulator_wait_steps` | steps |  | Steps to execute after waiting for the emulator to start up
 |
| `post_run_tests_steps` | steps |  | Steps to run after the tests
 |
| `pre_emulator_wait_steps` | steps |  | Steps to execute while before beginning to wait for the emulator to start up
 |
| `pre_run_tests_steps` | steps |  | Steps to run before the tests
 |
| `pre_test_command` | string |   | Command to run prior to runnning the test command
You can pass environment variables, using the $ syntax e.g. "$PRE_TEST_COMMAND"
 |
| `pull_data` | boolean | false | Whether to pull data after running tests
 |
| `pull_data_path` | string | data | Emulator directory to pull data from
 |
| `pull_data_target` | string | . | Location to save pulled data
 |
| `restore_gradle_cache_find_args` | string | . -name "build.gradle*" -o -name "settings.gradle*" | Use this to customize how the find command is used to look for relevant
file changes.
 |
| `restore_gradle_cache_post_emulator_launch` | boolean | true | Whether to restore the gradle cache after the emulator has been launched,
and before commencing the wait for the emulator to finish starting up.
 |
| `restore_gradle_cache_prefix` | string | v1 | Cache prefix used if the "restore_gradle_cache_post_emulator_launch" parameter
is set to true.
 |
| `retry_interval` | integer | 5 | Duration in seconds to wait before the next try |
| `run_logcat` | boolean | false | Whether to run with logcat in the background, after the emulator starts up
 |
| `run_tests_working_directory` | string | . | Working directory to run the tests in |
| `save_gradle_cache` | boolean | true | Whether to write to the gradle cache after the tests have run
 |
| `system_image` | string | system-images;android-29;default;x86 | Name of system image e.g. "system-images;android-29;default;x86".
It should match the name seen in the "sdkmanager --list" output.
You can pass environment variables, using the $ syntax e.g. "$SYSTEM_IMAGE"
 |
| `test_command` | string | ./gradlew connectedDebugAndroidTest | Command to run in order to run the tests
You can pass environment variables, using the $ syntax e.g. "$TEST_COMMAND"
 |
| `verbose` | boolean | true | Whether to run the emulator with the -verbose flag
 |
| `wait_for_emulator` | boolean | true | Whether to wait for the emulator to start up
 |

### wait_for_emulator

Wait for the emulator to start.
Requires the "circle-android" script to be present in PATH.


## Jobs

### build

Start building an Android project on CircleCI


| Parameter | Type | Default | Description |
|---|---|---|---|
| `executor` | executor |  | Executor for the job |

### deploy_to_play_store

Deploy an android app on CircleCI to the Google Play Store using Fastlane. For use with CirceCI Environment Variables.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base64_keystore` | env_var_name | BASE64_KEYSTORE | Your base64 keystore |
| `checkout` | boolean | true | Whether to run the checkout step |
| `executor` | executor |  | Executor for the job |
| `fastlane_working_directory` | string | . | Working directory to run fastlane commands in |
| `google_play_key` | env_var_name | GOOGLE_PLAY_KEY | Your google play key |
| `keystore_location` | string | . | The location of your decrypted keystore |
| `keystore_properties_working_directory` | string | . | Working directory to create keystore.properties in |
| `lane_name` | string | deploy | The name of the lane fastlane will execute |
| `release_key_alias` | env_var_name | RELEASE_KEY_ALIAS | Release key alias |
| `release_key_password` | env_var_name | RELEASE_KEY_PASSWORD | Password for your release key |
| `release_keystore` | string | ./keystore | Points to the location of your decrypted keystore |
| `release_store_password` | env_var_name | RELEASE_STORE_PASSWORD | Password for your keystore |

### run_ui_tests

Creates an AVD, starts an emulator and runs Android UI tests.
This is a job that wraps the "start_emulator_and_run_tests" command.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_avd_args` | string |  | Additional args to be passed directly to the avd creation command
 |
| `additional_emulator_args` | string |  | Additional args to be passed directly to the emulator command
 |
| `avd_name` | string | test | The name of the AVD to create
 |
| `camera_back` | string |  | The value to use for the "-camera-back" flag.
If set to "", the emulator will be run without the -camera-back flag.
 |
| `camera_front` | string |  | The value to use for the "-camera-front" flag.
If set to "", the emulator will be run without the -camera-front flag.
 |
| `checkout` | boolean | true | Whether to run the checkout step |
| `delay_adb` | boolean | false | Whether to run the emulator with the -delay-adb flag
 |
| `disable_animations` | boolean | true | Whether to disable animations that may interfere with tests, after the emulator starts up
 |
| `executor` | executor |  | Executor for the job |
| `gpu` | string | swiftshader_indirect | The value to use for the "-gpu" flag.
If set to "", the emulator will be run without the -gpu flag.
 |
| `install_system_image` | boolean | true | Whether to first install the system image via sdkmanager
 |
| `kill_emulators` | boolean | true | Whether to kill the emulators after the tests complete
 |
| `max_tries` | integer | 2 | Max number of tries. To disable retries, set this to 1. |
| `memory` | integer | -1 | The value to use for the "-memory" flag.
If set to -1, the emulator will be run without the -memory flag.
 |
| `no_audio` | boolean | true | Whether to run the emulator with the -noaudio flag
 |
| `no_boot_anim` | boolean | true | Whether to run the emulator with the -no-boot-anim flag
 |
| `no_output_timeout` | string | 10m | Use this to configure the no_output_timeout value of the test run
 |
| `no_snapshot` | boolean | true | Whether to run the emulator with the -no-snapshot flag
 |
| `no_window` | boolean | true | Whether to run the emulator with the -no-window flag
 |
| `override_emulator_args` | string |  | If this is set to a non-blank value, the emulator command will be
run with the -avd flag and the value of "override_args" (i.e. none of the defaults
provided by the orb command will be used)
 |
| `post_emulator_launch_assemble_command` | string | ./gradlew assembleDebugAndroidTest | If this is set to a non-blank value, the configured command will be run
after the emulator has been launched, and before commencing the
wait for the emulator to finish starting up.
 |
| `post_emulator_wait_steps` | steps |  | Steps to execute after waiting for the emulator to start up
 |
| `post_run_tests_steps` | steps |  | Steps to run after the tests
 |
| `pre_emulator_wait_steps` | steps |  | Steps to execute while before beginning to wait for the emulator to start up
 |
| `pre_run_tests_steps` | steps |  | Steps to run before the tests
 |
| `pre_test_command` | string |   | Command to run prior to runnning the test command |
| `pull_data` | boolean | false | Whether to pull data after running tests
 |
| `pull_data_path` | string | data | Emulator directory to pull data from
 |
| `pull_data_target` | string | . | Location to save pulled data
 |
| `restore_gradle_cache_find_args` | string | . -name "build.gradle*" -o -name "settings.gradle*" | Use this to customize how the find command is used to look for relevant
file changes.
 |
| `restore_gradle_cache_post_emulator_launch` | boolean | true | Whether to restore the gradle cache after the emulator has been launched,
and before commencing the wait for the emulator to finish starting up.
 |
| `restore_gradle_cache_prefix` | string | v1 | Cache prefix used if the "restore_gradle_cache_post_emulator_launch" parameter
is set to true.
 |
| `retry_interval` | integer | 5 | Duration in seconds to wait before the next try |
| `run_logcat` | boolean | false | Whether to run with logcat in the background, after the emulator starts up
 |
| `run_tests_working_directory` | string | . | Working directory to run the tests in |
| `save_gradle_cache` | boolean | true | Whether to write to the gradle cache after the tests have run
 |
| `system_image` | string | system-images;android-29;default;x86 | Name of system image e.g. "system-images;android-29;default;x86".
It should match the name seen in the "sdkmanager --list" output.
 |
| `test_command` | string | ./gradlew connectedDebugAndroidTest | Command to run in order to run the tests |
| `verbose` | boolean | true | Whether to run the emulator with the -verbose flag
 |
| `wait_for_emulator` | boolean | true | Whether to wait for the emulator to start up
 |

## Executors

### android_docker

Select a CircleCI convenience image to get building on Android.
See https://circleci.com/developer/images/image/cimg/android#image-tags for a full list of
the available images.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | medium | Resource class used for the executor. |
| `tag` | string |  | The Android image tag to use.
Choose a tag from https://circleci.com/developer/images/image/cimg/android#image-tags.
 |

### android_machine

This selects an Android machine image.
CircleCI's Android machine images are recommended for Android emulator tests.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | large | Resource class used for the executor. It is recommended
to use large and above to avoid memory issues such as process
crashes when running emulator tests.
 |
| `tag` | string |  | Name of CircleCI Android machine image to use.
Android machine tags can be found at https://circleci.com/developer/machine/image/android#image-tags
 |

## Examples

### granular_commands

An example of using the more granular commands of the orb together,
to achieve something similar to using the "start_emulator_and_run_tests" command
or the "run_ui_tests" job.


```yaml
version: '2.1'
orbs:
  android: circleci/android@3.0.0
jobs:
  test:
    executor:
      name: android/android_machine
      resource_class: large
      tag: default
    steps:
      - checkout
      - android/create_avd:
          avd_name: myavd
          install: true
          system_image: system-images;android-31;default;x86_64
      - android/start_emulator:
          avd_name: myavd
          no_window: true
          restore_gradle_cache_prefix: v1a
      - android/run_tests
      - android/save_gradle_cache:
          cache_prefix: v1a
workflows:
  test:
    jobs:
      - test
```

### override_machine_resource_class

An example of overriding the android_machine executor's default resource class


```yaml
version: '2.1'
orbs:
  android: circleci/android@3.0.0
workflows:
  test:
    jobs:
      - android/run_ui_tests:
          executor:
            name: android/android_machine
            resource_class: xlarge
            tag: default
```

### run_ui_tests_job

A simple example of using the run_ui_tests job,
using most of the default parameters.
Parameters like the system_image and emulator options (e.g. "no_window")
may need to be adjusted from the defaults, according to your project.


```yaml
version: '2.1'
orbs:
  android: circleci/android@3.0.0
workflows:
  test:
    jobs:
      - android/run_ui_tests:
          executor:
            name: android/android_machine
            resource-class: large
            tag: 2024.01.1
          system_image: system-images;android-31;default;x86_64
```

### start_emulator_and_run_tests

A simple example of using the start_emulator_and_run_tests command
in a job, using most of the default parameters.
Parameters like the system_image and emulator options (e.g. "no_window")
may need to be adjusted from the defaults, according to your project.


```yaml
version: '2.1'
orbs:
  android: circleci/android@3.0.0
jobs:
  test:
    executor:
      name: android/android_machine
      resource_class: large
      tag: default
    steps:
      - checkout
      - android/start_emulator_and_run_tests:
          system_image: system-images;android-31;default;x86_64
workflows:
  test:
    jobs:
      - test
```

### test_matrix

A simple example of using a test matrix to test on different
emulators.


```yaml
version: '2.1'
orbs:
  android: circleci/android@3.0.0
workflows:
  test:
    jobs:
      - android/run_ui_tests:
          matrix:
            parameters:
              system_image:
                - system-images;android-31;default;x86_64
                - system-images;android-31;default;x86_64
          name: ui-tests-<<matrix.system_image>>
```