null if it does not exist
* @throws DeviceNotAvailableException
*/
public String getProperty(String name) throws DeviceNotAvailableException;
/**
* Returns integer value of the given property from the device.
*
* @param name the property name
* @param defaultValue default value to return if property is empty or doesn't exist.
* @return the property value or {@code defaultValue} if the property is empty, doesn't exist,
* or doesn't have an integer value.
*/
public long getIntProperty(String name, long defaultValue) throws DeviceNotAvailableException;
/**
* Returns boolean value of the given property.
*
* @param name the property name
* @param defaultValue default value to return if property is empty or doesn't exist.
* @return {@code true} if the property has value {@code "1"}, {@code "y"}, {@code "yes"},
* {@code "on"}, or {@code "true"}, {@code false} if the property has value of {@code "0"},
* {@code "n"}, {@code "no"}, {@code "off"}, {@code "false"}, or {@code defaultValue}
* otherwise.
*/
public boolean getBooleanProperty(String name, boolean defaultValue)
throws DeviceNotAvailableException;
/**
* Sets the given property value on the device. Requires adb root is true.
*
* @param propKey The key targeted to be set.
* @param propValue The property value to be set.
* @return returns True if the setprop command was successful, False otherwise.
* @throws DeviceNotAvailableException
*/
public boolean setProperty(String propKey, String propValue) throws DeviceNotAvailableException;
/**
* Retrieve the given fastboot variable value from the device.
*
* @param variableName the variable name
* @return the property value or null if it does not exist
* @throws DeviceNotAvailableException, UnsupportedOperationException
*/
public String getFastbootVariable(String variableName)
throws DeviceNotAvailableException, UnsupportedOperationException;
/**
* 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)
*
* @return the {@link String} bootloader version or null if it cannot be found
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public String getBootloaderVersion() throws DeviceNotAvailableException;
/**
* 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.
*
* @return the {@link 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 String getBasebandVersion() throws DeviceNotAvailableException;
/**
* Convenience method to get the product type of this device.
*
* This method will work if device is in either adb or fastboot mode.
*
* @return the {@link 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 String getProductType() throws DeviceNotAvailableException;
/**
* Convenience method to get the product variant of this device.
*
* This method will work if device is in either adb or fastboot mode.
*
* @return the {@link String} product variant name or null if it cannot be
* determined
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public String getProductVariant() throws DeviceNotAvailableException;
/**
* 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 {@link #getProductType()} method in this case, because ITestDevice
* will know to recover device into fastboot if device is in incorrect state or is
* unresponsive.
*
* @return the {@link String} product type name or null if it cannot be determined
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public String getFastbootProductType() throws DeviceNotAvailableException;
/**
* 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 {@link #getProductType()} method in this case, because ITestDevice
* will know to recover device into fastboot if device is in incorrect state or is
* unresponsive.
*
* @return the {@link String} product type name or null if it cannot be determined
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public String getFastbootProductVariant() throws DeviceNotAvailableException;
/**
* 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 * @return the build alias or fall back to build id if it could not be retrieved * @throws DeviceNotAvailableException */ public String getBuildAlias() throws DeviceNotAvailableException; /** * Retrieve the build the device is currently running. * * @return the build id or {@link IBuildInfo#UNKNOWN_BUILD_ID} if it could not be retrieved * @throws DeviceNotAvailableException */ public String getBuildId() throws DeviceNotAvailableException; /** * Retrieve the build flavor for the device. * * @return the build flavor or null if it could not be retrieved * @throws DeviceNotAvailableException */ public String getBuildFlavor() throws DeviceNotAvailableException; /** * Executes the given adb shell command, retrying multiple times if command fails. *
* A simpler form of * {@link #executeShellCommand(String, IShellOutputReceiver, long, TimeUnit, int)} with * default values. * * @param command the adb shell command to run * @param receiver the {@link IShellOutputReceiver} to direct shell output to. * @throws DeviceNotAvailableException if connection with device is lost and cannot be * recovered. */ public void executeShellCommand(String command, IShellOutputReceiver receiver) throws DeviceNotAvailableException; /** * Executes a adb shell command, with more parameters to control command behavior. * * @see #executeShellCommand(String, IShellOutputReceiver) * @param command the adb shell command to run * @param receiver the {@link IShellOutputReceiver} to direct shell output to. * @param maxTimeToOutputShellResponse the maximum amount of time during which the command is * allowed to not output any response; unit as specified intimeUnit
* @param timeUnit unit for maxTimeToOutputShellResponse
* @param retryAttempts 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.
* @see TimeUtil
*/
public void executeShellCommand(String command, IShellOutputReceiver receiver,
long maxTimeToOutputShellResponse, TimeUnit timeUnit, int retryAttempts)
throws DeviceNotAvailableException;
/**
* Executes a adb shell command, with more parameters to control command behavior.
*
* @see #executeShellCommand(String, IShellOutputReceiver)
* @param command the adb shell command to run
* @param receiver the {@link IShellOutputReceiver} to direct shell output to.
* @param maxTimeoutForCommand the maximum timeout for the command to complete; unit as
* specified in timeUnit
* @param maxTimeToOutputShellResponse the maximum amount of time during which the command is
* allowed to not output any response; unit as specified in timeUnit
* @param timeUnit unit for maxTimeToOutputShellResponse
* @param retryAttempts 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.
* @see TimeUtil
*/
public void executeShellCommand(
String command,
IShellOutputReceiver receiver,
long maxTimeoutForCommand,
long maxTimeToOutputShellResponse,
TimeUnit timeUnit,
int retryAttempts)
throws DeviceNotAvailableException;
/**
* Helper method which executes a adb shell command and returns output as a {@link String}.
*
* @param command the adb shell command to run
* @return the shell output
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public String executeShellCommand(String command) throws DeviceNotAvailableException;
/**
* Helper method which executes a adb shell command and returns the results as a {@link
* CommandResult} properly populated with the command status output, stdout and stderr.
*
* @param command The command that should be run.
* @return The result in {@link CommandResult}.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public CommandResult executeShellV2Command(String command) throws DeviceNotAvailableException;
/**
* Helper method which executes a adb shell command and returns the results as a {@link
* CommandResult} properly populated with the command status output, stdout and stderr.
*
* @param command The command that should be run.
* @param receiver the {@link IShellOutputReceiver} to direct shell output to.
* @return The result in {@link CommandResult}.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public CommandResult executeShellV2Command(String command, IShellOutputReceiver receiver)
throws DeviceNotAvailableException;
/**
* Helper method which executes an adb shell command and returns the results as a {@link
* CommandResult} properly populated with the command status output, stdout and stderr.
*
* @param command The command that should be run.
* @param pipeAsInput A {@link File} that will be piped as input to the command, or null.
* @return The result in {@link CommandResult}.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public CommandResult executeShellV2Command(String command, File pipeAsInput)
throws DeviceNotAvailableException;
/**
* Helper method which executes an adb shell command and returns the results as a {@link
* CommandResult} properly populated with the command status output and stderr. stdout is
* directed to the specified stream.
*
* @param command The command that should be run.
* @param pipeToOutput {@link OutputStream} where the std output will be redirected, or null.
* @return The result in {@link CommandResult}.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public CommandResult executeShellV2Command(String command, OutputStream pipeToOutput)
throws DeviceNotAvailableException;
/**
* Executes a adb shell command, with more parameters to control command behavior.
*
* @see #executeShellV2Command(String)
* @param command the adb shell command to run
* @param maxTimeoutForCommand the maximum timeout for the command to complete; unit as
* specified in timeUnit
* @param timeUnit unit for maxTimeToOutputShellResponse
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
* @see TimeUtil
*/
public CommandResult executeShellV2Command(
String command, final long maxTimeoutForCommand, final TimeUnit timeUnit)
throws DeviceNotAvailableException;
/**
* Executes a adb shell command, with more parameters to control command behavior.
*
* @see #executeShellV2Command(String)
* @param command the adb shell command to run
* @param maxTimeoutForCommand the maximum timeout for the command to complete; unit as
* specified in timeUnit
* @param timeUnit unit for maxTimeToOutputShellResponse
* @param retryAttempts 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.
* @see TimeUtil
*/
public CommandResult executeShellV2Command(
String command,
final long maxTimeoutForCommand,
final TimeUnit timeUnit,
int retryAttempts)
throws DeviceNotAvailableException;
/**
* Executes a adb shell command, with more parameters to control command behavior.
*
* @see #executeShellV2Command(String)
* @param command the adb shell command to run
* @param pipeAsInput A {@link File} that will be piped as input to the command, or null.
* @param pipeToOutput {@link OutputStream} where the std output will be redirected, or null.
* @param maxTimeoutForCommand the maximum timeout for the command to complete; unit as
* specified in timeUnit
* @param timeUnit unit for maxTimeToOutputShellResponse
* @param retryAttempts 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.
* @see TimeUtil
*/
public CommandResult executeShellV2Command(
String command,
File pipeAsInput,
OutputStream pipeToOutput,
final long maxTimeoutForCommand,
final TimeUnit timeUnit,
int retryAttempts)
throws DeviceNotAvailableException;
/**
* Executes a adb shell command, with more parameters to control command behavior.
*
* @see #executeShellV2Command(String)
* @param command the adb shell command to run
* @param pipeAsInput A {@link File} that will be piped as input to the command, or null.
* @param pipeToOutput {@link OutputStream} where the std output will be redirected, or null.
* @param pipeToError {@link OutputStream} where the std error will be redirected, or null.
* @param maxTimeoutForCommand the maximum timeout for the command to complete; unit as
* specified in timeUnit
* @param timeUnit unit for maxTimeToOutputShellResponse
* @param retryAttempts 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.
* @see TimeUtil
*/
public CommandResult executeShellV2Command(
String command,
File pipeAsInput,
OutputStream pipeToOutput,
OutputStream pipeToError,
final long maxTimeoutForCommand,
final TimeUnit timeUnit,
int retryAttempts)
throws DeviceNotAvailableException;
/**
* Helper method which executes a adb command as a system command.
*
* {@link #executeShellCommand(String)} should be used instead wherever possible, as that
* method provides better failure detection and performance.
*
* @param commandArgs the adb command and arguments to run
* @return the stdout from command. null if command failed to execute.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public String executeAdbCommand(String... commandArgs) throws DeviceNotAvailableException;
/**
* Helper method which executes a adb command as a system command with a specified timeout.
*
* {@link #executeShellCommand(String)} should be used instead wherever possible, as that
* method provides better failure detection and performance.
*
* @param timeout the time in milliseconds before the device is considered unresponsive, 0L for
* no timeout
* @param commandArgs the adb command and arguments to run
* @return the stdout from command. null if command failed to execute.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public String executeAdbCommand(long timeout, String... commandArgs)
throws DeviceNotAvailableException;
/**
* Helper method which executes a adb command as a system command with a specified timeout.
*
*
{@link #executeShellCommand(String)} should be used instead wherever possible, as that
* method provides better failure detection and performance.
*
* @param timeout the time in milliseconds before the device is considered unresponsive, 0L for
* no timeout
* @param envMap environment to set for the command
* @param commandArgs the adb command and arguments to run
* @return the stdout from command. {@link #executeShellCommand(String)} should be used instead wherever possible, as that
* method provides better failure detection and performance.
*
* @param commandArgs the adb command and arguments to run
* @return the CommandResult containing output of command.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public CommandResult executeAdbV2Command(String... commandArgs)
throws DeviceNotAvailableException;
/**
* Helper method which executes a adb command as a system command with a specified timeout.
*
* {@link #executeShellCommand(String)} should be used instead wherever possible, as that
* method provides better failure detection and performance.
*
* @param timeout the time in milliseconds before the device is considered unresponsive, 0L for
* no timeout
* @param commandArgs the adb command and arguments to run
* @return the CommandResult containing output of command.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public CommandResult executeAdbV2Command(long timeout, String... commandArgs)
throws DeviceNotAvailableException;
/**
* Helper method which executes a adb command as a system command with a specified timeout.
*
* {@link #executeShellCommand(String)} should be used instead wherever possible, as that
* method provides better failure detection and performance.
*
* @param timeout the time in milliseconds before the device is considered unresponsive, 0L for
* no timeout
* @param envMap environment to set for the command
* @param commandArgs the adb command and arguments to run
* @return the CommandResult containing output of command.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public CommandResult executeAdbV2Command(
long timeout, Map {@link #executeShellCommand(String)} should be used instead wherever possible, as that
* method provides better failure detection and performance.
*
* @param timeout the time in milliseconds before the device is considered unresponsive, 0L for
* no timeout
* @param envMap environment to set for the command
* @param retryAttempts 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.
* @param commandArgs the adb command and arguments to run
* @return the CommandResult containing output of command.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public CommandResult executeAdbV2Command(
long timeout, Map Expected to be used when device is already in fastboot mode.
*
* @param commandArgs the fastboot command and arguments to run
* @return the CommandResult containing output of command
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public CommandResult executeFastbootCommand(String... commandArgs)
throws DeviceNotAvailableException;
/**
* Helper method which executes a fastboot command as a system command.
* Identical to {@link #executeFastbootCommand(String...)} except uses a longer timeout.
*
* @param envVarMap the system environment variables that the fastboot command run with
* @param commandArgs the fastboot command and arguments to run
* @return the CommandResult containing output of command
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public CommandResult executeLongFastbootCommand(
Map 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.
*
* @param runner the {@link IRemoteAndroidTestRunner} which runs the tests
* @param listeners the test result listeners
* @return Works in two modes:
* 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 {@link
* #getLogcat()} snapshot.
*
* @param maxBytes the maximum amount of data to return. Should be an amount that can
* comfortably fit in memory
*/
@MustBeClosed
public InputStreamSource getLogcat(int maxBytes);
/**
* Grabs a snapshot stream of captured logcat data starting the date provided. The time on the
* device should be used {@link #getDeviceDate}.
*
*
*
* @param date in millisecond since epoch format of when to start the snapshot until present.
* (can be be obtained using 'date +%s')
*/
@MustBeClosed
public InputStreamSource getLogcatSince(long date);
/**
* Get a dump of the current logcat for device. Unlike {@link #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.
*
* @return a {@link InputStreamSource} of the logcat data. An empty stream is returned if fail
* to capture logcat data.
*/
@MustBeClosed
public InputStreamSource getLogcatDump();
/**
* Perform instructions to configure device for testing that after every boot.
* Blocks until device becomes available.
*
* Last reboot reason can be obtained by querying {@code sys.boot.reason} propety.
*
* @param reason a reason for this reboot, or {@code null} if no reason is specified.
* @throws DeviceNotAvailableException if device is not available after reboot
*/
public void reboot(@Nullable String reason) throws DeviceNotAvailableException;
/**
* Reboots the device into fastbootd mode.
*
* Blocks until device is in fastbootd mode.
*
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public void rebootIntoFastbootd() throws DeviceNotAvailableException;
/**
* Reboots only userspace part of device.
*
* Blocks until device becomes available.
*
* WARNING. Userspace reboot is currently under active development, use it on your own risk.
*
* @throws DeviceNotAvailableException if device is not available after reboot
*/
// TODO(ioffe): link to docs around userspace reboot when they are available.
public void rebootUserspace() throws DeviceNotAvailableException;
/**
* Reboots the device into adb recovery mode.
* Blocks until device enters sideload mode
*
* @throws DeviceNotAvailableException if device is not in sideload after reboot
*/
public void rebootIntoSideload() throws DeviceNotAvailableException;
/**
* Reboots the device into adb sideload mode (note that this is a special mode under recovery)
*
* Blocks until device enters sideload mode
*
* @param autoReboot whether to automatically reboot the device after sideload
* @throws DeviceNotAvailableException if device is not in sideload after reboot
*/
public void rebootIntoSideload(boolean autoReboot) throws DeviceNotAvailableException;
/**
* An alternate to {@link #reboot()} that only blocks until device is online ie visible to adb.
*
* @throws DeviceNotAvailableException if device is not available after reboot
*/
public void rebootUntilOnline() throws DeviceNotAvailableException;
/**
* An alternate to {@link #reboot()} that only blocks until device is online ie visible to adb.
*
* @param reason a reason for this reboot, or {@code null} if no reason is specified.
* @throws DeviceNotAvailableException if device is not available after reboot
* @see #reboot(String)
*/
public void rebootUntilOnline(@Nullable String reason) throws DeviceNotAvailableException;
/**
* An alternate to {@link #rebootUserspace()} ()} that only blocks until device is online ie
* visible to adb.
*
* @throws DeviceNotAvailableException if device is not available after reboot
*/
public void rebootUserspaceUntilOnline() throws DeviceNotAvailableException;
/**
* Issues a command to reboot device and returns on command complete and when device is no
* longer visible to adb.
*
* @throws DeviceNotAvailableException
*/
public void nonBlockingReboot() throws DeviceNotAvailableException;
/**
* 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.
*
* @return
* Note: setting date on device requires root
* @param date specify a particular date; will use host date if
*
* @return the date of the device in epoch format.
* @throws DeviceNotAvailableException
*/
public long getDeviceDate() throws DeviceNotAvailableException;
/**
* Make the system partition on the device writable. May reboot the device.
* @throws DeviceNotAvailableException
*/
public void remountSystemWritable() throws DeviceNotAvailableException;
/**
* Make the vendor partition on the device writable. May reboot the device.
*
* @throws DeviceNotAvailableException
*/
public void remountVendorWritable() throws DeviceNotAvailableException;
/**
* Make the system partition on the device read-only. May reboot the device.
*
* @throws DeviceNotAvailableException
*/
public void remountSystemReadOnly() throws DeviceNotAvailableException;
/**
* Make the vendor partition on the device read-only. May reboot the device.
*
* @throws DeviceNotAvailableException
*/
public void remountVendorReadOnly() throws DeviceNotAvailableException;
/**
* 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)
* @return The signing key if found, null otherwise.
* @throws DeviceNotAvailableException
*/
public String getBuildSigningKeys() throws DeviceNotAvailableException;
/**
* Collects and log ANRs from the device.
*
* @param logger an {@link ITestLogger} to log the ANRs.
* @return True if the logging was successful, false otherwise.
*/
public boolean logAnrs(ITestLogger logger) throws DeviceNotAvailableException;
/**
* Get the device class.
*
* @return the {@link String} device class.
*/
public String getDeviceClass();
/**
* Extra steps for device specific required setup that will be executed on the device prior to
* the invocation flow.
*
* @param info The {@link IBuildInfo} of the device.
* @param attributes The attributes stored in the invocation context
* @throws TargetSetupError
* @throws DeviceNotAvailableException
*/
public default void preInvocationSetup(IBuildInfo info, MultiMap method is best-effort so if one tombstone fails to be pulled for any reason it will be
* missing from the list. Only a {@link DeviceNotAvailableException} will terminate the method
* early.
*
* @return A list of tombstone files, empty if no tombstone.
* @see Tombstones documentation
*/
public Listnull if command failed to execute.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public String executeAdbCommand(long timeout, Maptrue 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 boolean runInstrumentationTests(
IRemoteAndroidTestRunner runner, Collectiontrue 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 boolean runInstrumentationTests(
IRemoteAndroidTestRunner runner, ITestLifeCycleReceiver... listeners)
throws DeviceNotAvailableException;
/**
* Same as {@link ITestDevice#runInstrumentationTests(IRemoteAndroidTestRunner, Collection)} but
* runs the test for the given user.
*/
public boolean runInstrumentationTestsAsUser(
IRemoteAndroidTestRunner runner,
int userId,
Collectiontrue if file was retrieved successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pullFile(String remoteFilePath, File localFile)
throws DeviceNotAvailableException;
/**
* Retrieves a file off device.
*
* @param remoteFilePath the absolute path to file on device.
* @param localFile the local file to store contents in. If non-empty, contents will be
* replaced.
* @param userId The user id to pull from
* @return true if file was retrieved successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pullFile(String remoteFilePath, File localFile, int userId)
throws DeviceNotAvailableException;
/**
* Retrieves a file off device.
*
* @param remoteFilePath the absolute path to file on device.
* @param localFile the local file to store contents in. If non-empty, contents will be
* replaced.
* @param userId The user id to pull from
* @param timeout pull file command timeout
* @return true if file was retrieved successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pullFile(String remoteFilePath, File localFile, int userId, long timeout)
throws DeviceNotAvailableException;
/**
* Retrieves a file off device, stores it in a local temporary {@link File}, and returns that
* {@code File}.
*
* @param remoteFilePath the absolute path to file on device.
* @return A {@link File} containing the contents of the device file, or {@code 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 File pullFile(String remoteFilePath) throws DeviceNotAvailableException;
/**
* Retrieves a file off device, stores it in a local temporary {@link File}, and returns that
* {@code File}.
*
* @param remoteFilePath the absolute path to file on device.
* @param userId The user id to pull from
* @return A {@link File} containing the contents of the device file, or {@code 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 File pullFile(String remoteFilePath, int userId) throws DeviceNotAvailableException;
/**
* Retrieves a file off device, and returns the contents.
*
* @param remoteFilePath the absolute path to file on device.
* @return A {@link String} containing the contents of the device file, or {@code null} if the
* copy failed for any reason (including problems with the host filesystem)
*/
public String pullFileContents(String remoteFilePath) throws DeviceNotAvailableException;
/**
* A convenience method to retrieve a file from the device's external storage, stores it in a
* local temporary {@link File}, and return a reference to that {@code File}.
*
* @param remoteFilePath the path to file on device, relative to the device's external storage
* mountpoint
* @return A {@link File} containing the contents of the device file, or {@code 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 File pullFileFromExternal(String remoteFilePath) throws DeviceNotAvailableException;
/**
* Recursively pull directory contents from device.
*
* @param deviceFilePath the absolute file path of the remote source
* @param localDir the local directory to pull files into
* @return true if file was pulled successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pullDir(String deviceFilePath, File localDir)
throws DeviceNotAvailableException;
/**
* Recursively pull directory contents from device.
*
* @param deviceFilePath the absolute file path of the remote source
* @param localDir the local directory to pull files into
* @param userId the user id to pull from
* @return true if file was pulled successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pullDir(String deviceFilePath, File localDir, int userId)
throws DeviceNotAvailableException;
/**
* Recursively pull directory contents from device.
*
* @param deviceFilePath the absolute file path of the remote source
* @param localDir the local directory to pull files into
* @param userId the user id to pull from
* @param timeout the timeout for pulling command
* @return true if file was pulled successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pullDir(String deviceFilePath, File localDir, int userId, long timeout)
throws DeviceNotAvailableException;
/**
* Push a file to device. By default using a content provider.
*
* @param localFile the local file to push
* @param deviceFilePath the remote destination absolute file path
* @return true if file was pushed successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pushFile(File localFile, String deviceFilePath)
throws DeviceNotAvailableException;
/**
* Push a file to device. By default using a content provider.
*
* @param localFile the local file to push
* @param deviceFilePath the remote destination absolute file path
* @param userId the userId to push to
* @return true if file was pushed successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pushFile(File localFile, String deviceFilePath, int userId)
throws DeviceNotAvailableException;
/**
* Variant of {@link #pushFile(File, String)} which can optionally consider evaluating the need
* for the content provider.
*
* @param localFile the local file to push
* @param deviceFilePath the remote destination absolute file path
* @param evaluateContentProviderNeeded whether to check if we need the content provider
* @return true if file was pushed successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pushFile(
final File localFile,
final String deviceFilePath,
boolean evaluateContentProviderNeeded)
throws DeviceNotAvailableException;
/**
* Push file created from a string to device
*
* @param contents the contents of the file to push
* @param deviceFilePath the remote destination absolute file path
* @return true if string was pushed successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pushString(String contents, String deviceFilePath)
throws DeviceNotAvailableException;
/**
* Recursively push directory contents to device.
*
* @param localDir the local directory to push
* @param deviceFilePath the absolute file path of the remote destination
* @return true if file was pushed successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pushDir(File localDir, String deviceFilePath)
throws DeviceNotAvailableException;
/**
* Recursively push directory contents to device.
*
* @param localDir the local directory to push
* @param deviceFilePath the absolute file path of the remote destination
* @param userId the user id to push to
* @return true if file was pushed successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pushDir(File localDir, String deviceFilePath, int userId)
throws DeviceNotAvailableException;
/**
* Recursively push directory contents to device while excluding some directories that are
* filtered.
*
* @param localDir the local directory to push
* @param deviceFilePath the absolute file path of the remote destination
* @param excludedDirectories Set of excluded directories names that shouldn't be pushed.
* @return true if file was pushed successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean pushDir(File localDir, String deviceFilePath, Settrue if files were synced successfully. false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean syncFiles(File localFileDir, String deviceFilePath)
throws DeviceNotAvailableException;
/**
* Helper method to determine if file on device exists.
*
* @param deviceFilePath the absolute path of file on device to check
* @return true if file exists, false otherwise.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean doesFileExist(String deviceFilePath) throws DeviceNotAvailableException;
/**
* Helper method to delete a file or directory on the device.
*
* @param deviceFilePath The absolute path of the file on the device.
* @throws DeviceNotAvailableException
*/
public void deleteFile(String deviceFilePath) throws DeviceNotAvailableException;
/**
* Helper method to delete a file or directory on the device.
*
* @param deviceFilePath The absolute path of the file on the device.
* @param userId The user id to delete from
* @throws DeviceNotAvailableException
*/
public void deleteFile(String deviceFilePath, int userId) throws DeviceNotAvailableException;
/**
* Retrieve a reference to a remote file on device.
*
* @param path the file path to retrieve. Can be an absolute path or path relative to '/'. (ie
* both "/system" and "system" syntax is supported)
* @return the {@link IFileEntry} or null if file at given path cannot
* be found
* @throws DeviceNotAvailableException
*/
public IFileEntry getFileEntry(String path) throws DeviceNotAvailableException;
/**
* Returns True if the file path on the device is an executable file, false otherwise.
*
* @throws DeviceNotAvailableException
*/
public boolean isExecutable(String fullPath) throws DeviceNotAvailableException;
/**
* Return True if the path on the device is a directory, false otherwise.
*
* @throws DeviceNotAvailableException
*/
public boolean isDirectory(String deviceFilePath) throws DeviceNotAvailableException;
/**
* Alternative to using {@link IFileEntry} that sometimes won't work because of permissions.
*
* @param deviceFilePath is the path on the device where to do the search
* @return Array of string containing all the file in a path on the device.
* @throws DeviceNotAvailableException
*/
public String[] getChildren(String deviceFilePath) throws DeviceNotAvailableException;
/**
* Helper method to determine amount of free space on device external storage.
*
* @return the amount of free space in KB
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public long getExternalStoreFreeSpace() throws DeviceNotAvailableException;
/**
* Helper method to determine amount of free space on device partition.
*
* @return the amount of free space in KB
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public long getPartitionFreeSpace(String partition) throws DeviceNotAvailableException;
/**
* Returns a mount point.
*
* Queries the device directly if the cached info in {@link IDevice} is not available.
*
* TODO: move this behavior to {@link IDevice#getMountPoint(String)}
*
* @param mountName the name of the mount point
* @return the mount point or null
* @see IDevice#getMountPoint(String)
*/
public String getMountPoint(String mountName);
/**
* Returns a parsed version of the information in /proc/mounts on the device
*
* @return A {@link List} of {@link MountPointInfo} containing the information in "/proc/mounts"
*/
public Listnull if that path has nothing mounted or otherwise does not appear in
* /proc/mounts as a mountpoint.
*
* @return A {@link List} of {@link MountPointInfo} containing the information in "/proc/mounts"
* @see #getMountPointInfo()
*/
public MountPointInfo getMountPointInfo(String mountpoint) throws DeviceNotAvailableException;
/**
* 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, {@link #stopLogcat()} must be called.
*
* {@link #startLogcat()} and {@link #stopLogcat()} do not normally need to be called when
* within a TF invocation context, as the TF framework will start and stop logcat.
*/
public void startLogcat();
/**
* Stop capturing logcat output from device, and discard currently saved logcat data.
*
* Will have no effect if logcat output is not being captured.
*/
public void stopLogcat();
/**
* Deletes any accumulated logcat data.
*
* This is useful for cases when you want to ensure {@link ITestDevice#getLogcat()} only returns
* log data produced after a certain point (such as after flashing a new device build, etc).
*/
public void clearLogcat();
/**
* Grabs a snapshot stream of the logcat data.
*
* maxBytes of captured logcat data.
*
* true if successful.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean enableAdbRoot() throws DeviceNotAvailableException;
/**
* Turns off adb root.
* true if successful.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean disableAdbRoot() throws DeviceNotAvailableException;
/**
* @return true if device currently has adb root, false otherwise.
*
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean isAdbRoot() throws DeviceNotAvailableException;
/**
* Unlocks the device if the device is in an encrypted state.
* true if successful or if the device is unencrypted.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
* @throws UnsupportedOperationException if encryption is not supported on the device.
*/
public boolean unlockDevice() throws DeviceNotAvailableException,
UnsupportedOperationException;
/**
* Returns if the device is encrypted.
*
* @return true if the device is encrypted.
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public boolean isDeviceEncrypted() throws DeviceNotAvailableException;
/**
* Returns if encryption is supported on the device.
*
* @return true if the device supports encryption.
* @throws DeviceNotAvailableException
*/
public boolean isEncryptionSupported() throws DeviceNotAvailableException;
/**
* Waits for the device to be responsive and available for testing.
*
* @param waitTime the time in ms to wait
* @throws DeviceNotAvailableException if device is still unresponsive after waitTime expires.
* @return True if device is available, False if recovery is disabled and unavailable.
*/
public boolean waitForDeviceAvailable(final long waitTime) throws DeviceNotAvailableException;
/**
* 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.
* @return True if device is available, False if recovery is disabled and unavailable.
*/
public boolean waitForDeviceAvailable() throws DeviceNotAvailableException;
/**
* Waits for the device to be responsive and available without considering recovery path.
*
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
* @return True if device is available, False if unavailable.
*/
public boolean waitForDeviceAvailableInRecoverPath(final long waitTime)
throws DeviceNotAvailableException;
/**
* Blocks until device is visible via adb.
*
* Note the device may not necessarily be responsive to commands on completion. Use
* {@link #waitForDeviceAvailable()} instead.
*
* @param waitTime the time in ms to wait
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public void waitForDeviceOnline(final long waitTime) throws DeviceNotAvailableException;
/**
* Blocks until device is visible via adb. Uses default timeout
*
* Note the device may not necessarily be responsive to commands on completion. Use
* {@link #waitForDeviceAvailable()} instead.
*
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public void waitForDeviceOnline() throws DeviceNotAvailableException;
/**
* Blocks for the device to be not available ie missing from adb
*
* @param waitTime the time in ms to wait
* @return true if device becomes not available before time expires.
* false otherwise
*/
public boolean waitForDeviceNotAvailable(final long waitTime);
/**
* Blocks until device is visible via fastboot. Use default timeout.
*
* @throws DeviceNotAvailableException if connection with device is lost and cannot be
* recovered.
*/
public void waitForDeviceBootloader() throws DeviceNotAvailableException;
/**
* Blocks for the device to be in the 'adb recovery' state (note this is distinct from
* {@link IDeviceRecovery}).
*
* @param waitTime the time in ms to wait
* @return true if device boots into recovery before time expires.
* false otherwise
*/
public boolean waitForDeviceInRecovery(final long waitTime);
/**
* Blocks for the device to be in the 'adb sideload' state
*
* @param waitTime the time in ms to wait
* @return true if device boots into sideload before time expires. false
* otherwise
*/
public boolean waitForDeviceInSideload(final long waitTime);
/**
* Waits for device to be responsive to a basic adb shell command.
*
* @param waitTime the time in ms to wait
* @return true if device becomes responsive before waitTime elapses.
*/
public boolean waitForDeviceShell(final long waitTime);
/**
* Blocks until the device's boot complete flag is set.
*
* @param timeOut time in msecs to wait for the flag to be set
* @return true if device's boot complete flag is set within the timeout
* @throws DeviceNotAvailableException
*/
public boolean waitForBootComplete(long timeOut) throws DeviceNotAvailableException;
/**
* Set the {@link IDeviceRecovery} to use for this device. Should be set when device is first
* allocated.
*
* @param recovery the {@link IDeviceRecovery}
*/
public void setRecovery(IDeviceRecovery recovery);
/**
* 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
*
* @param mode whether 'recover till online only' mode should be on or not.
*/
public void setRecoveryMode(RecoveryMode mode);
/**
* Get the current recovery mode used for the device.
*
* @return the current recovery mode used for the device.
*/
public RecoveryMode getRecoveryMode();
/**
* Get the device's state.
*/
public TestDeviceState getDeviceState();
/**
* @return true if device is connected to adb-over-tcp, false
* otherwise.
*/
public boolean isAdbTcp();
/**
* Switch device to adb-over-tcp mode.
*
* @return the tcp serial number or null if device could not be switched
* @throws DeviceNotAvailableException
*/
public String switchToAdbTcp() throws DeviceNotAvailableException;
/**
* Switch device to adb over usb mode.
*
* @return true if switch was successful, false otherwise.
* @throws DeviceNotAvailableException
*/
public boolean switchToAdbUsb() throws DeviceNotAvailableException;
/**
* Get the stream of emulator stdout and stderr
* @return emulator output
*/
public InputStreamSource getEmulatorOutput();
/**
* Close and delete the emulator output.
*/
public void stopEmulatorOutput();
/**
* Get the device API Level. Defaults to {@link #UNKNOWN_API_LEVEL}.
*
* @return an integer indicating the API Level of device
* @throws DeviceNotAvailableException
*/
public int getApiLevel() throws DeviceNotAvailableException;
/**
* Get the device's first launched API Level. Defaults to {@link #UNKNOWN_API_LEVEL}.
*
* @return an integer indicating the first launched API Level of device
* @throws DeviceNotAvailableException
*/
public int getLaunchApiLevel() throws DeviceNotAvailableException;
/**
* Check whether or not a feature is currently supported given a minimally supported level. This
* method takes into account unreleased features yet, before API level is raised.
*
* @param strictMinLevel The strict min possible level that supports the feature.
* @return True if the level is supported. False otherwise.
* @throws DeviceNotAvailableException
*/
public boolean checkApiLevelAgainstNextRelease(int strictMinLevel)
throws DeviceNotAvailableException;
/**
* Helper to get the time difference between the device and a given {@link Date}. Use Epoch time
* internally.
*
* @return the difference in milliseconds
*/
public long getDeviceTimeOffset(Date date) throws DeviceNotAvailableException;
/**
* Sets the date on device
* null
* @throws DeviceNotAvailableException
*/
public void setDate(Date date) throws DeviceNotAvailableException;
/**
* Return the date of the device in millisecond since epoch.
*
* TimeUnit.
* @return Map of boot time (UTC time in second since Epoch) and boot reason
*/
public MapTimeUnit for the given utcEpochTime.
* @return {@code true} if device soft-restarted
* @throws RuntimeException if device has abnormal boot reason
* @throws DeviceNotAvailableException
*/
public boolean deviceSoftRestartedSince(long utcEpochTime, TimeUnit timeUnit)
throws DeviceNotAvailableException;
/**
* Helper method to check if device soft-restarted by comparing current system_server with
* previous system_server {@link ProcessInfo}. Use {@link #getProcessByName} to get {@link
* ProcessInfo}.
*
* @param prevSystemServerProcess the previous system_server process {@link ProcessInfo}.
* @return {@code true} if device soft-restarted
* @throws RuntimeException if device has abnormal boot reason
* @throws DeviceNotAvailableException
*/
public boolean deviceSoftRestarted(ProcessInfo prevSystemServerProcess)
throws DeviceNotAvailableException;
/**
* Log a message in the logcat of the device. This is a safe call that will not throw even if
* the logging fails.
*
* @param tag The tag under which we log our message in the logcat.
* @param level The debug level of the message in the logcat.
* @param format The message format.
* @param args the args to be replaced via String.format().
*/
public void logOnDevice(String tag, LogLevel level, String format, Object... args);
/** Returns total physical memory size in bytes or -1 in case of internal error */
public long getTotalMemory();
/** Returns the current battery level of a device or Null if battery level unavailable. */
public Integer getBattery();
/**
* Returns the last time Tradefed APIs triggered a reboot in milliseconds since EPOCH as
* returned by {@link System#currentTimeMillis()}.
*/
public long getLastExpectedRebootTimeMillis();
/**
* Fetch and return the list of tombstones from the devices. Requires root.
*
*