ITestDevice

public interface ITestDevice
implements INativeDevice

com.android.tradefed.device.ITestDevice

Provides an reliable and slightly higher level API to a ddmlib IDevice.

Retries device commands for a configurable amount, and provides a device recovery interface for devices which are unresponsive.

Summary

Nested classes

class ITestDevice.ApexInfo

A simple struct class to store information about a single APEX  

class ITestDevice.MountPointInfo

A simple struct class to store information about a single mountpoint  

enum ITestDevice.RecoveryMode

 

Public methods

abstract boolean checkConnectivity()

Check that device has network connectivity.

abstract boolean clearErrorDialogs()

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

abstract void clearLastConnectedWifiNetwork()

Clears the last connected wifi network.

abstract boolean connectToWifiNetwork(String wifiSsid, String wifiPsk)

Connects to a wifi network.

abstract boolean connectToWifiNetwork(String wifiSsid, String wifiPsk, boolean scanSsid)

Connects to a wifi network.

abstract boolean connectToWifiNetworkIfNeeded(String wifiSsid, String wifiPsk, boolean scanSsid)

A variant of connectToWifiNetwork(String, String) that only connects if device currently does not have network connectivity.

abstract boolean connectToWifiNetworkIfNeeded(String wifiSsid, String wifiPsk)

A variant of connectToWifiNetwork(String, String) that only connects if device currently does not have network connectivity.

abstract int createUser(String name)

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

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

Create a user with a given name and the provided flags

abstract int createUserNoThrow(String name)

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

abstract void disableKeyguard()

Attempts to disable the keyguard.

abstract boolean disableNetworkMonitor()

Disables network monitoring on device.

abstract boolean disconnectFromWifi()

Disconnects from a wifi network.

abstract File dumpHeap(String process, String devicePath)

Attempt to dump the heap from the system_server.

abstract boolean enableNetworkMonitor()

Enables network monitoring on device.

abstract getActiveApexes()

Fetch the information about APEXes activated on the device.

abstract getAllSettings(String namespace)

Return key value pairs of requested namespace.

abstract String getAndroidId(int userId)

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

abstract getAndroidIds()

Create a Map of android ids found matching user ids.

abstract PackageInfo getAppPackageInfo(String packageName)

Fetch information about a package installed on device.

abstract int getCurrentUser()

Return the id of the current running user.

abstract getInstalledPackageNames()

Fetch the application package names present on the device.

abstract String getIpAddress()

Gets the device's IP address.

abstract KeyguardControllerState getKeyguardState()

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

abstract int getMaxNumberOfRunningUsersSupported()

Get the maximum number of supported simultaneously running users.

abstract int getMaxNumberOfUsersSupported()

Get the maximum number of supported users.

abstract TestDeviceOptions getOptions()

Fetch the test options for the device.

abstract Integer getPrimaryUserId()

Returns the primary user id.

abstract InputStreamSource getScreenshot()

Grabs a screenshot from the device.

abstract InputStreamSource getScreenshot(String format, boolean rescale)

Grabs a screenshot from the device.

abstract InputStreamSource getScreenshot(int displayId)

Grabs a screenshot from the device given display id.

abstract InputStreamSource getScreenshot(String format)

Grabs a screenshot from the device.

abstract String getSetting(String namespace, String key)

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

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

Return the value of the requested setting.

abstract getUninstallablePackageNames()

Fetch the application package names that can be uninstalled.

abstract int getUserFlags(int userId)

Find and return the flags of a given user.

abstract getUserInfos()

Gets the Map of useId to UserInfo on the device.

abstract int getUserSerialNumber(int userId)

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

abstract boolean hasFeature(String feature)

Check if a feature is available on a device.

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

Install an Android package on device.

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

Install an Android package on device.

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

Install an Android package on device for a given user.

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

Install an Android package on device for a given user.

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

Install an Android application made of several APK files (one main and extra split packages).

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

Install an Android application made of several APK files (one main and extra split packages) that are sitting on the android device.

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

Install an Android application made of several APK files (one main and extra split packages) for a given user.

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

Install an Android application made of several APK files (one main and extra split packages) for a given user.

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

Install an Android application made of several APK files (one main and extra split packages) that are sitting on the android device.

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

Install an Android application made of several APK files (one main and extra split packages) that are sitting on the android device.

abstract boolean isMultiUserSupported()

Determines if multi user is supported.

abstract boolean isPackageInstalled(String packageName)

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

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

abstract boolean isUserRunning(int userId)

Check if a given user is running.

abstract boolean isUserSecondary(int userId)

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

abstract boolean isWifiEnabled()

Test if wifi is enabled.

abstract listDisplayIds()

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

abstract listUsers()

Gets the list of users on the device.

abstract boolean removeAdmin(String componentName, int userId)

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

abstract void removeOwners()

Remove all existing device profile owners with the best effort.

abstract boolean removeUser(int userId)

Remove a given user from the device.

abstract boolean setDeviceOwner(String componentName, int userId)

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

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

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

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

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

abstract boolean startUser(int userId)

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

abstract boolean startUser(int userId, boolean waitFlag)

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

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

Stop a given user.

abstract boolean stopUser(int userId)

Stops a given user.

abstract boolean switchUser(int userId)

Switch to another userId with a default timeout.

abstract boolean switchUser(int userId, long timeout)

Switch to another userId with the provided timeout as deadline.

abstract String uninstallPackage(String packageName)

Uninstall an Android package from device.

Public methods

checkConnectivity

public abstract boolean checkConnectivity ()

Check that device has network connectivity.

Returns
boolean true if device has a working network connection, false overwise.
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

clearErrorDialogs

public abstract 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 if connection with device is lost and cannot be recovered.

clearLastConnectedWifiNetwork

public abstract void clearLastConnectedWifiNetwork ()

Clears the last connected wifi network. This should be called when starting a new invocation to avoid connecting to the wifi network used in the previous test after device reboots.

connectToWifiNetwork

public abstract boolean connectToWifiNetwork (String wifiSsid, 
                String wifiPsk)

Connects to a wifi network.

Turns on wifi and blocks until a successful connection is made to the specified wifi network. Once a connection is made, the instance will try to restore the connection after every reboot until ITestDevice#disconnectFromWifi() or ITestDevice#clearLastConnectedWifiNetwork() is called.

Parameters
wifiSsid String: the wifi ssid to connect to
wifiPsk String: PSK passphrase or null if unencrypted
Returns
boolean true if connected to wifi network successfully. false otherwise
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

connectToWifiNetwork

public abstract boolean connectToWifiNetwork (String wifiSsid, 
                String wifiPsk, 
                boolean scanSsid)

Connects to a wifi network.

Turns on wifi and blocks until a successful connection is made to the specified wifi network. Once a connection is made, the instance will try to restore the connection after every reboot until ITestDevice#disconnectFromWifi() or ITestDevice#clearLastConnectedWifiNetwork() is called.

Parameters
wifiSsid String: the wifi ssid to connect to
wifiPsk String: PSK passphrase or null if unencrypted
scanSsid boolean: whether to scan for hidden SSID for this network.
Returns
boolean true if connected to wifi network successfully. false otherwise
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

connectToWifiNetworkIfNeeded

public abstract boolean connectToWifiNetworkIfNeeded (String wifiSsid, 
                String wifiPsk, 
                boolean scanSsid)

A variant of connectToWifiNetwork(String, String) that only connects if device currently does not have network connectivity.

Parameters
scanSsid boolean: whether to scan for hidden SSID for this network
Returns
boolean true if connected to wifi network successfully. false otherwise
Throws
DeviceNotAvailableException

connectToWifiNetworkIfNeeded

public abstract boolean connectToWifiNetworkIfNeeded (String wifiSsid, 
                String wifiPsk)

A variant of connectToWifiNetwork(String, String) that only connects if device currently does not have network connectivity.

Returns
boolean true if connected to wifi network successfully. false otherwise
Throws
DeviceNotAvailableException

createUser

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

disableNetworkMonitor

public abstract boolean disableNetworkMonitor ()

Disables network monitoring on device.

Returns
boolean true if monitoring is disabled successfully. false if it failed.
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

disconnectFromWifi

public abstract boolean disconnectFromWifi ()

Disconnects from a wifi network.

Removes all networks from known networks list and disables wifi.

Returns
boolean true if disconnected from wifi network successfully. false if disconnect failed.
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

dumpHeap

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

enableNetworkMonitor

public abstract boolean enableNetworkMonitor ()

Enables network monitoring on device.

Returns
boolean true if monitoring is enabled successfully. false if it failed.
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

getActiveApexes

public abstract  getActiveApexes ()

Fetch the information about APEXes activated on the device.

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

getAllSettings

public abstract  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 abstract 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 abstract  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 abstract 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 abstract int getCurrentUser ()

Return the id of the current running user.

Returns
int

Throws
DeviceNotAvailableException
DeviceRuntimeException

getInstalledPackageNames

public abstract  getInstalledPackageNames ()

Fetch the application package names present on the device.

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

getIpAddress

public abstract String getIpAddress ()

Gets the device's IP address.

Returns
String the device's IP address, or null if device has no IP address
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

getKeyguardState

public abstract 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 if connection with device is lost and cannot be recovered.

getMaxNumberOfRunningUsersSupported

public abstract 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 abstract int getMaxNumberOfUsersSupported ()

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

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

getOptions

public abstract TestDeviceOptions getOptions ()

Fetch the test options for the device.

Returns
TestDeviceOptions TestDeviceOptions related to the device under test.

getPrimaryUserId

public abstract 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
com.android.tradefed.device.DeviceNotAvailableException
DeviceRuntimeException if the output from the device is not as expected.
DeviceNotAvailableException

getScreenshot

public abstract 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 abstract 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 abstract InputStreamSource getScreenshot (int 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 int: 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

getScreenshot

public abstract 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 abstract 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 abstract 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 abstract  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.
Throws
DeviceNotAvailableException

getUserFlags

public abstract 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 abstract  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
com.android.tradefed.device.DeviceNotAvailableException
DeviceRuntimeException
DeviceNotAvailableException

getUserSerialNumber

public abstract 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 abstract 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 abstract 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 if connection with device is lost and cannot be recovered.

installPackage

public abstract 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 if connection with device is lost and cannot be recovered.
UnsupportedOperationException if runtime permission is not supported by the platform on device.

installPackageForUser

public abstract 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 if connection with device is lost and cannot be recovered.
UnsupportedOperationException if runtime permission is not supported by the platform on device.

installPackageForUser

public abstract 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 if connection with device is lost and cannot be recovered.

installPackages

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

Install an Android application made of several APK files (one main and extra split packages). See "https://developer.android.com/studio/build/configure-apk-splits" on how to split apk to several files.

Parameters
packageFiles : the local apk files
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 if connection with device is lost and cannot be recovered.
UnsupportedOperationException if runtime permission is not supported by the platform on device.

installPackages

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

Install an Android application made of several APK files (one main and extra split packages) that are sitting on the android device. See "https://developer.android.com/studio/build/configure-apk-splits" on how to split apk to several files.

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

Parameters
packageFiles : the remote apk file paths 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 if connection with device is lost and cannot be recovered.
UnsupportedOperationException if runtime permission is not supported by the platform on device.

installPackagesForUser

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

Install an Android application made of several APK files (one main and extra split packages) for a given user. See "https://developer.android.com/studio/build/configure-apk-splits" on how to split apk to several files.

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

Parameters
packageFiles : the local apk files
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 if connection with device is lost and cannot be recovered.
UnsupportedOperationException if runtime permission is not supported by the platform on device.

installPackagesForUser

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

Install an Android application made of several APK files (one main and extra split packages) for a given user. See "https://developer.android.com/studio/build/configure-apk-splits" on how to split apk to several files.

Parameters
packageFiles : the local apk files
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 if connection with device is lost and cannot be recovered.
UnsupportedOperationException if runtime permission is not supported by the platform on device.

installRemotePackages

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

Install an Android application made of several APK files (one main and extra split packages) that are sitting on the android device. See "https://developer.android.com/studio/build/configure-apk-splits" on how to split apk to several files.

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

Parameters
remoteApkPaths : the remote apk file paths
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 if connection with device is lost and cannot be recovered.
UnsupportedOperationException if runtime permission is not supported by the platform on device.

installRemotePackages

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

Install an Android application made of several APK files (one main and extra split packages) that are sitting on the android device. See "https://developer.android.com/studio/build/configure-apk-splits" on how to split apk to several files.

Parameters
remoteApkPaths : the remote apk file paths
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 if connection with device is lost and cannot be recovered.
UnsupportedOperationException if runtime permission is not supported by the platform on device.

isMultiUserSupported

public abstract boolean isMultiUserSupported ()

Determines if multi user is supported.

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

isPackageInstalled

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

isWifiEnabled

public abstract boolean isWifiEnabled ()

Test if wifi is enabled.

Checks if wifi is enabled on device. Useful for asserting wifi status before tests that shouldn't run with wifi, e.g. mobile data tests.

Returns
boolean true if wifi is enabled. false if disabled
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

listDisplayIds

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

listUsers

public abstract  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
com.android.tradefed.device.DeviceNotAvailableException
DeviceRuntimeException
DeviceNotAvailableException

removeAdmin

public abstract 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 abstract void removeOwners ()

Remove all existing device profile owners with the best effort.

Throws
DeviceNotAvailableException

removeUser

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

stopUser

public abstract 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 abstract 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 abstract 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 abstract 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 abstract 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 if connection with device is lost and cannot be recovered.