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 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
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.
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.
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.
String
getMicrodroidCID ()
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, File certFile, 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
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, boolean grantPermissions, String... extraArgs)
String
installRemotePackages ( remoteApkPaths, boolean reinstall, String... extraArgs)
boolean
isAppEnumerationSupported ()
Check whether platform on device supports app enumeration
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.
listDisplayIds ()
Collect the list of available displays id on the device as reported by "dumpsys
SurfaceFlinger".
listUsers ()
Gets the list of users on the device.
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
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.
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.
Fields
DISMISS_KEYGUARD_CMD
public static final String DISMISS_KEYGUARD_CMD
Commands that can be used to dismiss the keyguard.
Public constructors
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.
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
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
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.
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)
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.
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.
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.
getActiveApexes
public getActiveApexes ()
Fetch the information about APEXes activated on the device.
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.
getAndroidId
public String getAndroidId (int userId)
Find and return the android-id associated to a userId, null if not found.
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.
getAppPackageInfo
public PackageInfo getAppPackageInfo (String packageName)
Fetch information about a package installed on device.
Parameters
packageName
String
getAppPackageInfos
public getAppPackageInfos ()
Fetch information of packages installed on the device.
getCurrentFoldableState
public DeviceFoldableState getCurrentFoldableState ()
Returns the current foldable state of the device or null if some issues occurred.
getCurrentUser
public int getCurrentUser ()
Return the id of the current running user. In case of error, return -10000.
getFoldableStates
public getFoldableStates ()
Returns the list of foldable states on the device. Can be obtained with
"cmd device_state print-states".
getInstalledPackageNames
public getInstalledPackageNames ()
Fetch the application package names present on the device.
getKeyguardState
public KeyguardControllerState getKeyguardState ()
Return an object to get the current state of the keyguard or null if not supported.
getMainlineModuleInfo
public getMainlineModuleInfo ()
Get the information about the mainline modules installed on the device.
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
public int getMaxNumberOfUsersSupported ()
Get the maximum number of supported users. Defaults to 0.
Returns
int
an integer indicating the number of supported users
getMicrodroidCID
public String getMicrodroidCID ()
Returns
String
Returns the CID of the microdroid vm. If TestDevice is not a microdroid, return null.
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.
getScreenshot
public InputStreamSource getScreenshot ()
Grabs a screenshot from the device.
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
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
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.
getSetting
public String getSetting (String namespace,
String key)
See getSetting(int, String, String)
and performed on system user.
Parameters
namespace
String
key
String
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.
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 String
package names currently installed on the
device.
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.
Returns
int
the flags associated with the userId provided if found, -10000 in any other cases.
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.
getUserSerialNumber
public int getUserSerialNumber (int userId)
Return the serial number associated to the userId if found, -10000 in any other cases.
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.
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 String
with an error code, or null
if success.
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 String
with an error code, or null
if success.
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 String
with an error code, or null
if success.
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 String
with an error code, or null
if success.
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 String
with an error code, or null
if success.
installPackages
public String installPackages ( packageFiles,
boolean reinstall,
String... extraArgs)
Parameters
packageFiles
reinstall
boolean
extraArgs
String
installPackages
public String installPackages ( packageFiles,
boolean reinstall,
boolean grantPermissions,
String... extraArgs)
Parameters
packageFiles
reinstall
boolean
grantPermissions
boolean
extraArgs
String
installPackagesForUser
public String installPackagesForUser ( packageFiles,
boolean reinstall,
boolean grantPermissions,
int userId,
String... extraArgs)
Parameters
packageFiles
reinstall
boolean
grantPermissions
boolean
userId
int
extraArgs
String
installPackagesForUser
public String installPackagesForUser ( packageFiles,
boolean reinstall,
int userId,
String... extraArgs)
Parameters
packageFiles
reinstall
boolean
userId
int
extraArgs
String
installRemotePackages
public String installRemotePackages ( remoteApkPaths,
boolean reinstall,
boolean grantPermissions,
String... extraArgs)
Parameters
remoteApkPaths
reinstall
boolean
grantPermissions
boolean
extraArgs
String
installRemotePackages
public String installRemotePackages ( remoteApkPaths,
boolean reinstall,
String... extraArgs)
Parameters
remoteApkPaths
reinstall
boolean
extraArgs
String
isAppEnumerationSupported
public boolean isAppEnumerationSupported ()
Check whether platform on device supports app enumeration
Returns
boolean
True if app enumeration is supported, false otherwise
isMultiUserSupported
public boolean isMultiUserSupported ()
Determines if multi user is supported.
Returns
boolean
true if multi user is supported, false otherwise
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.
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.
isUserRunning
public boolean isUserRunning (int userId)
Check if a given user is running.
Returns
boolean
True if the user is running, false in every other cases.
isUserSecondary
public boolean isUserSecondary (int userId)
Return whether the specified user is a secondary user according to it's flags.
Returns
boolean
true if the user is secondary, false otherwise.
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.
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.
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.
removeOwners
public void removeOwners ()
Remove all existing device profile owners with the best effort.
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.
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.
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
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
shutdownMicrodroid
public void shutdownMicrodroid (ITestDevice microdroidDevice)
Shuts down the microdroid device, if one exist.
Parameters
microdroidDevice
ITestDevice
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.
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.
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.
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.
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)
.
Returns
boolean
True if the new userId matches the userId provider. False otherwise.
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.
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.
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 String
with an error code, or null
if success.
Protected methods
createParser
protected AaptParser createParser (File appFile)
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.
getCheckNewUserSleep
protected long getCheckNewUserSleep ()
Exposed for testing.
getHostCurrentTime
protected long getHostCurrentTime ()
Exposed for testing
prePostBootSetup
protected void prePostBootSetup ()
Allows each device type (AndroidNativeDevice, TestDevice) to override this method for
specific post boot setup.
Send feedback
Content and code samples on this page are subject to the licenses described in the Content License . Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2022-08-03 UTC.
[{
"type": "thumb-down",
"id": "missingTheInformationINeed",
"label":"Missing the information I need"
},{
"type": "thumb-down",
"id": "tooComplicatedTooManySteps",
"label":"Too complicated / too many steps"
},{
"type": "thumb-down",
"id": "outOfDate",
"label":"Out of date"
},{
"type": "thumb-down",
"id": "samplesCodeIssue",
"label":"Samples / code issue"
},{
"type": "thumb-down",
"id": "otherDown",
"label":"Other"
}]
[{
"type": "thumb-up",
"id": "easyToUnderstand",
"label":"Easy to understand"
},{
"type": "thumb-up",
"id": "solvedMyProblem",
"label":"Solved my problem"
},{
"type": "thumb-up",
"id": "otherUp",
"label":"Other"
}]
Need to tell us more?