Pass options and filters to suite and modules

First, ensure you understand Option Handling in Tradefed.

Suite setup describes the two layers that exist in the suite structure:

  • The top-level suite
  • The modules

In a non-suite Tradefed context, there is no need to think about it; every option goes to the full invocation. In a suite context, modules are kept isolated from the suite; so not all options are available at their level.

Pass options to the top-level suite

The top-level suite behaves like standard Tradefed configuration: the full configuration including the suite runner receives all the options like a non-suite Tradefed configuration.

Pass options to the modules

Modules by default do not receive any of the options passed to the command. They need to be explicitly targeted to receive the options through the module-arg option. This isolation of the modules options makes debugging easier.

Example:

cts-tradefed run cts --module-arg <module-name>:<option-name>:<option-value>

cts-tradefed run cts --module-arg CtsGestureTestCases:collect-tests-only:true

The syntax ensures that the targeted module will receive the given option.

There are additional ways to pass options to modules such as test-arg, which allows you to pass options to the test runner of each module based on the runner type or class.

Example:

cts-tradefed run cts --test-arg <test-class>:<option-name>:<option-value>

cts-tradefed run cts --test-arg com.android.tradefed.testtype.JarHosttest:collect-tests-only:true

The syntax does not target a particular module but rather all the test runners of the given class. test-arg considers only implementations of IRemoteTest as potential receiver of the options.

Pass options to a Java test class in a java_test_host

If you are adding an @Option to your java test class as part of a java_test_host build target you will need to use the following to inject that option:

cts-tradefed run cts --module-arg <module-name>:set-option:<option-name>:<option-value>

set-option in this context is the option of the HostTest runner from the test harness that wraps your java classes to execute them.

if your jar file target for the options contains multiple test classes, by default, they are all expected to have the @option specified or use the following syntax to target a single class:

cts-tradefed run cts --module-arg <module-name>:set-option:<class-name>:<option-name>:<option-value>

Pass filters to the suite

To filter some tests from a suite, we use --include-filter and --exclude-filter to respectively force include or exclude a particular test or module. Exclusion has priority.

They use this format: [abi] <module-name> [test name]

Examples:

--include-filter CtsGestureTestCases

--include-filter armeabi-v7a CtsGestureTestCases

--include-filter armeabi-v7a CtsGestureTestCases android.gesture.cts.GestureTest#testGetStrokes