Load protocols with global config

In order to understand this section, first study the Tradefed @Option.

Typical options in Tradefed allow for test classes to receive additional information from the XML configuration or command line. This feature allows you to go one extra step and resolve some of this additional information if necessary.

File option example

Example File @option:

@Option(name = 'config-file')
private File mConfigFile;

The above can be set via XML configuration:

<option name="config-file" value="/tmp/file" />

or via command:

--config-file /tmp/file

Description

The feature allows you to resolve File-typed @Options that are remote into a local file to be available seamlessly from a user standpoint.

For this to work, the file needs to be specified with a remote style path. For example:

--config-file gs://bucket/tmp/file

This path points to a file within a Google Cloud Storage (GCS) bucket where it's stored. Tradefed upon seeing that remote path, will attempt to download the file locally and assign it to the @Option. This results in the mConfigFile variable to now point to the local version of the file, which can be used by the test.

If the remote file cannot be downloaded for any reason, Tradefed will throw a ConfigurationException that will prevent the test from running. We consider missing those files a critical failure since some test artifacts will also be missing.

Use query parameters

Adding query parameters to a URL is possible using ?. For example, gs://bucket/path?unzip=true. The key/value unzip=true will be available in the IRemoteFileResolver interface implementation.

Two built-in behaviors are available:

  • unzip: If set to true and the downloaded file is a zip, it will be automatically unzipped to a temporary location. Example: ?unzip=true
  • optional: Defaults to false. If set to true and the resolution fails, it won't throw an exception and will simply not replace the file. Example: ?optional=true

You can also pass global query arguments via --dynamic-download-args key=value that will pass the key/value to all the dynamic downloads attempted in the invocation.

Supported protocols

The officially supported protocols and their corresponding formats are:

  • Google Cloud Storage, protocol: gs, format: gs://<bucket name>/path
  • Local files, protocol: file, format: file:/local/path
  • http links, protocol: http, format: http://url
  • https links, protocol: https, format: https://url

Limitations

The dynamic resolution of @Option currently supports only a limited number of protocols and locations to download from. The resolution of @Option is currently enabled only for the main XML Tradefed configuration.

If running as a suite, current modules (AndroidTest.xml) will not resolve the files by default. This is meant to prevent modules from creating some unknown dependencies. This can be escaped by using --enable-module-dynamic-download at the suite level, but major suites such as the Compatibility Test Suite (CTS) and Vendor Test Suite (VTS) will not enable it.

Implement a new protocol

The protocols that are supported have an implementation in Tradefed of the IRemoteFileResolver interface ,which defines the short tag of the protocol that will be matched in the file path through getSupportedProtocol. For example, gs is used for the Google Cloud Storage protocol. The recommended interface to implement is #resolveRemoteFiles(RemoteFileResolverArgs) which will be the long-term maintained interface.

The protocols implemented can be added to the harness META-INF services file to officially turn on the support.