TestDevice

public class TestDevice
extends NativeDevice

java.lang.Object
   ↳ com.android.tradefed.device.NativeDevice
     ↳ com.android.tradefed.device.TestDevice
Known Direct Subclasses
RemoteAndroidDevice Implementation of a ITestDevice for a full stack android device connected via adb connect. 

Implementation of a ITestDevice for a full stack android device

Summary

Constants

String DISMISS_DIALOG_CMD

the command used to dismiss a error dialog.

String DISMISS_KEYGUARD_CMD

Commands that can be used to dismiss the keyguard.

String DISMISS_KEYGUARD_WM_CMD

Alternative command to dismiss the keyguard by requesting the Window Manager service to do it.

String LIST_PACKAGES_CMD

Public constructors

TestDevice(IDevice device, IDeviceStateMonitor stateMonitor, IDeviceMonitor allocationMonitor)

Public methods

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)

Create a user with a given name and the provided flags

void disableKeyguard()

Attempts to disable the keyguard.

File dumpHeap(String process, String devicePath)

Attempt to dump the heap from the system_server.

String getAndroidId(int userId)

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

Map<Integer, String> getAndroidIds()

Create a Map of android ids found matching user ids.

PackageInfo getAppPackageInfo(String packageName)

Fetch information about a package installed on device.

int getCurrentUser()

Return the id of the current running user.

Set<String> 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.

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.

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.

Set<String> getUninstallablePackageNames()

Fetch the application package names that can be uninstalled.

int getUserFlags(int userId)

Find and return the flags of a given user.

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)
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.

boolean isMultiUserSupported()

Determines if multi user is supported.

boolean isUserRunning(int userId)

Check if a given user is running.

ArrayList<Integer> listUsers()

Gets the list of users on the device.

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.

boolean startUser(int userId)

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

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

Stop a given user.

boolean stopUser(int userId)

Stops a given user.

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.

String uninstallPackage(String packageName)

Uninstall an Android package from device.

Protected methods

void doAdbReboot(String into)

Perform a adb reboot.

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.

Constants

DISMISS_DIALOG_CMD

String DISMISS_DIALOG_CMD

the command used to dismiss a error dialog. Currently sends a DPAD_CENTER key event

Constant Value: "input keyevent 23"

DISMISS_KEYGUARD_CMD

String DISMISS_KEYGUARD_CMD

Commands that can be used to dismiss the keyguard.

Constant Value: "input keyevent 82"

DISMISS_KEYGUARD_WM_CMD

String DISMISS_KEYGUARD_WM_CMD

Alternative command to dismiss the keyguard by requesting the Window Manager service to do it. Api 23 and after.

Constant Value: "wm dismiss-keyguard"

LIST_PACKAGES_CMD

String LIST_PACKAGES_CMD

Constant Value: "pm list packages -f"

Public constructors

TestDevice

TestDevice (IDevice device, 
                IDeviceStateMonitor stateMonitor, 
                IDeviceMonitor allocationMonitor)

Public methods

clearErrorDialogs

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

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
IllegalStateException

createUser

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
IllegalStateException

disableKeyguard

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

dumpHeap

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 File containing the report. Null if something failed.
Throws
DeviceNotAvailableException

getAndroidId

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

Map<Integer, String> 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<Integer, String> Map of android ids found matching user ids.
Throws
DeviceNotAvailableException

getAppPackageInfo

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

getCurrentUser

int getCurrentUser ()

Return the id of the current running user.

Returns
int

Throws
DeviceNotAvailableException

getInstalledPackageNames

Set<String> getInstalledPackageNames ()

Fetch the application package names present on the device.

Returns
Set<String> Set of String package names currently installed on the device.
Throws
DeviceNotAvailableException

getKeyguardState

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

getMaxNumberOfUsersSupported

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

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

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

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

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

getSetting

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

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

Set<String> getUninstallablePackageNames ()

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

Returns
Set<String> Set of uninstallable String package names currently installed on the device.
Throws
DeviceNotAvailableException

getUserFlags

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

getUserSerialNumber

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

boolean hasFeature (String feature)

Check if a feature is available on a device.

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

installPackage

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 install --help' for available options.
Returns
String a String with an error code, or null if success.
Throws
DeviceNotAvailableException

installPackage

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 install --help' for available options.
Returns
String a String with an error code, or null if success.
Throws
DeviceNotAvailableException

installPackage

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

Parameters
packageFile File

certFile File

reinstall boolean

extraArgs String

Returns
String

Throws
DeviceNotAvailableException

installPackageForUser

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 install --help' for available options.
Returns
String a String with an error code, or null if success.
Throws
DeviceNotAvailableException

installPackageForUser

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 install --help' for available options.
Returns
String a String with an error code, or null if success.
Throws
DeviceNotAvailableException

isMultiUserSupported

boolean isMultiUserSupported ()

Determines if multi user is supported.

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

isUserRunning

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

listUsers

ArrayList<Integer> listUsers ()

Gets the list of users on the device. Defaults to null.

Returns
ArrayList<Integer> the list of user ids or null if there was an error.
Throws
DeviceNotAvailableException

removeAdmin

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

void removeOwners ()

Remove all existing device profile owners with the best effort.

Throws
DeviceNotAvailableException

removeUser

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

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

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

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

startUser

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

stopUser

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

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

switchUser

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

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

uninstallPackage

String uninstallPackage (String packageName)

Uninstall an Android package from device.

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

Protected methods

doAdbReboot

void doAdbReboot (String into)

Perform a adb reboot.

Parameters
into String: the bootloader name to reboot into, or null to just reboot the device.
Throws
DeviceNotAvailableException

getCheckNewUserSleep

long getCheckNewUserSleep ()

Exposed for testing.

Returns
long

getHostCurrentTime

long getHostCurrentTime ()

Exposed for testing

Returns
long

prePostBootSetup

void prePostBootSetup ()

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

Throws
DeviceNotAvailableException