TestDevice

public class TestDevice
extends NativeDevice

java.lang.Object
   ↳ com.android.tradefed.device.NativeDevice
     ↳ com.android.tradefed.device.TestDevice

Implementation of a ITestDevice for a full stack android device

Summary

Nested classes

class TestDevice.MicrodroidBuilder

A builder used to create a Microdroid TestDevice. 

Fields

public static final String DISMISS_KEYGUARD_CMD

Commands that can be used to dismiss the keyguard.

Public constructors

TestDevice(IDevice device, IDeviceStateMonitor stateMonitor, IDeviceMonitor allocationMonitor)

Public methods

boolean canSwitchToHeadlessSystemUser()

Returns whether it's allowed to switch to the headless SYSTEM user.

boolean clearErrorDialogs()

Attempt to dismiss any error dialogs currently displayed on device UI.

int createUser(String name)

Create a user with a given name and default flags 0.

int createUser(String name, boolean guest, boolean ephemeral, boolean forTesting)

Create a user with a given name and the provided flags

int createUser(String name, boolean guest, boolean ephemeral)

Create a user with a given name and the provided flags

int createUserNoThrow(String name)

Create a user with a given name and default flags 0.

void disableKeyguard()

Attempts to disable the keyguard.

boolean doesFileExist(String deviceFilePath)

Helper method to determine if file on device exists.

boolean doesFileExist(String deviceFilePath, int userId)

Helper method to determine if file on device exists for a given user.

File dumpHeap(String process, String devicePath)

Attempt to dump the heap from the system_server.

getActiveApexes()

Fetch the information about APEXes activated on the device.

getAllSettings(String namespace)

Return key value pairs of requested namespace.

String getAndroidId(int userId)

Find and return the android-id associated to a userId, null if not found.

getAndroidIds()

Create a Map of android ids found matching user ids.

PackageInfo getAppPackageInfo(String packageName)

Fetch information about a package installed on device.

getAppPackageInfos()

Fetch information of packages installed on the device.

InputStreamSource getBugreport()

Retrieves a bugreport from the device.

InputStreamSource getBugreportz()

Retrieves a bugreportz from the device.

DeviceFoldableState getCurrentFoldableState()

Returns the current foldable state of the device or null if some issues occurred.

int getCurrentUser()

Return the id of the current running user.

getFoldableStates()

Returns the list of foldable states on the device.

getInstalledPackageNames()

Fetch the application package names present on the device.

KeyguardControllerState getKeyguardState()

Return an object to get the current state of the keyguard or null if not supported.

Integer getMainUserId()

Returns the main user id.

getMainlineModuleInfo()

Get the information about the mainline modules installed on the device.

int getMaxNumberOfRunningUsersSupported()

Get the maximum number of supported simultaneously running users.

int getMaxNumberOfUsersSupported()

Get the maximum number of supported users.

Integer getPrimaryUserId()

Returns the primary user id.

InputStreamSource getScreenshot()

Grabs a screenshot from the device.

InputStreamSource getScreenshot(String format, boolean rescale)

Grabs a screenshot from the device.

InputStreamSource getScreenshot(String format)

Grabs a screenshot from the device.

InputStreamSource getScreenshot(long displayId)

Grabs a screenshot from the device given display id.

String getSetting(String namespace, String key)

See getSetting(int, String, String) and performed on system user.

String getSetting(int userId, String namespace, String key)

Return the value of the requested setting.

getUninstallablePackageNames()

Fetch the application package names that can be uninstalled.

int getUserFlags(int userId)

Find and return the flags of a given user.

getUserInfos()

Gets the Map of useId to UserInfo on the device.

int getUserSerialNumber(int userId)

Return the serial number associated to the userId if found, -10000 in any other cases.

boolean hasFeature(String feature)

Check if a feature is available on a device.

String installPackage(File packageFile, boolean reinstall, String... extraArgs)

Install an Android package on device.

String installPackage(File packageFile, boolean reinstall, boolean grantPermissions, String... extraArgs)

Install an Android package on device.

String installPackage(File packageFile, File certFile, boolean reinstall, String... extraArgs)

Install an Android package on device.

String installPackageForUser(File packageFile, boolean reinstall, boolean grantPermissions, int userId, String... extraArgs)

Install an Android package on device for a given user.

String installPackageForUser(File packageFile, boolean reinstall, int userId, String... extraArgs)

Install an Android package on device for a given user.

String installPackages( packageFiles, boolean reinstall, String... extraArgs)

String installPackages( packageFiles, boolean reinstall, boolean grantPermissions, String... extraArgs)

String installPackagesForUser( packageFiles, boolean reinstall, boolean grantPermissions, int userId, String... extraArgs)

String installPackagesForUser( packageFiles, boolean reinstall, int userId, String... extraArgs)

String installRemotePackages( remoteApkPaths, boolean reinstall, String... extraArgs)

String installRemotePackages( remoteApkPaths, boolean reinstall, boolean grantPermissions, String... extraArgs)

boolean isAppEnumerationSupported()

Check whether platform on device supports app enumeration

boolean isHeadlessSystemUserMode()

Returns whether the device uses headless system user mode.

boolean isMainUserPermanentAdmin()

Returns whether the main user is a permanent admin and can't be deleted or downgraded to non-admin status.

boolean isMultiUserSupported()

Determines if multi user is supported.

boolean isPackageInstalled(String packageName)

Query the device for a given package name to check if it's currently installed or not.

boolean isPackageInstalled(String packageName, String userId)

Query the device for a given package name and given user id to check if it's currently installed or not for that user.

boolean isUserRunning(int userId)

Check if a given user is running.

boolean isUserSecondary(int userId)

Return whether the specified user is a secondary user according to it's flags.

boolean isUserVisible(int userId)

Checks if the given user is visible.

boolean isUserVisibleOnDisplay(int userId, int displayId)

Checks if the given user is visible in the given display.

boolean isVisibleBackgroundUsersOnDefaultDisplaySupported()

Returns whether the device allow users to be started visible in the background in the ERROR(/java.android.view.Display#DEFAULT_DISPLAY).

boolean isVisibleBackgroundUsersSupported()

Returns whether the device allow users to be started visible in the background.

listDisplayIds()

Collect the list of available displays id on the device as reported by "dumpsys SurfaceFlinger".

listDisplayIdsForStartingVisibleBackgroundUsers()

Gets the list of displays that can be used to start a user visible in the background.

listUsers()

Gets the list of users on the device.

boolean logBugreport(String dataName, ITestLogger listener)

Helper method to take a bugreport and log it to the reporters.

void postInvocationTearDown(Throwable exception)

Extra steps for device specific required clean up that will be executed after the invocation is done.

boolean removeAdmin(String componentName, int userId)

Remove given device admin in given user and return true if it is successful, false otherwise.

void removeOwners()

Remove all existing device profile owners with the best effort.

boolean removeUser(int userId)

Remove a given user from the device.

boolean setDeviceOwner(String componentName, int userId)

Set a device admin component as device owner in given user.

void setSetting(String namespace, String key, String value)

See setSetting(int, String, String, String) and performed on system user.

void setSetting(int userId, String namespace, String key, String value)

Add a setting value to the namespace of a given user.

void shutdownMicrodroid(ITestDevice microdroidDevice)

Shuts down the microdroid device, if one exist.

boolean startUser(int userId)

Starts a given user in the background if it is currently stopped.

boolean startUser(int userId, boolean waitFlag)

Starts a given user in the background if it is currently stopped.

boolean startVisibleBackgroundUser(int userId, int displayId, boolean waitFlag)

Starts a given user in the background, visible in the given display (i.e., allowing the user to launch activities in that display).

boolean stopUser(int userId, boolean waitFlag, boolean forceFlag)

Stop a given user.

boolean stopUser(int userId)

Stops a given user.

boolean supportsMicrodroid()

Checks the preconditions to run a microdroid.

boolean supportsMicrodroid(boolean protectedVm)

Checks the preconditions to run a microdroid.

boolean switchUser(int userId)

Switch to another userId with a default timeout.

boolean switchUser(int userId, long timeout)

Switch to another userId with the provided timeout as deadline.

Bugreport takeBugreport()

Take a bugreport and returns it inside a Bugreport object to handle it.

String uninstallPackage(String packageName)

Uninstall an Android package from device.

String uninstallPackageForUser(String packageName, int userId)

Uninstall an Android package from device for a given user.

Protected methods

AaptParser createParser(File appFile)
void doAdbReboot(NativeDevice.RebootMode rebootMode, String reason)

Perform a adb reboot.

InputStreamSource getBugreportInternal()
File getBugreportzInternal()

Internal Helper method to get the bugreportz zip file as a ERROR(/File).

long getCheckNewUserSleep()

Exposed for testing.

long getHostCurrentTime()

Exposed for testing

void prePostBootSetup()

Allows each device type (AndroidNativeDevice, TestDevice) to override this method for specific post boot setup.

Fields

DISMISS_KEYGUARD_CMD

public static final String DISMISS_KEYGUARD_CMD

Commands that can be used to dismiss the keyguard.

Public constructors

TestDevice

public TestDevice (IDevice device, 
                IDeviceStateMonitor stateMonitor, 
                IDeviceMonitor allocationMonitor)

Public methods

canSwitchToHeadlessSystemUser

public boolean canSwitchToHeadlessSystemUser ()

Returns whether it's allowed to switch to the headless SYSTEM user.

Returns
boolean

Throws
DeviceNotAvailableException

clearErrorDialogs

public boolean clearErrorDialogs ()

Attempt to dismiss any error dialogs currently displayed on device UI.

Returns
boolean true if no dialogs were present or dialogs were successfully cleared. false otherwise.
Throws
DeviceNotAvailableException

createUser

public int createUser (String name)

Create a user with a given name and default flags 0.

Parameters
name String: of the user to create on the device
Returns
int the integer for the user id created
Throws
DeviceNotAvailableException

createUser

public int createUser (String name, 
                boolean guest, 
                boolean ephemeral, 
                boolean forTesting)

Create a user with a given name and the provided flags

Parameters
name String: of the user to create on the device
guest boolean: enable the user flag --guest during creation
ephemeral boolean: enable the user flag --ephemeral during creation
forTesting boolean: enable the test flag --for-testing during creation
Returns
int id of the created user
Throws
DeviceNotAvailableException

createUser

public int createUser (String name, 
                boolean guest, 
                boolean ephemeral)

Create a user with a given name and the provided flags

Parameters
name String: of the user to create on the device
guest boolean: enable the user flag --guest during creation
ephemeral boolean: enable the user flag --ephemeral during creation
Returns
int id of the created user
Throws
DeviceNotAvailableException

createUserNoThrow

public int createUserNoThrow (String name)

Create a user with a given name and default flags 0.

Parameters
name String: of the user to create on the device
Returns
int the integer for the user id created or -1 for error.
Throws
DeviceNotAvailableException

disableKeyguard

public void disableKeyguard ()

Attempts to disable the keyguard.

First wait for the input dispatch to become ready, this happens around the same time when the device reports BOOT_COMPLETE, apparently asynchronously, because current framework implementation has occasional race condition. Then command is sent to dismiss keyguard (works on non-secure ones only)

Throws
DeviceNotAvailableException

doesFileExist

public boolean doesFileExist (String deviceFilePath)

Helper method to determine if file on device exists.

Parameters
deviceFilePath String: the absolute path of file on device to check
Returns
boolean true if file exists, false otherwise.
Throws
DeviceNotAvailableException

doesFileExist

public boolean doesFileExist (String deviceFilePath, 
                int userId)

Helper method to determine if file on device exists for a given user.

Parameters
deviceFilePath String: the absolute path of file on device to check
userId int: The user id against which to check file existence
Returns
boolean true if file exists, false otherwise.
Throws
DeviceNotAvailableException

dumpHeap

public File dumpHeap (String process, 
                String devicePath)

Attempt to dump the heap from the system_server. It is the caller responsibility to clean up the dumped file.

Parameters
process String: the name of the device process to dumpheap on.
devicePath String: the path on the device where to put the dump. This must be a location where permissions allow it.
Returns
File the ERROR(/File) containing the report. Null if something failed.
Throws
DeviceNotAvailableException

getActiveApexes

public  getActiveApexes ()

Fetch the information about APEXes activated on the device.

Returns
ERROR(/Set) of ApexInfo currently activated on the device
Throws
DeviceNotAvailableException

getAllSettings

public  getAllSettings (String namespace)

Return key value pairs of requested namespace.

Parameters
namespace String: must be one of {"system", "secure", "global"}
Returns
the map of key value pairs. Null if namespace is not supported.
Throws
DeviceNotAvailableException

getAndroidId

public String getAndroidId (int userId)

Find and return the android-id associated to a userId, null if not found.

Parameters
userId int

Returns
String

Throws
DeviceNotAvailableException

getAndroidIds

public  getAndroidIds ()

Create a Map of android ids found matching user ids. There is no insurance that each user id will found an android id associated in this function so some user ids may match null.

Returns
Map of android ids found matching user ids.
Throws
DeviceNotAvailableException

getAppPackageInfo

public PackageInfo getAppPackageInfo (String packageName)

Fetch information about a package installed on device.

Parameters
packageName String

Returns
PackageInfo the PackageInfo or null if information could not be retrieved
Throws
DeviceNotAvailableException

getAppPackageInfos

public  getAppPackageInfos ()

Fetch information of packages installed on the device.

Returns
ERROR(/List) of PackageInfos installed on the device.
Throws
DeviceNotAvailableException

getBugreport

public InputStreamSource getBugreport ()

Retrieves a bugreport from the device.

The implementation of this is guaranteed to continue to work on a device without an sdcard (or where the sdcard is not yet mounted).

Returns
InputStreamSource An InputStreamSource which will produce the bugreport contents on demand. In case of failure, the InputStreamSource will produce an empty ERROR(/InputStream).

getBugreportz

public InputStreamSource getBugreportz ()

Retrieves a bugreportz from the device. Zip format bugreport contains the main bugreport and other log files that are useful for debugging.

Only supported for 'adb version' > 1.0.36

Returns
InputStreamSource a InputStreamSource of the zip file containing the bugreportz, return null in case of failure.

getCurrentFoldableState

public DeviceFoldableState getCurrentFoldableState ()

Returns the current foldable state of the device or null if some issues occurred.

Returns
DeviceFoldableState

Throws
DeviceNotAvailableException

getCurrentUser

public int getCurrentUser ()

Return the id of the current running user. In case of error, return -10000.

Returns
int

Throws
DeviceNotAvailableException

getFoldableStates

public  getFoldableStates ()

Returns the list of foldable states on the device. Can be obtained with "cmd device_state print-states".

Returns
Throws
DeviceNotAvailableException

getInstalledPackageNames

public  getInstalledPackageNames ()

Fetch the application package names present on the device.

Returns
ERROR(/Set) of ERROR(/String) package names currently installed on the device.
Throws
DeviceNotAvailableException

getKeyguardState

public KeyguardControllerState getKeyguardState ()

Return an object to get the current state of the keyguard or null if not supported.

Returns
KeyguardControllerState a KeyguardControllerState containing a snapshot of the state of the keyguard and returns Null if the Keyguard query is not supported.
Throws
DeviceNotAvailableException

getMainUserId

public Integer getMainUserId ()

Returns the main user id.

Returns
Integer the userId of the main user if there is one, and null if there is no main user.
Throws
DeviceNotAvailableException

getMainlineModuleInfo

public  getMainlineModuleInfo ()

Get the information about the mainline modules installed on the device.

Returns
ERROR(/Set) of ERROR(/String) mainline modules currently installed on the device.
Throws
DeviceNotAvailableException

getMaxNumberOfRunningUsersSupported

public int getMaxNumberOfRunningUsersSupported ()

Get the maximum number of supported simultaneously running users. Defaults to 0.

Returns
int an integer indicating the number of simultaneously running users
Throws
DeviceNotAvailableException

getMaxNumberOfUsersSupported

public int getMaxNumberOfUsersSupported ()

Get the maximum number of supported users. Defaults to 0.

Returns
int an integer indicating the number of supported users
Throws
DeviceNotAvailableException

getPrimaryUserId

public Integer getPrimaryUserId ()

Returns the primary user id.

Returns
Integer the userId of the primary user if there is one, and null if there is no primary user.
Throws
DeviceNotAvailableException

getScreenshot

public InputStreamSource getScreenshot ()

Grabs a screenshot from the device.

Returns
InputStreamSource a InputStreamSource of the screenshot in png format, or null if the screenshot was not successful.
Throws
DeviceNotAvailableException

getScreenshot

public InputStreamSource getScreenshot (String format, 
                boolean rescale)

Grabs a screenshot from the device. Recommended to use getScreenshot(String) instead with JPEG encoding for smaller size.

Parameters
format String: supported PNG, JPEG
rescale boolean: if screenshot should be rescaled to reduce the size of resulting image
Returns
InputStreamSource a InputStreamSource of the screenshot in format, or null if the screenshot was not successful.
Throws
DeviceNotAvailableException

getScreenshot

public InputStreamSource getScreenshot (String format)

Grabs a screenshot from the device. Recommended to use getScreenshot(format) instead with JPEG encoding for smaller size

Parameters
format String: supported PNG, JPEG
Returns
InputStreamSource a InputStreamSource of the screenshot in format, or null if the screenshot was not successful.
Throws
DeviceNotAvailableException

getScreenshot

public InputStreamSource getScreenshot (long displayId)

Grabs a screenshot from the device given display id. Format is PNG.

TODO: extend the implementations above to support 'format' and 'rescale'

Parameters
displayId long: the display id of the screen to get screenshot from.
Returns
InputStreamSource a InputStreamSource of the screenshot in format, or null if the screenshot was not successful.
Throws
DeviceNotAvailableException

getSetting

public String getSetting (String namespace, 
                String key)

See getSetting(int, String, String) and performed on system user.

Parameters
namespace String

key String

Returns
String

Throws
DeviceNotAvailableException

getSetting

public String getSetting (int userId, 
                String namespace, 
                String key)

Return the value of the requested setting. namespace must be one of: {"system", "secure", "global"}

Parameters
userId int

namespace String

key String

Returns
String the value associated with the namespace:key of a user. Null if not found.
Throws
DeviceNotAvailableException

getUninstallablePackageNames

public  getUninstallablePackageNames ()

Fetch the application package names that can be uninstalled. This is presently defined as non-system packages, and updated system packages.

Returns
ERROR(/Set) of uninstallable ERROR(/String) package names currently installed on the device.
Throws
DeviceNotAvailableException

getUserFlags

public int getUserFlags (int userId)

Find and return the flags of a given user. Flags are defined in "android.content.pm.UserInfo" class in Android Open Source Project.

Parameters
userId int

Returns
int the flags associated with the userId provided if found, -10000 in any other cases.
Throws
DeviceNotAvailableException

getUserInfos

public  getUserInfos ()

Gets the Map of useId to UserInfo on the device. Will throw DeviceRuntimeException if output from device is not as expected.

Returns
the list of UserInfo objects.
Throws
DeviceNotAvailableException

getUserSerialNumber

public int getUserSerialNumber (int userId)

Return the serial number associated to the userId if found, -10000 in any other cases.

Parameters
userId int

Returns
int

Throws
DeviceNotAvailableException

hasFeature

public boolean hasFeature (String feature)

Check if a feature is available on a device.

Parameters
feature String: which format should be "feature:" or "" directly.
Returns
boolean True if feature is found, false otherwise.
Throws
DeviceNotAvailableException

installPackage

public String installPackage (File packageFile, 
                boolean reinstall, 
                String... extraArgs)

Install an Android package on device.

Parameters
packageFile File: the apk file to install
reinstall boolean: true if a reinstall should be performed
extraArgs String: optional extra arguments to pass. See 'adb shell pm -h' for available options.
Returns
String a ERROR(/String) with an error code, or null if success.
Throws
DeviceNotAvailableException

installPackage

public String installPackage (File packageFile, 
                boolean reinstall, 
                boolean grantPermissions, 
                String... extraArgs)

Install an Android package on device.

Note: Only use cases that requires explicit control of granting runtime permission at install time should call this function.

Parameters
packageFile File: the apk file to install
reinstall boolean: true if a reinstall should be performed
grantPermissions boolean: if all runtime permissions should be granted at install time
extraArgs String: optional extra arguments to pass. See 'adb shell pm -h' for available options.
Returns
String a ERROR(/String) with an error code, or null if success.
Throws
DeviceNotAvailableException

installPackage

public String installPackage (File packageFile, 
                File certFile, 
                boolean reinstall, 
                String... extraArgs)

Install an Android package on device.

Note: Only use cases that requires explicit control of granting runtime permission at install time should call this function.

Parameters
packageFile File: the apk file to install
certFile File: true if a reinstall should be performed
reinstall boolean: if all runtime permissions should be granted at install time
extraArgs String: optional extra arguments to pass. See 'adb shell pm -h' for available options.
Returns
String a ERROR(/String) with an error code, or null if success.
Throws
DeviceNotAvailableException

installPackageForUser

public String installPackageForUser (File packageFile, 
                boolean reinstall, 
                boolean grantPermissions, 
                int userId, 
                String... extraArgs)

Install an Android package on device for a given user.

Note: Only use cases that requires explicit control of granting runtime permission at install time should call this function.

Parameters
packageFile File: the apk file to install
reinstall boolean: true if a reinstall should be performed
grantPermissions boolean: if all runtime permissions should be granted at install time
userId int: the integer user id to install for.
extraArgs String: optional extra arguments to pass. See 'adb shell pm -h' for available options.
Returns
String a ERROR(/String) with an error code, or null if success.
Throws
DeviceNotAvailableException

installPackageForUser

public String installPackageForUser (File packageFile, 
                boolean reinstall, 
                int userId, 
                String... extraArgs)

Install an Android package on device for a given user.

Parameters
packageFile File: the apk file to install
reinstall boolean: true if a reinstall should be performed
userId int: the integer user id to install for.
extraArgs String: optional extra arguments to pass. See 'adb shell pm -h' for available options.
Returns
String a ERROR(/String) with an error code, or null if success.
Throws
DeviceNotAvailableException

installPackages

public String installPackages ( packageFiles, 
                boolean reinstall, 
                String... extraArgs)

Parameters
packageFiles

reinstall boolean

extraArgs String

Returns
String

Throws
DeviceNotAvailableException

installPackages

public String installPackages ( packageFiles, 
                boolean reinstall, 
                boolean grantPermissions, 
                String... extraArgs)

Parameters
packageFiles

reinstall boolean

grantPermissions boolean

extraArgs String

Returns
String

Throws
DeviceNotAvailableException

installPackagesForUser

public String installPackagesForUser ( packageFiles, 
                boolean reinstall, 
                boolean grantPermissions, 
                int userId, 
                String... extraArgs)

Parameters
packageFiles

reinstall boolean

grantPermissions boolean

userId int

extraArgs String

Returns
String

Throws
DeviceNotAvailableException

installPackagesForUser

public String installPackagesForUser ( packageFiles, 
                boolean reinstall, 
                int userId, 
                String... extraArgs)

Parameters
packageFiles

reinstall boolean

userId int

extraArgs String

Returns
String

Throws
DeviceNotAvailableException

installRemotePackages

public String installRemotePackages ( remoteApkPaths, 
                boolean reinstall, 
                String... extraArgs)

Parameters
remoteApkPaths

reinstall boolean

extraArgs String

Returns
String

Throws
DeviceNotAvailableException

installRemotePackages

public String installRemotePackages ( remoteApkPaths, 
                boolean reinstall, 
                boolean grantPermissions, 
                String... extraArgs)

Parameters
remoteApkPaths

reinstall boolean

grantPermissions boolean

extraArgs String

Returns
String

Throws
DeviceNotAvailableException

isAppEnumerationSupported

public boolean isAppEnumerationSupported ()

Check whether platform on device supports app enumeration

Returns
boolean True if app enumeration is supported, false otherwise
Throws
DeviceNotAvailableException

isHeadlessSystemUserMode

public boolean isHeadlessSystemUserMode ()

Returns whether the device uses headless system user mode.

Returns
boolean

Throws
DeviceNotAvailableException

isMainUserPermanentAdmin

public boolean isMainUserPermanentAdmin ()

Returns whether the main user is a permanent admin and can't be deleted or downgraded to non-admin status.

Returns
boolean

Throws
DeviceNotAvailableException

isMultiUserSupported

public boolean isMultiUserSupported ()

Determines if multi user is supported.

Returns
boolean true if multi user is supported, false otherwise
Throws
DeviceNotAvailableException

isPackageInstalled

public boolean isPackageInstalled (String packageName)

Query the device for a given package name to check if it's currently installed or not.

Parameters
packageName String

Returns
boolean True if the package is reported as installed. False otherwise.
Throws
DeviceNotAvailableException

isPackageInstalled

public boolean isPackageInstalled (String packageName, 
                String userId)

Query the device for a given package name and given user id to check if it's currently installed or not for that user.

Parameters
packageName String: the package we are checking if it's installed.
userId String: The user id we are checking the package is installed for. If null, primary user zero will be used.
Returns
boolean True if the package is reported as installed. False otherwise.
Throws
DeviceNotAvailableException

isUserRunning

public boolean isUserRunning (int userId)

Check if a given user is running.

Parameters
userId int

Returns
boolean True if the user is running, false in every other cases.
Throws
DeviceNotAvailableException

isUserSecondary

public boolean isUserSecondary (int userId)

Return whether the specified user is a secondary user according to it's flags.

Parameters
userId int

Returns
boolean true if the user is secondary, false otherwise.
Throws
DeviceNotAvailableException

isUserVisible

public boolean isUserVisible (int userId)

Checks if the given user is visible.

A "visible" user is a user that is interacting with the "human" user and hence is able to launch launch activities (typically in the default display).

Parameters
userId int

Returns
boolean

Throws
DeviceNotAvailableException

isUserVisibleOnDisplay

public boolean isUserVisibleOnDisplay (int userId, 
                int displayId)

Checks if the given user is visible in the given display.

A "visible" user is a user that is interacting with the "human" user and hence is able to launch launch activities in that display.

Parameters
userId int

displayId int

Returns
boolean

Throws
DeviceNotAvailableException

isVisibleBackgroundUsersOnDefaultDisplaySupported

public boolean isVisibleBackgroundUsersOnDefaultDisplaySupported ()

Returns whether the device allow users to be started visible in the background in the ERROR(/java.android.view.Display#DEFAULT_DISPLAY).

If it does, you could call startVisibleBackgroundUser(int, int, boolean), passing a display returned by listDisplayIdsForStartingVisibleBackgroundUsers() (which should include ERROR(/java.android.view.Display#DEFAULT_DISPLAY)).

Returns
boolean

Throws
DeviceNotAvailableException

isVisibleBackgroundUsersSupported

public boolean isVisibleBackgroundUsersSupported ()

Returns whether the device allow users to be started visible in the background.

If it does, you could call startVisibleBackgroundUser(int, int, boolean), passing a display returned by listDisplayIdsForStartingVisibleBackgroundUsers().

Returns
boolean

Throws
DeviceNotAvailableException

listDisplayIds

public  listDisplayIds ()

Collect the list of available displays id on the device as reported by "dumpsys SurfaceFlinger".

Returns
The list of displays. Default always returns the default display 0.
Throws
DeviceNotAvailableException

listDisplayIdsForStartingVisibleBackgroundUsers

public  listDisplayIdsForStartingVisibleBackgroundUsers ()

Gets the list of displays that can be used to start a user visible in the background.

Returns
Throws
DeviceNotAvailableException

listUsers

public  listUsers ()

Gets the list of users on the device. Will throw DeviceRuntimeException if output from device is not as expected.

Returns
the list of user ids.
Throws
DeviceNotAvailableException

logBugreport

public boolean logBugreport (String dataName, 
                ITestLogger listener)

Helper method to take a bugreport and log it to the reporters.

Parameters
dataName String: name under which the bugreport will be reported.
listener ITestLogger: an ITestLogger to log the bugreport.
Returns
boolean True if the logging was successful, false otherwise.

postInvocationTearDown

public void postInvocationTearDown (Throwable exception)

Extra steps for device specific required clean up that will be executed after the invocation is done.

Parameters
exception Throwable: if any, the final exception raised by the invocation failure.

removeAdmin

public boolean removeAdmin (String componentName, 
                int userId)

Remove given device admin in given user and return true if it is successful, false otherwise.

Parameters
componentName String: of device admin to be removed.
userId int: of user that the device admin lives in.
Returns
boolean True if it is successful, false otherwise.
Throws
DeviceNotAvailableException

removeOwners

public void removeOwners ()

Remove all existing device profile owners with the best effort.

Throws
DeviceNotAvailableException

removeUser

public boolean removeUser (int userId)

Remove a given user from the device.

Parameters
userId int: of the user to remove
Returns
boolean true if we were successful in removing the user, false otherwise.
Throws
DeviceNotAvailableException

setDeviceOwner

public boolean setDeviceOwner (String componentName, 
                int userId)

Set a device admin component as device owner in given user.

Parameters
componentName String: of device admin to be device owner.
userId int: of the user that the device owner lives in.
Returns
boolean True if it is successful, false otherwise.
Throws
DeviceNotAvailableException

setSetting

public void setSetting (String namespace, 
                String key, 
                String value)

See setSetting(int, String, String, String) and performed on system user.

Parameters
namespace String

key String

value String

Throws
DeviceNotAvailableException

setSetting

public void setSetting (int userId, 
                String namespace, 
                String key, 
                String value)

Add a setting value to the namespace of a given user. Some settings will only be available after a reboot. namespace must be one of: {"system", "secure", "global"}

Parameters
userId int

namespace String

key String

value String

Throws
DeviceNotAvailableException

shutdownMicrodroid

public void shutdownMicrodroid (ITestDevice microdroidDevice)

Shuts down the microdroid device, if one exist.

Parameters
microdroidDevice ITestDevice

Throws
com.android.tradefed.device.DeviceNotAvailableException
DeviceNotAvailableException

startUser

public boolean startUser (int userId)

Starts a given user in the background if it is currently stopped. If the user is already running in the background, this method is a NOOP.

Parameters
userId int: of the user to start in the background
Returns
boolean true if the user was successfully started in the background.
Throws
DeviceNotAvailableException

startUser

public boolean startUser (int userId, 
                boolean waitFlag)

Starts a given user in the background if it is currently stopped. If the user is already running in the background, this method is a NOOP. Possible to provide extra flag to wait for the operation to have effect.

Parameters
userId int: of the user to start in the background
waitFlag boolean: will make the command wait until user is started and unlocked.
Returns
boolean true if the user was successfully started in the background.
Throws
DeviceNotAvailableException

startVisibleBackgroundUser

public boolean startVisibleBackgroundUser (int userId, 
                int displayId, 
                boolean waitFlag)

Starts a given user in the background, visible in the given display (i.e., allowing the user to launch activities in that display).

NOTE: this command doesn't check if the user exists, display is available, device supports such feature, etc.

Parameters
userId int: of the user to start in the background
displayId int: display to start user visible on
waitFlag boolean: will make the command wait until user is started and unlocked.
Returns
boolean true if the user was successfully started visible in the background.
Throws
DeviceNotAvailableException

stopUser

public boolean stopUser (int userId, 
                boolean waitFlag, 
                boolean forceFlag)

Stop a given user. Possible to provide extra flags to wait for the operation to have effect, and force terminate the user. Cannot stop current and system user.

Parameters
userId int: of the user to stop.
waitFlag boolean: will make the command wait until user is stopped.
forceFlag boolean: will force stop the user.
Returns
boolean true if the user was successfully stopped.
Throws
DeviceNotAvailableException

stopUser

public boolean stopUser (int userId)

Stops a given user. If the user is already stopped, this method is a NOOP. Cannot stop current and system user.

Parameters
userId int: of the user to stop.
Returns
boolean true if the user was successfully stopped.
Throws
DeviceNotAvailableException

supportsMicrodroid

public boolean supportsMicrodroid ()

Checks the preconditions to run a microdroid.

Returns
boolean returns true if the preconditions are satisfied, false otherwise.

supportsMicrodroid

public boolean supportsMicrodroid (boolean protectedVm)

Checks the preconditions to run a microdroid.

Parameters
protectedVm boolean: true if microdroid is intended to run on protected VM.
Returns
boolean returns true if the preconditions are satisfied, false otherwise.

switchUser

public boolean switchUser (int userId)

Switch to another userId with a default timeout. switchUser(int, long).

Parameters
userId int

Returns
boolean True if the new userId matches the userId provider. False otherwise.
Throws
DeviceNotAvailableException

switchUser

public boolean switchUser (int userId, 
                long timeout)

Switch to another userId with the provided timeout as deadline. Attempt to disable keyguard after user change is successful.

Parameters
userId int

timeout long: to wait before returning false for switch-user failed.
Returns
boolean True if the new userId matches the userId provider. False otherwise.
Throws
DeviceNotAvailableException

takeBugreport

public Bugreport takeBugreport ()

Take a bugreport and returns it inside a Bugreport object to handle it. Return null in case of issue. File referenced in the Bugreport object need to be cleaned via Bugreport.close().

Returns
Bugreport

uninstallPackage

public String uninstallPackage (String packageName)

Uninstall an Android package from device.

Parameters
packageName String: the Android package to uninstall
Returns
String a ERROR(/String) with an error code, or null if success.
Throws
DeviceNotAvailableException

uninstallPackageForUser

public String uninstallPackageForUser (String packageName, 
                int userId)

Uninstall an Android package from device for a given user.

Parameters
packageName String: the Android package to uninstall
userId int: the integer user id to uninstall for.
Returns
String a ERROR(/String) with an error code, or null if success.
Throws
DeviceNotAvailableException

Protected methods

createParser

protected AaptParser createParser (File appFile)

Parameters
appFile File

Returns
AaptParser

doAdbReboot

protected void doAdbReboot (NativeDevice.RebootMode rebootMode, 
                String reason)

Perform a adb reboot.

Parameters
rebootMode NativeDevice.RebootMode: a mode of this reboot.
reason String: for this reboot.
Throws
com.android.tradefed.device.DeviceNotAvailableException
DeviceNotAvailableException

getBugreportInternal

protected InputStreamSource getBugreportInternal ()

Returns
InputStreamSource

getBugreportzInternal

protected File getBugreportzInternal ()

Internal Helper method to get the bugreportz zip file as a ERROR(/File).

Returns
File

getCheckNewUserSleep

protected long getCheckNewUserSleep ()

Exposed for testing.

Returns
long

getHostCurrentTime

protected long getHostCurrentTime ()

Exposed for testing

Returns
long

prePostBootSetup

protected void prePostBootSetup ()

Allows each device type (AndroidNativeDevice, TestDevice) to override this method for specific post boot setup.

Throws
DeviceNotAvailableException