Effective in 2026, to align with our trunk stable development model and ensure platform stability for the ecosystem, we will publish source code to AOSP in Q2 and Q4. For building and contributing to AOSP, use android-latest-release. The android-latest-release manifest branch will always reference the most recent release pushed to AOSP. For more information, see Changes to AOSP.

GTestBase

public abstract class GTestBase
extends Object implements IAbiReceiver, IConfigurationReceiver, IRemoteTest, IRuntimeHintProvider, IShardableTest, ITestCollector, ITestFilterReceiver

java.lang.Object
↳	com.android.tradefed.testtype.GTestBase

Known direct subclasses

GTest, HostGTest

GTest	A Test that runs a native test package on given device.
HostGTest	A Test that runs a native test package.

Known indirect subclasses

ArtGTest

The base class of gTest

Summary

Constants
`String`	`FILTER_EXTENSION`
`String`	`GTEST_FLAG_FILE`
`String`	`GTEST_FLAG_FILTER`
`String`	`GTEST_FLAG_LIST_TESTS`
`String`	`GTEST_FLAG_PRINT_TIME`
`String`	`GTEST_FLAG_RUN_DISABLED_TESTS`
`String`	`GTEST_XML_OUTPUT`

Public constructors
`GTestBase()`

Public methods
`void`	`addAllExcludeFilters(Set<String> filters)` Adds the `Set` of filters of which tests to exclude.
`void`	`addAllIncludeFilters(Set<String> filters)` Adds the `Set` of filters of which tests to include.
`void`	`addExcludeFilter(String filter)` Adds a filter of which tests to exclude.
`void`	`addIncludeFilter(String filter)` Adds a filter of which tests to include.
`String`	`cleanFilter(String filter)`
`void`	`clearExcludeFilters()` Delete all the exclude filters currently tracked.
`void`	`clearIncludeFilters()` Delete all the include filters currently tracked.
`IAbi`	`getAbi()`
`List<String>`	`getAfterTestCmd()` Gets shell command(s) to run after GTest.
`List<String>`	`getBeforeTestCmd()` Gets shell command(s) to run before GTest.
`Set<String>`	`getExcludeFilters()` Returns the current `Set` of exclude filters.
`Set<String>`	`getFileExclusionFilterRegex()` Gets regex to exclude certain files from executing.
`List<String>`	`getGTestFlags()` Gets Additional flag values to pass to the native test's shell command.
`Set<String>`	`getIncludeFilters()` Returns the current `Set` of include filters.
`long`	`getMaxTestTimeMs()` Gets the max time for a gtest to run.
`String`	`getModuleName()` Get the Android native test module to run.
`boolean`	`getRunDisabledTests()` Get whether GTest should run disabled tests.
`long`	`getRuntimeHint()` Return the expected runtime of the test in milliseconds.
`int`	`getShardCount()` Returns the current shard-count.
`int`	`getShardIndex()` Gets the shard index of this test.
`String`	`getTestFilterKey()` Gets test filter key.
`String`	`getTestModule()` Gets module name.
`boolean`	`isCollectTestsOnly()` Gets only invoke the test binary to collect list of applicable test cases or not.
`boolean`	`isEnableXmlOutput()` Gets use gtest xml output for test results or not.
`boolean`	`isSharded()` Gets isSharded flag.
`void`	`notifyTestExecution(boolean incompleteTestFound, Set<String> failedTests)` Notify parent of test execution, so that inclusion/exclusion filters can be handled properly for the retry attempts.
`void`	`setAbi(IAbi abi)`
`void`	`setCollectTestsOnly(boolean shouldCollectTest)` Enables or disables test collection mode
`void`	`setConfiguration(IConfiguration configuration)` Injects the `IConfiguration` in use.
`void`	`setModuleName(String moduleName)` Set the Android native test module to run.
`void`	`setShardCount(int shardCount)` Sets the shard count of this test.
`void`	`setShardIndex(int shardIndex)` Sets the shard index of this test.
`Collection<IRemoteTest>`	`split(int shardCountHint)` Alternative version of `split()` which also provides the shardCount that is attempted to be run.

Protected methods
`String`	`convertName(String gtestFlagName)`
`String`	`createFlagFile(String filter)` Create a file containing the filters that will be used via --gtest_flagfile to avoid any OS limitation in args size.
`void`	`erasePrependedFileName(Set<String> filters, String filename)`
`String`	`getAllGTestFlags(String path)` Helper to get all the GTest flags to pass into the adb shell command.
`IConfiguration`	`getConfiguration()` Returns the test configuration.
`String`	`getExceptionMessage(Exception e)` Make a best effort attempt to retrieve a meaningful short descriptive message for given `Exception`
`String`	`getGTestCmdLine(String fullPath, String flags)` Helper method to build the gtest command to run.
`String`	`getGTestCmdLineWrapper(String fullPath, String flags)` Helper which allows derived classes to wrap the gtest command under some other tool (chroot, strace, gdb, and similar).
`String`	`getGTestFilters(String path)` Helper to get the g-test filter of test to run.
`ITestInvocationListener`	`getGTestListener(ITestInvocationListener... listeners)` Returns the GTestListener that provides extra debugging info, like detects and reports duplicate tests if mDisabledDuplicateCheck is false.
`abstract String`	`loadFilter(String path)` Define get filter method.
`void`	`setRunDisabled(boolean runDisabled)` Set whether GTest should run disabled tests.

Constants

FILTER_EXTENSION

protected static final String FILTER_EXTENSION

Constant Value: ".filter"

GTEST_FLAG_FILE

protected static final String GTEST_FLAG_FILE

Constant Value: "--gtest_flagfile"

GTEST_FLAG_FILTER

protected static final String GTEST_FLAG_FILTER

Constant Value: "--gtest_filter"

GTEST_FLAG_LIST_TESTS

protected static final String GTEST_FLAG_LIST_TESTS

Constant Value: "--gtest_list_tests"

GTEST_FLAG_PRINT_TIME

protected static final String GTEST_FLAG_PRINT_TIME

Constant Value: "--gtest_print_time"

GTEST_FLAG_RUN_DISABLED_TESTS

protected static final String GTEST_FLAG_RUN_DISABLED_TESTS

Constant Value: "--gtest_also_run_disabled_tests"

GTEST_XML_OUTPUT

protected static final String GTEST_XML_OUTPUT

Constant Value: "--gtest_output=xml:%s"

Public constructors

GTestBase

public GTestBase ()

Public methods

addAllExcludeFilters

public void addAllExcludeFilters (Set<String> filters)

Adds the Set of filters of which tests to exclude.

Parameters
`filters`	`Set`

addAllIncludeFilters

public void addAllIncludeFilters (Set<String> filters)

Adds the Set of filters of which tests to include.

Parameters
`filters`	`Set`

addExcludeFilter

public void addExcludeFilter (String filter)

Adds a filter of which tests to exclude.

Parameters
`filter`	`String`

addIncludeFilter

public void addIncludeFilter (String filter)

Adds a filter of which tests to include.

Parameters
`filter`	`String`

cleanFilter

public String cleanFilter (String filter)

Parameters
`filter`	`String`

Returns
`String`

clearExcludeFilters

public void clearExcludeFilters ()

Delete all the exclude filters currently tracked.

clearIncludeFilters

public void clearIncludeFilters ()

Delete all the include filters currently tracked.

getAbi

public IAbi getAbi ()

Returns
`IAbi`

getAfterTestCmd

public List<String> getAfterTestCmd ()

Gets shell command(s) to run after GTest.

Returns
`List<String>`

getBeforeTestCmd

public List<String> getBeforeTestCmd ()

Gets shell command(s) to run before GTest.

Returns
`List<String>`

getExcludeFilters

public Set<String> getExcludeFilters ()

Returns the current Set of exclude filters.

Returns
`Set<String>`

getFileExclusionFilterRegex

public Set<String> getFileExclusionFilterRegex ()

Gets regex to exclude certain files from executing.

Returns
`Set<String>`

getGTestFlags

public List<String> getGTestFlags ()

Gets Additional flag values to pass to the native test's shell command.

Returns
`List<String>`

getIncludeFilters

public Set<String> getIncludeFilters ()

Returns the current Set of include filters.

Returns
`Set<String>`

getMaxTestTimeMs

public long getMaxTestTimeMs ()

Gets the max time for a gtest to run.

Returns
`long`

getModuleName

public String getModuleName ()

Get the Android native test module to run.

Returns
`String`	the name of the native test module to run, or null if not set

getRunDisabledTests

public boolean getRunDisabledTests ()

Get whether GTest should run disabled tests.

Returns
`boolean`	True if disabled tests should be run, false otherwise

getRuntimeHint

public long getRuntimeHint ()

Return the expected runtime of the test in milliseconds. The time is used to load balance sharded execution

Returns
`long`

getShardCount

public int getShardCount ()

Returns the current shard-count.

Returns
`int`

getShardIndex

public int getShardIndex ()

Gets the shard index of this test.

Returns
`int`

getTestFilterKey

public String getTestFilterKey ()

Gets test filter key.

Returns
`String`

getTestModule

public String getTestModule ()

Gets module name.

Returns
`String`

isCollectTestsOnly

public boolean isCollectTestsOnly ()

Gets only invoke the test binary to collect list of applicable test cases or not.

Returns
`boolean`

isEnableXmlOutput

public boolean isEnableXmlOutput ()

Gets use gtest xml output for test results or not.

Returns
`boolean`

isSharded

public boolean isSharded ()

Gets isSharded flag.

Returns
`boolean`

notifyTestExecution

public void notifyTestExecution (boolean incompleteTestFound, 
                Set<String> failedTests)

Notify parent of test execution, so that inclusion/exclusion filters can be handled properly for the retry attempts.

Parameters
`incompleteTestFound`	`boolean`
`failedTests`	`Set`

setAbi

public void setAbi (IAbi abi)

Parameters
`abi`	`IAbi`

setCollectTestsOnly

public void setCollectTestsOnly (boolean shouldCollectTest)

Enables or disables test collection mode

setConfiguration

public void setConfiguration (IConfiguration configuration)

Injects the IConfiguration in use.

Parameters
`configuration`	`IConfiguration`

setModuleName

public void setModuleName (String moduleName)

Set the Android native test module to run.

Parameters
`moduleName`	`String`: The name of the native test module to run

setShardCount

public void setShardCount (int shardCount)

Sets the shard count of this test.

Parameters
`shardCount`	`int`

setShardIndex

public void setShardIndex (int shardIndex)

Sets the shard index of this test.

Parameters
`shardIndex`	`int`

split

public Collection<IRemoteTest> split (int shardCountHint)

Alternative version of split() which also provides the shardCount that is attempted to be run. This is useful for some test runner that cannot arbitrarily decide sometimes.

Parameters
`shardCountHint`	`int`: the attempted shard count.

Returns
`Collection<IRemoteTest>`	a collection of subtests to be executed separately or `null` if test is not currently shardable

Protected methods

convertName

protected String convertName (String gtestFlagName)

Parameters
`gtestFlagName`	`String`

Returns
`String`

createFlagFile

protected String createFlagFile (String filter)

Create a file containing the filters that will be used via --gtest_flagfile to avoid any OS limitation in args size.

Parameters
`filter`	`String`: The filter string

Returns
`String`	The path to the file containing the filter.

Throws
	com.android.tradefed.device.DeviceNotAvailableException
`DeviceNotAvailableException`

erasePrependedFileName

protected void erasePrependedFileName (Set<String> filters, 
                String filename)

Parameters
`filters`	`Set`
`filename`	`String`

getAllGTestFlags

protected String getAllGTestFlags (String path)

Helper to get all the GTest flags to pass into the adb shell command.

Parameters
`path`	`String`: the full path of the binary on the device.

Returns
`String`	the `String` of all the GTest flags that should be passed to the GTest

Throws
`DeviceNotAvailableException`

getConfiguration

protected IConfiguration getConfiguration ()

Returns the test configuration.

Returns
`IConfiguration`	an IConfiguration

getExceptionMessage

protected String getExceptionMessage (Exception e)

Make a best effort attempt to retrieve a meaningful short descriptive message for given Exception

Parameters
`e`	`Exception`: the `Exception`

Returns
`String`	a short message

getGTestCmdLine

protected String getGTestCmdLine (String fullPath, 
                String flags)

Helper method to build the gtest command to run.

Parameters
`fullPath`	`String`: absolute file system path to gtest binary on device
`flags`	`String`: gtest execution flags

Returns
`String`	the shell command line to run for the gtest

getGTestCmdLineWrapper

protected String getGTestCmdLineWrapper (String fullPath, 
                String flags)

Helper which allows derived classes to wrap the gtest command under some other tool (chroot, strace, gdb, and similar).

Parameters
`fullPath`	`String`
`flags`	`String`

Returns
`String`

getGTestFilters

protected String getGTestFilters (String path)

Helper to get the g-test filter of test to run.

Note that filters filter on the function name only (eg: Google Test "Test"); all Google Test "Test Cases" will be considered.

Parameters
`path`	`String`: the full path of the binary on the device.

Returns
`String`	the full filter flag to pass to the g-test, or an empty string if none have been specified

Throws
`DeviceNotAvailableException`

getGTestListener

protected ITestInvocationListener getGTestListener (ITestInvocationListener... listeners)

Returns the GTestListener that provides extra debugging info, like detects and reports duplicate tests if mDisabledDuplicateCheck is false. Otherwise, returns the passed-in listener.

Parameters
`listeners`	`ITestInvocationListener`

Returns
`ITestInvocationListener`

loadFilter

protected abstract String loadFilter (String path)

Define get filter method.

Sub class must implement how to get it's own filter.

Parameters
`path`	`String`: the full path of the filter file.

Returns
`String`	filter string.

Throws
`DeviceNotAvailableException`

setRunDisabled

protected void setRunDisabled (boolean runDisabled)

Set whether GTest should run disabled tests.

Parameters
`runDisabled`	`boolean`