Starting March 27, 2025, we recommend using android-latest-release instead of aosp-main to build and contribute to AOSP. For more information, see Changes to AOSP.

InvocationExecution

public class InvocationExecution
extends Object implements IInvocationExecution

java.lang.Object
↳	com.android.tradefed.invoker.InvocationExecution

Known direct subclasses

DelegatedInvocationExecution, ParentSandboxInvocationExecution, RemoteInvocationExecution, SandboxedInvocationExecution

DelegatedInvocationExecution	`InvocationExecution` which delegate the execution to another Tradefed binary.
ParentSandboxInvocationExecution	Version of `InvocationExecution` for the parent invocation special actions when running a sandbox.
RemoteInvocationExecution	Implementation of `InvocationExecution` that drives a remote execution.
SandboxedInvocationExecution	Special sandbox execution of the invocation: This is the InvocationExection for when we are inside the sandbox running the command.

Class that describes all the invocation steps: build download, target_prep, run tests, clean up. Can be extended to override the default behavior of some steps. Order of the steps is driven by TestInvocation.

Summary

Fields
`public static final String`	`ADB_VERSION_KEY`
`public static final String`	`JAVA_CLASSPATH_KEY`
`public static final String`	`JAVA_VERSION_KEY`

Public constructors
`InvocationExecution()`

Public methods
`void`	`cleanUpBuilds(IInvocationContext context, IConfiguration config)` Execute the build_provider clean up step.
`void`	`doCleanUp(IInvocationContext context, IConfiguration config, Throwable exception)` Execute the target_preparer and multi_target_preparer cleanUp step.
`void`	`doSetup(TestInformation testInfo, IConfiguration config, ITestLogger listener)` Execute the target_preparer and multi_target_preparer setUp step.
`void`	`doTeardown(TestInformation testInfo, IConfiguration config, ITestLogger logger, Throwable exception)` Execute the target_preparer and multi_target_preparer teardown step.
`boolean`	`fetchBuild(TestInformation testInfo, IConfiguration config, IRescheduler rescheduler, ITestInvocationListener listener)` Execute the build_provider step of the invocation.
`void`	`reportLogs(ITestDevice device, ITestLogger listener, TestInvocation.Stage stage)` Report some device logs at different stage of the invocation.
`void`	`runDevicePostInvocationTearDown(IInvocationContext context, IConfiguration config, Throwable exception)` Invoke the `ITestDevice.postInvocationTearDown(Throwable)` for each device part of the invocation.
`void`	`runDevicePreInvocationSetup(IInvocationContext context, IConfiguration config, ITestLogger logger)` Invoke the `ERROR(ITestDevice.preInvocationSetup(IBuildInfo)/com.android.tradefed.device.ITestDevice#preInvocationSetup(com.android.tradefed.build.IBuildInfo) ITestDevice.preInvocationSetup(IBuildInfo))` for each device part of the invocation.
`void`	`runTests(TestInformation info, IConfiguration config, ITestInvocationListener listener)` Runs the test.
`boolean`	`shardConfig(IConfiguration config, TestInformation testInfo, IRescheduler rescheduler, ITestLogger logger)` Attempt to shard the configuration into sub-configurations, to be re-scheduled to run on multiple resources in parallel.

Protected methods
`void`	`collectAutoInfo(IConfiguration config, TestInformation info)` Collect automatically some information on the primary device under test.
`IShardHelper`	`createShardHelper()` Create an return the `IShardHelper` to be used.
`void`	`customizeDevicePreInvocation(IConfiguration config, IInvocationContext context)` Give a chance to customize some of the device before preInvocationSetup.
`String`	`getAdbVersion()` Returns the adb version in use for the invocation.
	`getLabPreparersToRun(IConfiguration config, String deviceName)` Retrieve a list of lab preparers to run on this device.
	`getTargetPreparersToRun(IConfiguration config, String deviceName)` Retrieve a list of target preparers to run on this device.
`void`	`linkExternalDirs(IBuildInfo info, TestInformation testInfo)`
`void`	`logHostAdb(IConfiguration config, ITestLogger logger)` Collect the logs from $TMPDIR/adb.$UID.log.
`Throwable`	`runPreparersTearDown(TestInformation testInfo, ITestDevice device, String deviceName, int deviceIndex, ITestLogger logger, Throwable exception, preparersToRun, trackPreparersMap)`
`void`	`setTestTag(IBuildInfo info, IConfiguration config)` Handle setting the test tag on the build info.

Fields

ADB_VERSION_KEY

public static final String ADB_VERSION_KEY

JAVA_CLASSPATH_KEY

public static final String JAVA_CLASSPATH_KEY

JAVA_VERSION_KEY

public static final String JAVA_VERSION_KEY

Public constructors

InvocationExecution

public InvocationExecution ()

Public methods

cleanUpBuilds

public void cleanUpBuilds (IInvocationContext context, 
                IConfiguration config)

Execute the build_provider clean up step. Associated with the build fetching.

Parameters
`context`	`IInvocationContext`: the `IInvocationContext` of the invocation.
`config`	`IConfiguration`: the `IConfiguration` of this test run.

doCleanUp

public void doCleanUp (IInvocationContext context, 
                IConfiguration config, 
                Throwable exception)

Execute the target_preparer and multi_target_preparer cleanUp step. Does the devices clean up.

Parameters
`context`	`IInvocationContext`: the `IInvocationContext` of the invocation.
`config`	`IConfiguration`: the `IConfiguration` of this test run.
`exception`	`Throwable`: the original exception thrown by the test running.

doSetup

public void doSetup (TestInformation testInfo, 
                IConfiguration config, 
                ITestLogger listener)

Execute the target_preparer and multi_target_preparer setUp step. Does all the devices setup required for the test to run.

Parameters
`testInfo`	`TestInformation`: the `TestInformation` of the invocation.
`config`	`IConfiguration`: the `IConfiguration` of this test run.
`listener`	`ITestLogger`: the `ITestLogger` to report setup failures logs.

Throws
`BuildError`
`DeviceNotAvailableException`
`TargetSetupError`

doTeardown

public void doTeardown (TestInformation testInfo, 
                IConfiguration config, 
                ITestLogger logger, 
                Throwable exception)

Execute the target_preparer and multi_target_preparer teardown step. Does the devices tear down associated with the setup.

Parameters
`testInfo`	`TestInformation`: the `TestInformation` of the invocation.
`config`	`IConfiguration`: the `IConfiguration` of this test run.
`logger`	`ITestLogger`: the `ITestLogger` to report logs.
`exception`	`Throwable`: the original exception thrown by the test running.

fetchBuild

public boolean fetchBuild (TestInformation testInfo, 
                IConfiguration config, 
                IRescheduler rescheduler, 
                ITestInvocationListener listener)

Execute the build_provider step of the invocation.

Parameters
`testInfo`	`TestInformation`: the `TestInformation` of the invocation.
`config`	`IConfiguration`: the `IConfiguration` of this test run.
`rescheduler`	`IRescheduler`: the `IRescheduler`, for rescheduling portions of the invocation for execution on another resource(s)
`listener`	`ITestInvocationListener`: the `ITestInvocation` to report build download failures.

Returns
`boolean`	True if we successfully downloaded the build, false otherwise.

Throws
`BuildRetrievalError`
`DeviceNotAvailableException`

reportLogs

public void reportLogs (ITestDevice device, 
                ITestLogger listener, 
                TestInvocation.Stage stage)

Report some device logs at different stage of the invocation. For example: logcat.

Parameters
`device`	`ITestDevice`: The device to report logs from.
`listener`	`ITestLogger`: The logger for the logs.
`stage`	`TestInvocation.Stage`: The stage of the invocation we are at.

runDevicePostInvocationTearDown

public void runDevicePostInvocationTearDown (IInvocationContext context, 
                IConfiguration config, 
                Throwable exception)

Invoke the ITestDevice.postInvocationTearDown(Throwable) for each device part of the invocation.

Parameters
`context`	`IInvocationContext`: the `IInvocationContext` of the invocation.
`config`	`IConfiguration`: the `IConfiguration` of this test run.
`exception`	`Throwable`: the original exception thrown by the test running if any.

runDevicePreInvocationSetup

public void runDevicePreInvocationSetup (IInvocationContext context, 
                IConfiguration config, 
                ITestLogger logger)

Invoke the ERROR(ITestDevice.preInvocationSetup(IBuildInfo)/com.android.tradefed.device.ITestDevice#preInvocationSetup(com.android.tradefed.build.IBuildInfo) ITestDevice.preInvocationSetup(IBuildInfo)) for each device part of the invocation.

Parameters
`context`	`IInvocationContext`: the `IInvocationContext` of the invocation.
`config`	`IConfiguration`: the `IConfiguration` of this test run.
`logger`	`ITestLogger`: the `ITestLogger` to report logs.

Throws
`DeviceNotAvailableException`
`TargetSetupError`

runTests

public void runTests (TestInformation info, 
                IConfiguration config, 
                ITestInvocationListener listener)

Runs the test.

Parameters
`info`	`TestInformation`: the `TestInformation` to run tests with.
`config`	`IConfiguration`: the `IConfiguration` to run
`listener`	`ITestInvocationListener`: the `ITestInvocationListener` of test results

shardConfig

public boolean shardConfig (IConfiguration config, 
                TestInformation testInfo, 
                IRescheduler rescheduler, 
                ITestLogger logger)

Attempt to shard the configuration into sub-configurations, to be re-scheduled to run on multiple resources in parallel.

If a shard count is greater than 1, it will simply create configs for each shard by setting shard indices and reschedule them. If a shard count is not set,it would fallback to IShardHelper.shardConfig.

Parameters
`config`	`IConfiguration`: the current `IConfiguration`.
`testInfo`	`TestInformation`: the `TestInformation` holding the info of the tests.
`rescheduler`	`IRescheduler`: the `IRescheduler`.
`logger`	`ITestLogger`: `ITestLogger` used to log file during sharding.

Returns
`boolean`	true if test was sharded. Otherwise return `false`

Protected methods

collectAutoInfo

protected void collectAutoInfo (IConfiguration config, 
                TestInformation info)

Collect automatically some information on the primary device under test.

Parameters
`config`	`IConfiguration`
`info`	`TestInformation`

Throws
`DeviceNotAvailableException`

createShardHelper

protected IShardHelper createShardHelper ()

Create an return the IShardHelper to be used.

Returns
`IShardHelper`

customizeDevicePreInvocation

protected void customizeDevicePreInvocation (IConfiguration config, 
                IInvocationContext context)

Give a chance to customize some of the device before preInvocationSetup.

Parameters
`config`	`IConfiguration`: The config of the invocation.
`context`	`IInvocationContext`: The current invocation context.

getAdbVersion

protected String getAdbVersion ()

Returns the adb version in use for the invocation.

Returns
`String`

getLabPreparersToRun

protected  getLabPreparersToRun (IConfiguration config, 
                String deviceName)

Retrieve a list of lab preparers to run on this device.

Overridden in sandbox classes to restrict lab preparers from being run inside the sandbox child

Parameters
`config`	`IConfiguration`
`deviceName`	`String`

Returns

getTargetPreparersToRun

protected  getTargetPreparersToRun (IConfiguration config, 
                String deviceName)

Retrieve a list of target preparers to run on this device.

Overridden in sandbox classes to restrict lab preparers from being run inside the sandbox child

Parameters
`config`	`IConfiguration`
`deviceName`	`String`

Returns

linkExternalDirs

protected void linkExternalDirs (IBuildInfo info, 
                TestInformation testInfo)

Parameters
`info`	`IBuildInfo`
`testInfo`	`TestInformation`

logHostAdb

protected void logHostAdb (IConfiguration config, 
                ITestLogger logger)

Collect the logs from $TMPDIR/adb.$UID.log.

Parameters
`config`	`IConfiguration`
`logger`	`ITestLogger`

runPreparersTearDown

protected Throwable runPreparersTearDown (TestInformation testInfo, 
                ITestDevice device, 
                String deviceName, 
                int deviceIndex, 
                ITestLogger logger, 
                Throwable exception, 
                 preparersToRun, 
                 trackPreparersMap)

Parameters
`testInfo`	`TestInformation`
`device`	`ITestDevice`
`deviceName`	`String`
`deviceIndex`	`int`
`logger`	`ITestLogger`
`exception`	`Throwable`
`preparersToRun`
`trackPreparersMap`

Returns
`Throwable`

setTestTag

protected void setTestTag (IBuildInfo info, 
                IConfiguration config)

Handle setting the test tag on the build info.

Parameters
`info`	`IBuildInfo`
`config`	`IConfiguration`