to top
public interface

ITestDevice

com.android.tradefed.device.ITestDevice
Known Indirect Subclasses

Class Overview

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.MountPointInfo A simple struct class to store information about a single mountpoint  
enum ITestDevice.RecoveryMode  
Constants
int UNKNOWN_API_LEVEL Default value when API Level cannot be detected
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 void clearLogcat()
Deletes any accumulated logcat data.
abstract boolean connectToWifiNetwork(String wifiSsid, String wifiPsk)
Connects to a wifi network.
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.
abstract boolean disableNetworkMonitor()
Disables network monitoring on device.
abstract boolean disconnectFromWifi()
Disconnects from a wifi network.
abstract boolean doesFileExist(String deviceFilePath)
Helper method to determine if file on device exists.
abstract boolean enableAdbRoot()
Turns on adb root.
abstract boolean enableNetworkMonitor()
Enables network monitoring on device.
abstract boolean encryptDevice(boolean inplace)
Encrypts the device.
abstract String executeAdbCommand(String... commandArgs)
Helper method which executes a adb command as a system command.
abstract CommandResult executeFastbootCommand(String... commandArgs)
Helper method which executes a fastboot command as a system command.
abstract CommandResult executeLongFastbootCommand(String... commandArgs)
Helper method which executes a long running fastboot command as a system command.
abstract String executeShellCommand(String command)
Helper method which executes a adb shell command and returns output as a String.
abstract void executeShellCommand(String command, IShellOutputReceiver receiver, long maxTimeToOutputShellResponse, TimeUnit timeUnit, int retryAttempts)
Executes a adb shell command, with more parameters to control command behavior.
abstract void executeShellCommand(String command, IShellOutputReceiver receiver)
Executes the given adb shell command, retrying multiple times if command fails.
abstract void executeShellCommand(String command, IShellOutputReceiver receiver, int maxTimeToOutputShellResponse, int retryAttempts)
abstract CommandResult fastbootWipePartition(String partition)
Helper method which wipes a partition for the device.
abstract int getApiLevel()
Get the device API Level.
abstract PackageInfo getAppPackageInfo(String packageName)
Fetch information about a package installed on device.
abstract String getBasebandVersion()
Convenience method to get baseband (radio) version of this device.
abstract String getBootloaderVersion()
Convenience method to get the bootloader version of this device.
abstract InputStreamSource getBugreport()
Retrieves a bugreport from the device.
abstract String getBuildAlias()
Retrieve the alias of the build that the device is currently running.
abstract String getBuildFlavor()
Retrieve the build flavor for the device.
abstract String getBuildId()
Retrieve the build the device is currently running.
abstract String getBuildSigningKeys()
Returns the key type used to sign the device image

Typically Android devices may be signed with test-keys (like in AOSP) or release-keys (controlled by individual device manufacturers)

abstract String getDeviceClass()
Get the device class.
abstract TestDeviceState getDeviceState()
Get the device's state.
abstract InputStreamSource getEmulatorOutput()
Get the stream of emulator stdout and stderr
abstract long getExternalStoreFreeSpace()
Helper method to determine amount of free space on device external storage.
abstract String getFastbootProductType()
Convenience method to get the product type of this device when its in fastboot mode.
abstract String getFastbootProductVariant()
Convenience method to get the product type of this device when its in fastboot mode.
abstract IFileEntry getFileEntry(String path)
Retrieve a reference to a remote file on device.
abstract IDevice getIDevice()
Returns a reference to the associated ddmlib IDevice.
abstract Set<String> getInstalledPackageNames()
Fetch the application package names present on the device.
abstract String getIpAddress()
Gets the device's IP address.
abstract InputStreamSource getLogcat()
Grabs a snapshot stream of the logcat data.
abstract InputStreamSource getLogcat(int maxBytes)
Grabs a snapshot stream of the last maxBytes of captured logcat data.
abstract InputStreamSource getLogcatDump()
Get a dump of the current logcat for device.
abstract int getMaxNumberOfUsersSupported()
Get the maximum number of supported users.
abstract String getMountPoint(String mountName)
Returns a mount point.
abstract ITestDevice.MountPointInfo getMountPointInfo(String mountpoint)
Returns a ITestDevice.MountPointInfo corresponding to the specified mountpoint path, or null if that path has nothing mounted or otherwise does not appear in /proc/mounts as a mountpoint.
abstract List<ITestDevice.MountPointInfo> getMountPointInfo()
Returns a parsed version of the information in /proc/mounts on the device
abstract TestDeviceOptions getOptions()
Fetch the test options for the device.
abstract Integer getPrimaryUserId()
Returns the primary user id.
abstract String getProductType()
Convenience method to get the product type of this device.
abstract String getProductVariant()
Convenience method to get the product variant of this device.
abstract String getProperty(String name)
Retrieve the given property value from the device.
abstract String getPropertySync(String name)
This method is deprecated. use ERROR(/getProperty(String))
abstract ITestDevice.RecoveryMode getRecoveryMode()
Get the current recovery mode used for the device.
abstract InputStreamSource getScreenshot(String format)
Grabs a screenshot from the device.
abstract InputStreamSource getScreenshot()
Grabs a screenshot from the device.
abstract String getSerialNumber()
Convenience method to get serial number of this device.
abstract Set<String> getUninstallablePackageNames()
Fetch the application package names that can be uninstalled.
abstract boolean getUseFastbootErase()
Get whether to use fastboot erase or fastboot format to wipe a partition on the device.
abstract String installPackage(File packageFile, boolean reinstall, boolean grantPermissions, String... extraArgs)
Install an Android package on device.
abstract String installPackage(File packageFile, boolean reinstall, String... extraArgs)
Install an Android package on device.
abstract String installPackageForUser(File packageFile, boolean reinstall, int userId, String... extraArgs)
Install an Android package on device for a given user.
abstract String installPackageForUser(File packageFile, boolean reinstall, boolean grantPermissions, int userId, String... extraArgs)
Install an Android package on device for a given user.
abstract boolean isAdbRoot()
abstract boolean isAdbTcp()
abstract boolean isDeviceEncrypted()
Returns if the device is encrypted.
abstract boolean isEncryptionSupported()
Returns if encryption is supported on the device.
abstract boolean isMultiUserSupported()
Determines if multi user is supported.
abstract boolean isRuntimePermissionSupported()
Check whether platform on device supports runtime permission granting
abstract boolean isWifiEnabled()
Test if wifi is enabled.
abstract ArrayList<Integer> listUsers()
Gets the list of users on the device.
abstract void nonBlockingReboot()
Issues a command to reboot device and returns on command complete and when device is no longer visible to adb.
abstract void postBootSetup()
Perform instructions to configure device for testing that after every boot.
abstract File pullFile(String remoteFilePath)
Retrieves a file off device, stores it in a local temporary File, and returns that File.
abstract boolean pullFile(String remoteFilePath, File localFile)
Retrieves a file off device.
abstract File pullFileFromExternal(String remoteFilePath)
A convenience method to retrieve a file from the device's external storage, stores it in a local temporary File, and return a reference to that File.
abstract boolean pushDir(File localDir, String deviceFilePath)
Recursively push directory contents to device.
abstract boolean pushFile(File localFile, String deviceFilePath)
Push a file to device
abstract boolean pushString(String contents, String deviceFilePath)
Push file created from a string to device
abstract void reboot()
Reboots the device into adb mode.
abstract void rebootIntoBootloader()
Reboots the device into bootloader mode.
abstract void rebootIntoRecovery()
Reboots the device into adb recovery mode.
abstract void rebootUntilOnline()
An alternate to reboot() that only blocks until device is online ie visible to adb.
abstract void remountSystemWritable()
Make the system partition on the device writable.
abstract boolean removeUser(int userId)
Remove a given user from the device.
abstract boolean runInstrumentationTests(IRemoteAndroidTestRunner runner, Collection<ITestRunListener> listeners)
Runs instrumentation tests, and provides device recovery.
abstract boolean runInstrumentationTests(IRemoteAndroidTestRunner runner, ITestRunListener... listeners)
Convenience method for performing runInstrumentationTests(IRemoteAndroidTestRunner, Collection) with one or more listeners passed as parameters.
abstract boolean runInstrumentationTestsAsUser(IRemoteAndroidTestRunner runner, int userId, ITestRunListener... listeners)
abstract boolean runInstrumentationTestsAsUser(IRemoteAndroidTestRunner runner, int userId, Collection<ITestRunListener> listeners)
Same as runInstrumentationTests(IRemoteAndroidTestRunner, Collection) but runs the test for the given user.
abstract void setDate(Date date)
Sets the date on device

Note: setting date on device requires root

abstract void setOptions(TestDeviceOptions options)
Set the TestDeviceOptions for the device
abstract void setRecovery(IDeviceRecovery recovery)
Set the IDeviceRecovery to use for this device.
abstract void setRecoveryMode(ITestDevice.RecoveryMode mode)
Set the current recovery mode to use for the device.
abstract void setUseFastbootErase(boolean useFastbootErase)
Set whether to use fastboot erase or fastboot format to wipe a partition on the device.
abstract void startLogcat()
Start capturing logcat output from device in the background.
abstract boolean startUser(int userId)
Starts a given user in the background if it is currently stopped.
abstract void stopEmulatorOutput()
Close and delete the emulator output.
abstract void stopLogcat()
Stop capturing logcat output from device, and discard currently saved logcat data.
abstract void stopUser(int userId)
Stops a given user.
abstract String switchToAdbTcp()
Switch device to adb-over-tcp mode.
abstract boolean switchToAdbUsb()
Switch device to adb over usb mode.
abstract boolean syncFiles(File localFileDir, String deviceFilePath)
Incrementally syncs the contents of a local file directory to device.
abstract boolean unencryptDevice()
Unencrypts the device.
abstract String uninstallPackage(String packageName)
Uninstall an Android package from device.
abstract boolean unlockDevice()
Unlocks the device if the device is in an encrypted state.
abstract boolean waitForBootComplete(long timeOut)
Blocks until the device's boot complete flag is set.
abstract void waitForDeviceAvailable()
Waits for the device to be responsive and available for testing.
abstract void waitForDeviceAvailable(long waitTime)
Waits for the device to be responsive and available for testing.
abstract boolean waitForDeviceInRecovery(long waitTime)
Blocks for the device to be in the 'adb recovery' state (note this is distinct from IDeviceRecovery).
abstract boolean waitForDeviceNotAvailable(long waitTime)
Blocks for the device to be not available ie missing from adb
abstract void waitForDeviceOnline()
Blocks until device is visible via adb.
abstract void waitForDeviceOnline(long waitTime)
Blocks until device is visible via adb.
abstract boolean waitForDeviceShell(long waitTime)
Waits for device to be responsive to a basic adb shell command.

Constants

public static final int UNKNOWN_API_LEVEL

Default value when API Level cannot be detected

Constant Value: -1 (0xffffffff)

Public Methods

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.

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.

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.

public abstract void clearLogcat ()

Deletes any accumulated logcat data.

This is useful for cases when you want to ensure getLogcat() only returns log data produced after a certain point (such as after flashing a new device build, etc).

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 disconnectFromWifi() or 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.

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

public abstract int createUser (String name)

Create a user with a given name.

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

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.

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.

public abstract boolean doesFileExist (String deviceFilePath)

Helper method to determine if file on device exists.

Parameters
deviceFilePath String: the absolute path of file on device to check
Returns
boolean true if file exists, false otherwise.
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract boolean enableAdbRoot ()

Turns on adb root. If the "enable-root" setting is "false", will log a message and return without enabling root.

Enabling adb root may cause device to disconnect from adb. This method will block until device is available.

Returns
boolean true if successful.
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

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.

public abstract boolean encryptDevice (boolean inplace)

Encrypts the device.

Encrypting the device may be done inplace or with a wipe. Inplace encryption will not wipe any data on the device but normally takes a couple orders of magnitude longer than the wipe.

This method will reboot the device if it is not already encrypted and will block until device is online. Also, it will not decrypt the device after the reboot. Therefore, the device might not be fully booted and/or ready to be tested when this method returns.

Parameters
inplace boolean: if the encryption process should take inplace and the device should not be wiped.
Returns
boolean true if successful.
Throws
DeviceNotAvailableException if device is not available after reboot.
UnsupportedOperationException if encryption is not supported on the device.

public abstract String executeAdbCommand (String... commandArgs)

Helper method which executes a adb command as a system command.

executeShellCommand(String) should be used instead wherever possible, as that method provides better failure detection and performance.

Parameters
commandArgs String: the adb command and arguments to run
Returns
String the stdout from command. null if command failed to execute.
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract CommandResult executeFastbootCommand (String... commandArgs)

Helper method which executes a fastboot command as a system command.

Expected to be used when device is already in fastboot mode.

Parameters
commandArgs String: the fastboot command and arguments to run
Returns
CommandResult the CommandResult containing output of command
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract CommandResult executeLongFastbootCommand (String... commandArgs)

Helper method which executes a long running fastboot command as a system command.

Identical to executeFastbootCommand(String) except uses a longer timeout.

Parameters
commandArgs String: the fastboot command and arguments to run
Returns
CommandResult the CommandResult containing output of command
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract String executeShellCommand (String command)

Helper method which executes a adb shell command and returns output as a String.

Parameters
command String: the adb shell command to run
Returns
String the shell output
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract void executeShellCommand (String command, IShellOutputReceiver receiver, long maxTimeToOutputShellResponse, TimeUnit timeUnit, int retryAttempts)

Executes a adb shell command, with more parameters to control command behavior.

Parameters
command String: the adb shell command to run
receiver IShellOutputReceiver: the IShellOutputReceiver to direct shell output to.
maxTimeToOutputShellResponse long: the maximum amount of time during which the command is allowed to not output any response; unit as specified in timeUnit
timeUnit TimeUnit: unit for maxTimeToOutputShellResponse, see TimeUtil
retryAttempts int: the maximum number of times to retry command if it fails due to a exception. DeviceNotResponsiveException will be thrown if retryAttempts are performed without success.
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract void executeShellCommand (String command, IShellOutputReceiver receiver)

Executes the given adb shell command, retrying multiple times if command fails.

A simpler form of executeShellCommand(String, IShellOutputReceiver, int, int) with default values.

Parameters
command String: the adb shell command to run
receiver IShellOutputReceiver: the IShellOutputReceiver to direct shell output to.
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract void executeShellCommand (String command, IShellOutputReceiver receiver, int maxTimeToOutputShellResponse, int retryAttempts)

This method is deprecated.
Use executeShellCommand(String, IShellOutputReceiver, long, TimeUnit, int)

Executes a adb shell command, with more parameters to control command behavior.

Parameters
command String: the adb shell command to run
receiver IShellOutputReceiver: the IShellOutputReceiver to direct shell output to.
maxTimeToOutputShellResponse int: the maximum amount of time during which the command is allowed to not output any response.
retryAttempts int: the maximum number of times to retry command if it fails due to a exception. DeviceNotResponsiveException will be thrown if retryAttempts are performed without success.
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract CommandResult fastbootWipePartition (String partition)

Helper method which wipes a partition for the device.

If getUseFastbootErase() is true, then fastboot erase will be used to wipe the partition. The device must then create a filesystem the next time the device boots. Otherwise, fastboot format is used which will create a new filesystem on the device.

Expected to be used when device is already in fastboot mode.

Parameters
partition String: the partition to wipe
Returns
CommandResult the CommandResult containing output of command
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract int getApiLevel ()

Get the device API Level. Defaults to UNKNOWN_API_LEVEL.

Returns
int an integer indicating the API Level of device
Throws
DeviceNotAvailableException

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

public abstract String getBasebandVersion ()

Convenience method to get baseband (radio) version of this device. Getting the radio version is device specific, so it might not return the correct information for all devices. This method relies on the gsm.version.baseband propery to return the correct version information. This is not accurate for some CDMA devices and the version returned here might not match the version reported from fastboot and might not return the version for the CDMA radio. TL;DR this method only reports accurate version if the gsm.version.baseband property is the same as the version returned by fastboot getvar version-baseband.

Returns
String the String baseband version or null if it cannot be determined (device has no radio or version string cannot be read)
Throws
DeviceNotAvailableException if the connection with the device is lost and cannot be recovered.

public abstract String getBootloaderVersion ()

Convenience method to get the bootloader version of this device.

Will attempt to retrieve bootloader version from the device's current state. (ie if device is in fastboot mode, it will attempt to retrieve version from fastboot)

Returns
String the String bootloader version or null if it cannot be found
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract InputStreamSource getBugreport ()

Retrieves a bugreport from the device.

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

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

public abstract String getBuildAlias ()

Retrieve the alias of the build that the device is currently running.

Build alias is usually a more readable string than build id (typically a number for Nexus builds). For example, final Android 4.2 release has build alias JDQ39, and build id 573038

Returns
String the build alias or fall back to build id if it could not be retrieved
Throws
DeviceNotAvailableException

public abstract String getBuildFlavor ()

Retrieve the build flavor for the device.

Returns
String the build flavor or null if it could not be retrieved
Throws
DeviceNotAvailableException

public abstract String getBuildId ()

Retrieve the build the device is currently running.

Returns
String the build id or UNKNOWN_BUILD_ID if it could not be retrieved
Throws
DeviceNotAvailableException

public abstract String getBuildSigningKeys ()

Returns the key type used to sign the device image

Typically Android devices may be signed with test-keys (like in AOSP) or release-keys (controlled by individual device manufacturers)

Returns
String
Throws
DeviceNotAvailableException

public abstract String getDeviceClass ()

Get the device class.

Returns
String the String device class.

public abstract TestDeviceState getDeviceState ()

Get the device's state.

Returns
TestDeviceState

public abstract InputStreamSource getEmulatorOutput ()

Get the stream of emulator stdout and stderr

Returns
InputStreamSource emulator output

public abstract long getExternalStoreFreeSpace ()

Helper method to determine amount of free space on device external storage.

Returns
long the amount of free space in KB
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract String getFastbootProductType ()

Convenience method to get the product type of this device when its in fastboot mode.

This method should only be used if device should be in fastboot. Its a bit safer variant than the generic getProductType() method in this case, because ITestDevice will know to recover device into fastboot if device is in incorrect state or is unresponsive.

Returns
String the String product type name or null if it cannot be determined
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract String getFastbootProductVariant ()

Convenience method to get the product type of this device when its in fastboot mode.

This method should only be used if device should be in fastboot. Its a bit safer variant than the generic getProductType() method in this case, because ITestDevice will know to recover device into fastboot if device is in incorrect state or is unresponsive.

Returns
String the String product type name or null if it cannot be determined
Throws
DeviceNotAvailableException if connection with device is lost and cannot be recovered.

public abstract IFileEntry getFileEntry (String path)

Retrieve a reference to a remote file on device.

Parameters
path String: the file path to retrieve. Can be an absolute path or path relative to '/'. (ie both "/system" and "system" syntax is supported)
Returns
IFileEntry the IFileEntry or null if file at given path cannot be found
Throws
DeviceNotAvailableException

public abstract IDevice getIDevice ()

Returns a reference to the associated ddmlib IDevice.

A new IDevice may be allocated by DDMS each time the device disconnects and reconnects from adb. Thus callers should not keep a reference to the IDevice, because that reference may become stale.

Returns
IDevice the IDevice

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

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.

public abstract InputStreamSource getLogcat ()

Grabs a snapshot stream of the logcat data.

Works in two modes:

  • If the logcat is currently being captured in the background, will return up to getMaxLogcatDataSize() bytes of the current contents of the background logcat capture
  • Otherwise, will return a static dump of the logcat data if device is currently responding

    Returns
    InputStreamSource
  • public abstract InputStreamSource getLogcat (int maxBytes)

    Grabs a snapshot stream of the last maxBytes of captured logcat data.

    Useful for cases when you want to capture frequent snapshots of the captured logcat data without incurring the potentially big disk space penalty of getting the entire getLogcat() snapshot.

    Parameters
    maxBytes int: the maximum amount of data to return. Should be an amount that can comfortably fit in memory
    Returns
    InputStreamSource

    public abstract InputStreamSource getLogcatDump ()

    Get a dump of the current logcat for device. Unlike getLogcat(), this method will always return a static dump of the logcat.

    Has the disadvantage that nothing will be returned if device is not reachable.

    Returns
    InputStreamSource a InputStreamSource of the logcat data. An empty stream is returned if fail to capture logcat data.

    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

    public abstract String getMountPoint (String mountName)

    Returns a mount point.

    Queries the device directly if the cached info in IDevice is not available.

    TODO: move this behavior to getMountPoint(String)

    Parameters
    mountName String: the name of the mount point
    Returns
    String the mount point or null

    public abstract ITestDevice.MountPointInfo getMountPointInfo (String mountpoint)

    Returns a ITestDevice.MountPointInfo corresponding to the specified mountpoint path, or null if that path has nothing mounted or otherwise does not appear in /proc/mounts as a mountpoint.

    Parameters
    mountpoint String
    Returns
    ITestDevice.MountPointInfo A List of ITestDevice.MountPointInfo containing the information in "/proc/mounts"
    Throws
    DeviceNotAvailableException

    public abstract List<ITestDevice.MountPointInfo> getMountPointInfo ()

    Returns a parsed version of the information in /proc/mounts on the device

    Returns
    List<ITestDevice.MountPointInfo> A List of ITestDevice.MountPointInfo containing the information in "/proc/mounts"
    Throws
    DeviceNotAvailableException

    public abstract TestDeviceOptions getOptions ()

    Fetch the test options for the device.

    Returns
    TestDeviceOptions TestDeviceOptions related to the device under test.

    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
    DeviceNotAvailableException

    public abstract String getProductType ()

    Convenience method to get the product type of this device.

    This method will work if device is in either adb or fastboot mode.

    Returns
    String the String product type name. Will not be null
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered, or if product type can not be determined

    public abstract String getProductVariant ()

    Convenience method to get the product variant of this device.

    This method will work if device is in either adb or fastboot mode.

    Returns
    String the String product variant name or null if it cannot be determined
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract String getProperty (String name)

    Retrieve the given property value from the device.

    Parameters
    name String: the property name
    Returns
    String the property value or null if it does not exist
    Throws
    DeviceNotAvailableException

    public abstract String getPropertySync (String name)

    This method is deprecated.
    use ERROR(/getProperty(String))

    Retrieve the given property value from the device.

    Parameters
    name String: the property name
    Returns
    String the property value or null if it does not exist
    Throws
    DeviceNotAvailableException
    DeviceNotAvailableException

    public abstract ITestDevice.RecoveryMode getRecoveryMode ()

    Get the current recovery mode used for the device.

    Returns
    ITestDevice.RecoveryMode the current recovery mode used for the device.

    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

    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

    public abstract String getSerialNumber ()

    Convenience method to get serial number of this device.

    Returns
    String the String serial number

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

    public abstract boolean getUseFastbootErase ()

    Get whether to use fastboot erase or fastboot format to wipe a partition on the device.

    Returns
    boolean true if fastboot erase will be used or false if fastboot format will be used.

    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.

    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.

    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.

    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.

    public abstract boolean isAdbRoot ()

    Returns
    boolean true if device currently has adb root, false otherwise.
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract boolean isAdbTcp ()

    Returns
    boolean true if device is connected to adb-over-tcp, false otherwise.

    public abstract boolean isDeviceEncrypted ()

    Returns if the device is encrypted.

    Returns
    boolean true if the device is encrypted.
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract boolean isEncryptionSupported ()

    Returns if encryption is supported on the device.

    Returns
    boolean true if the device supports encryption.
    Throws
    DeviceNotAvailableException

    public abstract boolean isMultiUserSupported ()

    Determines if multi user is supported.

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

    public abstract boolean isRuntimePermissionSupported ()

    Check whether platform on device supports runtime permission granting

    Returns
    boolean
    Throws
    DeviceNotAvailableException

    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.

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

    public abstract void nonBlockingReboot ()

    Issues a command to reboot device and returns on command complete and when device is no longer visible to adb.

    Throws
    DeviceNotAvailableException

    public abstract void postBootSetup ()

    Perform instructions to configure device for testing that after every boot.

    Should be called after device is fully booted/available

    In normal circumstances this method doesn't need to be called explicitly, as implementations should perform these steps automatically when performing a reboot.

    Where it may need to be called is when device reboots due to other events (eg when a fastboot update command has completed)

    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract File pullFile (String remoteFilePath)

    Retrieves a file off device, stores it in a local temporary File, and returns that File.

    Parameters
    remoteFilePath String: the absolute path to file on device.
    Returns
    File A File containing the contents of the device file, or null if the copy failed for any reason (including problems with the host filesystem)
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract boolean pullFile (String remoteFilePath, File localFile)

    Retrieves a file off device.

    Parameters
    remoteFilePath String: the absolute path to file on device.
    localFile File: the local file to store contents in. If non-empty, contents will be replaced.
    Returns
    boolean true if file was retrieved successfully. false otherwise.
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract File pullFileFromExternal (String remoteFilePath)

    A convenience method to retrieve a file from the device's external storage, stores it in a local temporary File, and return a reference to that File.

    Parameters
    remoteFilePath String: the path to file on device, relative to the device's external storage mountpoint
    Returns
    File A File containing the contents of the device file, or null if the copy failed for any reason (including problems with the host filesystem)
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract boolean pushDir (File localDir, String deviceFilePath)

    Recursively push directory contents to device.

    Parameters
    localDir File: the local directory to push
    deviceFilePath String: the absolute file path of the remote destination
    Returns
    boolean true if file was pushed successfully. false otherwise.
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract boolean pushFile (File localFile, String deviceFilePath)

    Push a file to device

    Parameters
    localFile File: the local file to push
    deviceFilePath String: the remote destination absolute file path
    Returns
    boolean true if file was pushed successfully. false otherwise.
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract boolean pushString (String contents, String deviceFilePath)

    Push file created from a string to device

    Parameters
    contents String: the contents of the file to push
    deviceFilePath String: the remote destination absolute file path
    Returns
    boolean true if string was pushed successfully. false otherwise.
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract void reboot ()

    Reboots the device into adb mode.

    Blocks until device becomes available.

    Throws
    DeviceNotAvailableException if device is not available after reboot

    public abstract void rebootIntoBootloader ()

    Reboots the device into bootloader mode.

    Blocks until device is in bootloader mode.

    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract void rebootIntoRecovery ()

    Reboots the device into adb recovery mode.

    Blocks until device enters recovery

    Throws
    DeviceNotAvailableException if device is not available after reboot

    public abstract void rebootUntilOnline ()

    An alternate to reboot() that only blocks until device is online ie visible to adb.

    Throws
    DeviceNotAvailableException if device is not available after reboot

    public abstract void remountSystemWritable ()

    Make the system partition on the device writable. May reboot the device.

    Throws
    DeviceNotAvailableException

    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 succesful in removing the user, false otherwise.
    Throws
    DeviceNotAvailableException

    public abstract boolean runInstrumentationTests (IRemoteAndroidTestRunner runner, Collection<ITestRunListener> listeners)

    Runs instrumentation tests, and provides device recovery.

    If connection with device is lost before test run completes, and recovery succeeds, all listeners will be informed of testRunFailed and "false" will be returned. The test command will not be rerun. It is left to callers to retry if necessary.

    If connection with device is lost before test run completes, and recovery fails, all listeners will be informed of testRunFailed and DeviceNotAvailableException will be thrown.

    Parameters
    runner IRemoteAndroidTestRunner: the IRemoteAndroidTestRunner which runs the tests
    listeners Collection: the test result listeners
    Returns
    boolean true if test command completed. false if it failed to complete due to device communication exception, but recovery succeeded
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered. ie test command failed to complete and recovery failed.

    public abstract boolean runInstrumentationTests (IRemoteAndroidTestRunner runner, ITestRunListener... listeners)

    Convenience method for performing runInstrumentationTests(IRemoteAndroidTestRunner, Collection) with one or more listeners passed as parameters.

    Parameters
    runner IRemoteAndroidTestRunner: the IRemoteAndroidTestRunner which runs the tests
    listeners ITestRunListener: the test result listener(s)
    Returns
    boolean true if test command completed. false if it failed to complete, but recovery succeeded
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered. ie test command failed to complete and recovery failed.

    public abstract boolean runInstrumentationTestsAsUser (IRemoteAndroidTestRunner runner, int userId, ITestRunListener... listeners)

    Same as runInstrumentationTests(IRemoteAndroidTestRunner, ITestRunListener) but runs the test for a given user.

    Parameters
    runner IRemoteAndroidTestRunner
    userId int
    listeners ITestRunListener
    Returns
    boolean
    Throws
    DeviceNotAvailableException

    public abstract boolean runInstrumentationTestsAsUser (IRemoteAndroidTestRunner runner, int userId, Collection<ITestRunListener> listeners)

    Same as runInstrumentationTests(IRemoteAndroidTestRunner, Collection) but runs the test for the given user.

    Parameters
    runner IRemoteAndroidTestRunner
    userId int
    listeners Collection
    Returns
    boolean
    Throws
    DeviceNotAvailableException

    public abstract void setDate (Date date)

    Sets the date on device

    Note: setting date on device requires root

    Parameters
    date Date: specify a particular date; will use host date if null
    Throws
    DeviceNotAvailableException

    public abstract void setOptions (TestDeviceOptions options)

    Set the TestDeviceOptions for the device

    Parameters
    options TestDeviceOptions

    public abstract void setRecovery (IDeviceRecovery recovery)

    Set the IDeviceRecovery to use for this device. Should be set when device is first allocated.

    Parameters
    recovery IDeviceRecovery: the IDeviceRecovery

    public abstract void setRecoveryMode (ITestDevice.RecoveryMode mode)

    Set the current recovery mode to use for the device.

    Used to control what recovery method to use when a device communication problem is encountered. Its recommended to only use this method sparingly when needed (for example, when framework is down, etc

    Parameters
    mode ITestDevice.RecoveryMode: whether 'recover till online only' mode should be on or not.

    public abstract void setUseFastbootErase (boolean useFastbootErase)

    Set whether to use fastboot erase or fastboot format to wipe a partition on the device.

    Parameters
    useFastbootErase boolean: true if fastboot erase should be used or false if fastboot format should be used.

    public abstract void startLogcat ()

    Start capturing logcat output from device in the background.

    Will have no effect if logcat output is already being captured. Data can be later retrieved via getLogcat.

    When the device is no longer in use, stopLogcat() must be called.

    startLogcat() and stopLogcat() do not normally need to be called when within a TF invocation context, as the TF framework will start and stop logcat.

    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 succesfully started in the background.
    Throws
    DeviceNotAvailableException

    public abstract void stopEmulatorOutput ()

    Close and delete the emulator output.

    public abstract void stopLogcat ()

    Stop capturing logcat output from device, and discard currently saved logcat data.

    Will have no effect if logcat output is not being captured.

    public abstract void stopUser (int userId)

    Stops a given user. If the user is already stopped, this method is a NOOP.

    Parameters
    userId int: of the user to stop.
    Throws
    DeviceNotAvailableException

    public abstract String switchToAdbTcp ()

    Switch device to adb-over-tcp mode.

    Returns
    String the tcp serial number or null if device could not be switched
    Throws
    DeviceNotAvailableException

    public abstract boolean switchToAdbUsb ()

    Switch device to adb over usb mode.

    Returns
    boolean true if switch was successful, false otherwise.
    Throws
    DeviceNotAvailableException

    public abstract boolean syncFiles (File localFileDir, String deviceFilePath)

    Incrementally syncs the contents of a local file directory to device.

    Decides which files to push by comparing timestamps of local files with their remote equivalents. Only 'newer' or non-existent files will be pushed to device. Thus overhead should be relatively small if file set on device is already up to date.

    Hidden files (with names starting with ".") will be ignored.

    Example usage: syncFiles("/tmp/files", "/sdcard") will created a /sdcard/files directory if it doesn't already exist, and recursively push the /tmp/files contents to /sdcard/files.

    Parameters
    localFileDir File: the local file directory containing files to recursively push.
    deviceFilePath String: the remote destination absolute file path root. All directories in thos file path must be readable. ie pushing to /data/local/tmp when adb is not root will fail
    Returns
    boolean true if files were synced successfully. false otherwise.
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract boolean unencryptDevice ()

    Unencrypts the device.

    Unencrypting the device may cause device to be wiped and may reboot device. This method will block until device is available and ready for testing. Requires fastboot inorder to wipe the userdata partition.

    Returns
    boolean true if successful.
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.
    UnsupportedOperationException if encryption is not supported on the device.

    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.

    public abstract boolean unlockDevice ()

    Unlocks the device if the device is in an encrypted state.

    This method may restart the framework but will not call postBootSetup(). Therefore, the device might not be fully ready to be tested when this method returns.

    Returns
    boolean true if successful or if the device is unencrypted.
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.
    UnsupportedOperationException if encryption is not supported on the device.

    public abstract boolean waitForBootComplete (long timeOut)

    Blocks until the device's boot complete flag is set.

    Parameters
    timeOut long: time in msecs to wait for the flag to be set
    Returns
    boolean true if device's boot complete flag is set within the timeout
    Throws
    DeviceNotAvailableException

    public abstract void waitForDeviceAvailable ()

    Waits for the device to be responsive and available for testing. Uses default timeout.

    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract void waitForDeviceAvailable (long waitTime)

    Waits for the device to be responsive and available for testing.

    Parameters
    waitTime long: the time in ms to wait
    Throws
    DeviceNotAvailableException if device is still unresponsive after waitTime expires.

    public abstract boolean waitForDeviceInRecovery (long waitTime)

    Blocks for the device to be in the 'adb recovery' state (note this is distinct from IDeviceRecovery).

    Parameters
    waitTime long: the time in ms to wait
    Returns
    boolean true if device boots into recovery before time expires. false otherwise

    public abstract boolean waitForDeviceNotAvailable (long waitTime)

    Blocks for the device to be not available ie missing from adb

    Parameters
    waitTime long: the time in ms to wait
    Returns
    boolean true if device becomes not available before time expires. false otherwise

    public abstract void waitForDeviceOnline ()

    Blocks until device is visible via adb. Uses default timeout

    Note the device may not necessarily be responsive to commands on completion. Use waitForDeviceAvailable() instead.

    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract void waitForDeviceOnline (long waitTime)

    Blocks until device is visible via adb.

    Note the device may not necessarily be responsive to commands on completion. Use waitForDeviceAvailable() instead.

    Parameters
    waitTime long: the time in ms to wait
    Throws
    DeviceNotAvailableException if connection with device is lost and cannot be recovered.

    public abstract boolean waitForDeviceShell (long waitTime)

    Waits for device to be responsive to a basic adb shell command.

    Parameters
    waitTime long: the time in ms to wait
    Returns
    boolean true if device becomes responsive before waitTime elapses.