Set up CTS automated testing

Before you can execute automated CTS tests, prepare your physical environment, set up your workstation, and configure the device you're testing.

Set up physical environment

Certain CTS tests require the use of external devices to be set up near the DUT. To set up your physical environment:

(optional) If your DUT supports Bluetooth LE, place at least three Bluetooth LE beacons within 5 meters of the DUT for Bluetooth LE scan testing. Additionally:
- The beacons don't need to be configured or emit anything specific.
- The beacons can be any kind, including iBeacon, Eddystone, or even devices simulating BLE beacons.
Place the phone in front of a scene, such as a wall or the ceiling, at a distance equivalent to the DUT's minimum focus distance. Additionally:
- The scene must have sufficient lighting to allow the sensors under test to reach and remain at the maximum configured target frames per second (FPS) as specified in CONTROL_AE_TARGET_FPS_RANGE.
- This set up applies to all camera sensors reported by getCameraIdList as the test iterates over the listed devices and measures performance individually.
- If the DUT supports external cameras, such as USB webcams, plug in an external camera when running CTS. Otherwise, the CTS tests fail.
(optional) If your DUT supports a global positioning system (GPS) or other global navigation satellite system (GNSS), provide a GNSS signal to the DUT at a suitable signal level for reception and location calculation. Additionally:
- The GPS must be compliant with ICD-GPS-200C.
- The GNSS signal can be of any type, including a satellite simulator or a repeater of outdoor signals.
- You can place the DUT close to a window so that it can directly receive enough GNSS signal from a satellite.
Caution: For the GPS testing, the internet connection setup must not block connections to supl.google.com port 7276. This port downloads GPS assistance data for testing position calculation on the local device.
Ensure your Wi-Fi network supports IPv4 and IPv6, has an internet connection with DNS for IPv4 and IPv6, supports IP multicast, and can treat the DUT as an isolated client.

Note: An isolated client is a configuration where the DUT doesn't have visibility to the broadcast or multinetwork messages on that subnetwork. To set up an isolated client, use a Wi-Fi access point (AP) configuration or run the DUT on an isolated subnetwork without other devices being connected.

If you don't have access to a native IPv6 network, an IPv6 carrier network, or a VPN to pass IPv6 tests, use a Wi-Fi AP and an IPv6 tunnel.
Ensure the DUT has the UP, BROADCAST, and MULTICAST flags set on the Wi-Fi interface.
Ensure the Wi-Fi interface has IPv4 and IPv6 addresses assigned. To check the Wi-Fi interface properties, run adb shell ifconfig.
(optional) If your DUT supports Wi-Fi STA or STA concurrency, set up at least two Wi-Fi networks. These Wi-Fi networks must run on different bands with different SSIDs or on the same SSID with different BSSIDs.
(optional) If your DUT supports Wi-Fi round trip time (RTT), set up a device that supports Wi-Fi RTT:
1. Place the Wi-Fi RTT device within 40 feet of the DUT.
2. Power up the Wi-Fi RTT device.
Here are two recommended devices supporting Wi-Fi RTT: - Google Wifi - Compulab's fitlet2 access point (set to 40 MHz bandwidth at 5 GHz).

Set up your desktop machine

Before running the CTS automated tests, ensure that your desktop machine meets hardware and operating system requirements and has the proper software installed, as described in the following sections.

Meet hardware requirements

Your CTS desktop machine should meet or exceed these hardware requirements:

A 64-bit x86 system
At least 256 GB of free disk space to accommodate the increased number of CTS test cases and an increase in Java heap space reservation in Tradefed
A minimum of 32 GB of RAM

Meet operating system requirements

Your development machine must run a 64-bit Linux distribution with GNU C Library (glibc) 2.17 or higher.

Install desktop software

To install the proper desktop software for CTS:

Install the FFmpeg package version 5.1.3 or higher.
Install the most recent versions of Android Debug Bridge (adb) and Android Asset Packaging Tool (AAPT2) and add the location of those tools to the system path of your machine:
1. Follow the instructions at the start of the SDK Manager documentation to install the sdkmanager command-line tool. The link to download the command-line tools is in the Command line tools only section at the bottom of the Android Studio download page.
2. Update your system path to include the location of the newly installed sdkmanager.
3. Using sdkmanager, install the latest platform-tools and build-tools packages. These packages contain adb and AAPT2. For information on installing packages, see Install packages.
4. Update your path to include the location of the newly installed adb and AAPT2 tools.
5. Verify that adb and AAPT2 are in your path.
Note: Alternatively, if you're using Android Studio on your CTS desktop machine, you can check the Android SDK Platform-Tools and Android SDK Build-Tools options to install the platform and SDK build tools.
Install the proper version of Java Development Kit (JDK):
- For Android 11 or higher, install JDK 11.
- For Android 10 or lower, see Set up CTS (AOSP 10 or lower).
(optional) For Android 13 or higher, install virtualenv. The virtualenv tool is required for multidevice tests.
To ensure Python is installed, type python3. The Python version and date should appear indicating python is properly installed.
Download and open the CTS packages from Compatibility Test Suite downloads that match your devices' Android version and all the application binary interfaces (ABIs) that your devices support.
Download and open the latest version of the CTS media files. The media files include video clips from Big Buck Bunny, which are copyrighted by the Blender Foundation under the Creative Commons Attribution 3.0 license.
(optional) When you run CTS for first time, it dynamically downloads some Mainline-related CTS files. Depending on your network speed, this download adds 10 minutes or more to the CTS run time.

To avoid this added CTS run time, you can download the Mainline-related CTS files before running CTS. For information on downloading the Mainline-related CTS files, see Download Mainline-related CTS files.

Prepare the DUT

After setting up your desktop machine, you must set up and configure the DUT.

Set up the DUT

To set up the DUT:

Ensure the DUT is running a system image based on the known to be compatible user build (Android 4.0 or higher) from Codenames, Tags, and Build Numbers and uses the user build variant. For more on build variants, see Choose a target.
If the DUT is running Android 13 or higher, ensure the build has ro.product.first_api_level set to the API level that the device was commercially launched with. To set this value, make the following change to the device.mk file:
```
PRODUCT_SHIPPING_API_LEVEL := 21
```
Certain CTS requirements depend on the build that a device was originally shipped with. For example, devices that originally ship with earlier builds might be excluded from system requirements that apply to devices that ship with later builds. For valid API level values, see Codenames, Tags, and Build Numbers. For more information on ro.product.first_api_level, see Vendor API level.

For Android 10 or lower, see Set up CTS (AOSP 10 or lower).
If your device supports APEX package management:
1. Download the APEX shim package for your specific Android version and hardware architecture. The left two columns in shim packages table provide links to the package to download.
2. Copy the downloaded package to /system/apex.
3. Rename the file to com.android.apex.cts.shim.apex.
If your device doesn't support APEX package management:
1. Download the APEX shim packages for your specific Android version and hardware architecture. The right two columns in the shim packages table provide links to the packages to download.
2. Copy the CtsShim.apk to /system/app/
3. Rename the CtsShim.apk to CtsShimPrebuilt.apk
4. Copy the CtsShimPriv.apk to /system/priv-app/
5. Rename the CtsShimPriv.apk to CtsShimPrivPrebuilt.apk
If your device reports more than one secure element:
1. Download google-cardlet.cap.
2. Copy the downloaded file to /data/uicc/cardlets/.
If your device reports more than one secure element, install the sample applet into the embedded Secure Element (eSE) of the DUT or into the SIM card used by the DUT. For more information, see CTS test for Secure Element.
If your device doesn't have an embedded screen, connect a screen to the device.
If the device has a memory card slot, plug in an empty SD card. Use an SD card that supports an ultra high speed (UHS) bus with SDHC or SDXC capacity or a card with speed class 10 or better to ensure that it can pass the CTS.

Warning: CTS might modify or erase data on the SD card plugged into the device.
If the device has SIM card slots, plug an activated SIM card into each slot. If the device supports SMS, each SIM card must have its own number field populated. For devices running Android 12 or higher, all SIM cards must have support for storing abbreviated dialing numbers (ADN). GSM and USIM cards with the telecom dedicated file (DF_Telecom) satisfy this requirement.

Warning: CTS might modify or erase data on the SIM cards plugged into the device.
Ensure your device has a SIM with CTS carrier privileges meeting the requirements specified in Prepare the UICC.

Configure the DUT

Use the following steps to configure your DUT for use with CTS.

On the DUT:

Factory data reset the device.

Warning: This reset erases all user data from the device.
Set the device's language to English (United States).
If the device supports customizing default fonts, ensure the default sans-serif font family is set to Roboto.
If there's a GPS or a Wi-Fi or mobile network feature on the device, enable the location setting.
Connect to a Wi-Fi network that supports IPv6, can treat the DUT as an isolated client, and has an internet connection. For an explanation of isolated clients, see Set up physical environment.
Ensure there isn't a lock pattern or password set.
Enable USB debugging:
1. Navigate to Settings > About phone and tap Build number seven times. The Developer options appears within the System settings category.
2. Tap USB debugging.
To enable USB debugging on Android 10 or lower, see Set up CTS (AOSP 10 or lower).
Set the time to the 12-hour format.
Enable Developer options > Stay awake.
Disable USB app verification:
1. Navigate to Developer options.
2. Tap Verify apps over USB.
In Android 13 or higher, enable mock modem:
1. Navigate to Developer options.
2. Tap Allow Mock Modem.
This setting is required for specific telephony tests.

On the desktop machine:

Launch the browser and dismiss any startup or setup screen.
Connect the DUT to the desktop machine using a USB cable.
If the system prompts you to accept an RSA key allowing debugging through this computer, click Allow USB debugging.
Set Roboto2 as the sans-serif font using a user accessible affordance (not hidden) setting.
Copy the CTS media files to the DUT:
1. Navigate (cd) to the path where the media files are downloaded and unzipped.
2. Change the file permissions:
```
chmod u+x copy_media.sh
```
3. Copy the files:
  - To copy clips up to a resolution of 720x480, run:
```
./copy_media.sh 720x480
```
  - If you aren't sure of the maximum resolution, copy all of the files:
```
./copy_media.sh all
```
  - If there are multiple DUTs, add the serial option (-s) of a specific device to the end. For example, to copy up to 720x480 to the device with serial 1234567, run:
```
./copy_media.sh 720x480 -s 1234567
```

Download Mainline-related CTS files

To download the Mainline-related CTS files:

Get the Android API level on the device by running:
```
adb shell getprop ro.build.version.sdk
```
Follow the instructions in the download_mcts.sh script to download the Mainline CTS files.

The download takes at least 10 minutes, depending on your network speed.

Shim packages

The following table lists the packages available for each device version and architecture:

Device Version	Packages (if APEX supported)		Packages (if APEX isn't supported)
	ARM	x86	ARM	x86
Android 15	`15-arm-release`	`android15-x86-release`	`android15-arm-CtsShim.apk` `android15-arm-CtsShimPriv.apk`	`android15-x86-CtsShim.apk` `android15-x86-CtsShimPriv.apk`
Android 14	`android14-arm-release`	`android14-x86-release`	`android14-arm-CtsShim.apk` `android14-arm-CtsShimPriv.apk`	`android14-x86-CtsShim.apk` `android14-x86-CtsShimPriv.apk`
Android 13	`android13-arm-release`	`android13-x86-release`	`android13-arm-CtsShim.apk` `android13-arm-CtsShimPriv.apk`	`android13-x86-CtsShim.apk` `android13-x86-CtsShimPriv.apk`
Android 12	`android12-arm-release`	`android12-x86-release`	`android12-arm-CtsShim.apk` `android12-arm-CtsShimPriv.apk`	`android12-x86-CtsShim.apk` `android12-x86-CtsShimPriv.apk`
Android 11	`android11-arm-release`	`android11-x86-release`	`android11-arm-CtsShim.apk` `android11-arm-CtsShimPriv.apk`	`android11-x86-CtsShim.apk` `android11-x86-CtsShimPriv.apk`
Android 10	`android10-release`		`android10-arm-CtsShim.apk` `android10-arm-CtsShimPriv.apk`	`android10-x86-CtsShim.apk` `android10-x86-CtsShimPriv.apk`
Android 9, O, and O-MR1	N/A	N/A	`arm-CtsShim.apk` `arm-CtsShimPriv.apk`	`x86-CtsShim.apk` `x86-CtsShimPriv.apk`

What's next?

After reading this document, continue to Run automated CTS tests.