TestDevice

public class TestDevice
extends NativeDevice

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

Known direct subclasses

RemoteAndroidDevice

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.
`long`	`INSTALL_TIMEOUT_MINUTES` Timeout in minutes for the package installation
`long`	`INSTALL_TIMEOUT_TO_OUTPUT_MINUTES` Max timeout to output for package installation
`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.
`Map<String, String>`	`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.
`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`	`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.
`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.
`void`	`postInvocationTearDown()` 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.
`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

static final 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

static final String DISMISS_KEYGUARD_CMD

Commands that can be used to dismiss the keyguard.

Constant Value: "input keyevent 82"

DISMISS_KEYGUARD_WM_CMD

static final 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"

INSTALL_TIMEOUT_MINUTES

static final long INSTALL_TIMEOUT_MINUTES

Timeout in minutes for the package installation

Constant Value: 4 (0x0000000000000004)

INSTALL_TIMEOUT_TO_OUTPUT_MINUTES

static final long INSTALL_TIMEOUT_TO_OUTPUT_MINUTES

Max timeout to output for package installation

Constant Value: 3 (0x0000000000000003)

LIST_PACKAGES_CMD

static final String LIST_PACKAGES_CMD

Constant Value: "pm list packages -f"

Public constructors

TestDevice

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

Public methods

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`
`IllegalStateException`

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`
`IllegalStateException`

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`

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

Throws
`DeviceNotAvailableException`

getAllSettings

public Map<String, String> getAllSettings (String namespace)

Return key value pairs of requested namespace.

Parameters
`namespace`	`String`: must be one of {"system", "secure", "global"}

Returns
`Map<String, String>`	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 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

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`

getCurrentUser

public int getCurrentUser ()

Return the id of the current running user.

Returns
`int`

Throws
`DeviceNotAvailableException`

getInstalledPackageNames

public 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

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`

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`

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

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`

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:".

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 install --help' for available options.

Returns
`String`	a `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 install --help' for available options.

Returns
`String`	a `String` with an error code, or `null` if success.

Throws
`DeviceNotAvailableException`

installPackage

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

Parameters
`packageFile`	`File`
`certFile`	`File`
`reinstall`	`boolean`
`extraArgs`	`String`

Returns
`String`

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 install --help' for available options.

Returns
`String`	a `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 install --help' for available options.

Returns
`String`	a `String` with an error code, or `null` if success.

Throws
`DeviceNotAvailableException`

isMultiUserSupported

public boolean isMultiUserSupported ()

Determines if multi user is supported.

Returns
`boolean`	true if multi user is supported, 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`

listUsers

public ArrayList<Integer> listUsers ()

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

Returns
`ArrayList<Integer>`	the list of user ids.

Throws
`DeviceNotAvailableException`

postInvocationTearDown

public void postInvocationTearDown ()

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

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`

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`

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`

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`

uninstallPackage

public 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

protected 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

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`

TestDevice

Summary

Constants

Public constructors

Public methods

Protected methods

Constants

DISMISS_DIALOG_CMD

DISMISS_KEYGUARD_CMD

DISMISS_KEYGUARD_WM_CMD

INSTALL_TIMEOUT_MINUTES

INSTALL_TIMEOUT_TO_OUTPUT_MINUTES

LIST_PACKAGES_CMD

Public constructors

TestDevice

Public methods

clearErrorDialogs

createUser

createUser

disableKeyguard

dumpHeap

getAllSettings

getAndroidId

getAndroidIds

getAppPackageInfo

getCurrentUser

getInstalledPackageNames

getKeyguardState

getMaxNumberOfRunningUsersSupported

getMaxNumberOfUsersSupported

getPrimaryUserId

getScreenshot

getScreenshot

getScreenshot

getSetting

getSetting

getUninstallablePackageNames

getUserFlags

getUserSerialNumber

hasFeature

installPackage

installPackage

installPackage

installPackageForUser

installPackageForUser

isMultiUserSupported

isUserRunning

listUsers

postInvocationTearDown

removeAdmin

removeOwners

removeUser

setDeviceOwner

setSetting

setSetting

startUser

stopUser

stopUser

switchUser

switchUser

uninstallPackage

Protected methods

doAdbReboot

getCheckNewUserSleep

getHostCurrentTime

prePostBootSetup

Interfaces

Classes

Enums

Exceptions