Advanced ACTS guide

This is a guide on how to run Android Comms Test Suite (ACTS) tests.

Get the code

The most up-to-date version of ACTS can be found in the Android Open Source Project (AOSP) Gerrit repository in /platform/tools/test/connectivity/.

For details on how to sync the code, see Download the source and the Android Developer Codelab. When syncing the code, sync the main branch. Don't sync a tagged build.

Note that when downloading ACTS, you don't need to sync the entire Android repository. To sync only ACTS, after running the repo init command, run:

repo sync platform/tools/test/connectivity

ACTS can be found under <repo>/tools/test/connectivity/acts/.

Environment setup

To make sure that ACTS has the required dependencies for setup, install the following Python 3 setup tools:

sudo apt-get install python3-setuptools
sudo apt-get install python3-pip
sudo apt-get install adb fastboot
sudo pip3 install --upgrade pip setuptools
# Needed due to an on-going bug.
sudo apt-get install protobuf-compiler

Install ACTS

The setup.py script found in <repo>/tools/test/connectivity/acts/framework installs the rest of the dependencies and ACTS itself.

For continuous development on or with ACTS, run the following command:

cd <repo>/tools/test/connectivity/acts/framework/
sudo python3 setup.py develop
cd -

If you want to run only tests, run this command instead:

cd <repo>/tools/test/connectivity/acts/framework/
sudo python3 setup.py install
cd -

Verify installation

After setup, make sure that you can use act.py in your terminal, and import ACTS modules in Python. For example:

act.py -h
usage: act.py [-h] -c <PATH> [--test_args Arg1 Arg2 ... ]
python3
>>> from acts.controllers import android_device
>>> device_list = android_device.get_all_instances()

Run without install

Users can run ACTS without installing the package directly. The only step that must be performed is modifying the Python path to import from <repo>/tools/test/connectivity/acts/framework. Before running ACTS, run setup.py install_deps to install all required dependencies by ACTS without installing ACTS. If an existing version of ACTS is on your machine, run sudo setup.py uninstall.

To run ACTS, use one of the following commands:

cd <repo>/tools/test/connectivity/acts/framework; acts/bin/act.py

export PYTHONPATH=<repo>/tools/test/connectivity/acts/framework; acts/bin/act.py

ACTS outputs messages requesting -c and -tc flags. For more information, see Configuring ACTS Tests.

Set up ACTS in a virtual environment

To isolate your installation from other installations of ACTS, you should install ACTS in a virtual environment. The following steps assumes that you have acts_test.zip from aosp-main on ci.android.com or have direct access to the source.

Get ACTS.

Builds are published. For more information, see Android Continuous Integration. You can pull zip files from a build on ci.android.com. Look for the test_suites_x86_64 target.

The acts_test.zip file is under the Artifacts tab. For this example, assume that acts_test.zip has been downloaded to /tmp/acts_test.zip.

If you have access to the source code, you can use that instead.
Install virtualenv on your machine.

If you don't have it already, you can install virtualenv using:
```
python3 -m pip install -U --user virtualenv
```
Create and activate the virtual environment (in /tmp/my_virtualenv for this example). This ensures that new packages are installed in the virtualenv directory.
```
python3 -m virtualenv /tmp/my_virtualenv
source /tmp/my_virtualenv/bin/activate
```

Install ACTS. Run the following command.

unzip /tmp/acts_test.zip -d /tmp/my_virtualenv/acts
cd /tmp/my_virtualenv/acts/tools/test/connectivity/acts/framework/
python3 setup.py install

If you have access to the code directly, you can skip the unzip:

cd /path/to/acts/framework
python3 setup.py install

Run ACTS from anywhere.
```
act.py -c <config> ...
```
Leave the virtual environment when finished running tests.
```
deactivate
```

Flash the Android device (optional)

If you want to get system privileged control of the device, flash the device with a userdebug build.

To flash the device, use the Android Flash Tool (flash.android.com/). For more details, see the documentation at Android Flash Tool.

Install SL4A (optional, recommended)

If you're using a device with a userdebug build, you have the option to get system privilege control of your device using SL4A. If your test doesn't use SL4A on the device, you can set the skip_sl4a flag in the ACTS config to disable the feature.

"AndroidDevice": [{"serial": "standardized serial number reference", "skip_sl4a": true}, ...]

To get the SL4A APK, follow the instructions at Scripting Layer for Android.