Configure ACTS tests

This page describes how to configure ACTS tests.

Sources of configuration

The Android Comms Test Suite (ACTS) has three major sources of configuration:

  • The command line interface (CLI)
  • The ACTS config file
  • Environment variables

Values from these sources are combined into a single configuration that's used to run an ACTS test. If values are specified in multiple locations, the values are overwritten based on the order above (where the CLI takes precedence).

A note on environment variables

Be careful when using environment variables for ACTS tests. These values are the least visible to the user, and aren't recommended for use outside of a developer's workstation. Environment variables are disabled during ACTS automated tests to prevent environment poisoning.

Required configuration variables

Every ACTS test requires the following variables to be set.

ACTS test paths

ACTS runs from a single main entry location. As a result, the test path location is unknown to the runner.

Set the test path location using the ACTS_TESTPATH environment variable or with the -tp/--testpaths flag in the command line. The value can be a list of directories.

ACTS test classes

ACTS must know what test classes to run. This can be a regex or a list of test class names.

To set this value, use the -tc/--test_class flag in the command line. Note that this flag also accepts a list of class names. The class names must match their corresponding file names, for example, SampleTest must be found in SampleTest.py.

ACTS log path

ACTS must have a location to write logs to other than STDOUT. ACTS writes full debug logs containing data that can help determine why some tests are failing. To prevent clutter, ACTS doesn't write these logs to STDOUT.

To set the log path, use the ACTS_LOGPATH environment variable or the -lp/--logpath flag in the command line.

ACTS config path

To run the test, ACTS must know what testbed exists. The ACTS config contains all the devices in the testbed, and any special test or environment parameters that might be needed. Set this value on the command line using -c/--config.

If there are multiple testbeds within the config, ACTS runs the tests for each testbed. To only run the test for a single testbed in the list, use the -tb/--testbed <NAME> command line argument.

A local workstation example

Most ACTS users develop on a single Android repo branch, and have a setup similar to this one:

# in ~/.bashrc
ACTS_LOGPATH='/tmp/acts_logpath'
ACTS_TESTPATH='~/android/<REPO_BRANCH>/tools/test/connectivity/acts_tests/'

# On cmdline
$ act.py -c ~/acts_configs/local_config.json -tc SampleTest -tb marlin

If ACTS users run on multiple branches, they often run ACTS from the acts/framework directory, and use a relative path for ACTS_TESTPATH:

# in ~/.bashrc
ACTS_LOGPATH='/tmp/acts_logpath'
ACTS_TESTPATH='../acts_tests/'

# On cmdline
$ cd ~/android/main/tools/test/connectivity/acts_tests/acts_contrib/
$ act.py -c ~/acts_configs/local_config.json -tc SampleTest -tb marlin

Configure your testbeds

The ACTS config file provides all the necessary information for running tests on hardware devices:

{
  "testbed": {
    "my_testbed": {
      "my_testbed_value": "value"
    },
    "another_testbed": {
      "AndroidDevice": [
        "53R147"
      ]
    }
  },
  "user_parameter_1": "special environment value",
  "user_parameter_2": "other special value"
}

The base unit of this configuration is the testbed. In the example configuration above, the testbed my_testbed is created with a single testbed value. The second testbed, another_testbed, has a special controller config that holds the information for a list of Android devices. These devices are stored in a list of devices under self.android_devices. Note that if a testbed doesn't specify an AndroidDevice object, a test class that expects an AndroidDevice object raises an exception. For a full list of supported controller configs that come with ACTS, see the list at /acts/framework/acts/controllers/.

All other values (that aren't special values mentioned in the section above) are stored in self.user_params as a dictionary. This is a good place to hold environment or test information such as whether phones are in a metered data environment, or how long to collect data for a test.

Special cases for AndroidDevice

For development convenience when you want to have multiple devices with different properties available, AndroidDevice has some special cases.

JSON config format

All the key/value pairs in the following JSON example are set to the corresponding AndroidDevice object. If the config tries to overwrite a parameter defined in the AndroidDevice attribute, ControllerError is thrown.

  "AndroidDevice": [{"serial": "XXXXXX", "label": "publisher"},
                    {"serial": "YYYYYY", "label": "subscriber", "user_parameter_1": "anything"}]

Then in the test script, you can use a filter function to retrieve the correct device and access extra parameters from the device object:

  def setup_class(self):
      self.pub = next(filter(lambda ad: ad.label == 'publisher',
                             self.android_devices))
      self.sub = next(filter(lambda ad: ad.label == 'user_parameter_1',
                             self.android_devices))

Optional parameter

The following is an optional parameter:

  • adb_logcat_param: A string appended to the adb logcat command for gathering adb logs. By default, adb logcat -v threadtime -b all is used. If adb_logcat_param is set, the -b all section is overwritten. For example, setting adb_logcat_param to -b radio changes the command to adb logcat -v threadtime -b radio.