BackupRestoreController
public interface BackupRestoreController extends AutoCloseable
Controls backup, restore, and verification workflows for a test device.
Provides operations to seed test data with runOnDevice, run backups with performBackup, wipe app data with clearAppData, and restore data with performRestore.
Summary
Public fields |
|
|---|---|
default static final @NonNull String |
Class name of the prebuilt action that verifies restored data in app storage. |
default static final @NonNull String |
Class name of the prebuilt action that seeds test data into app storage. |
default static final @NonNull List<@NonNull String> |
Default package installation flags: reinstall, allow test, grant all runtime permissions. |
Public methods |
|
|---|---|
abstract @NonNull BackupRestoreController |
Clears application sandbox data on the device via |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
Clears application sandbox data asynchronously on the device. |
abstract @NonNull BackupRestoreController |
Clears the device logcat buffer via |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
Clears the device logcat buffer asynchronously. |
abstract void |
close()Closes open resources, including ADB connections. |
abstract @NonNull BackupRestoreController |
fetchDeviceLogs(@NonNull Path destinationPath, @NonNull Duration duration)Saves recent device logcat entries to a local file. |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
fetchDeviceLogsAsync(@NonNull Path destinationPath)Saves recent device logcat entries asynchronously to a local file. |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
fetchDeviceLogsAsync(Saves recent device logcat entries asynchronously to a local file. |
abstract int |
SDK API level of this device or emulator. |
abstract @NonNull String |
Application ID of the target package under test. |
abstract @NonNull String |
Serial number of this device or emulator. |
abstract @NonNull BackupRestoreController |
Installs an APK from the host onto the device via |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
installApkAsync(@NonNull Path apkFile)Installs an APK asynchronously from the host onto the device. |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
Installs an APK asynchronously from the host onto the device. |
abstract @NonNull BackupRestoreController |
launchApp(Starts the target application on the device via |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
Starts the target application asynchronously on the device. |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
launchAppAsync(String activityClass)Starts the target application asynchronously on the device. |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
Starts the target application asynchronously on the device. |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
launchAppAsync(Starts the target application asynchronously on the device. |
abstract @NonNull Path |
performBackup(Captures an application backup archive using the specified transport mode. |
abstract @NonNull ListenableFuture<@NonNull Path> |
performBackupAsync(Captures an application backup archive asynchronously using the specified transport mode. |
abstract @NonNull ListenableFuture<@NonNull Path> |
performBackupAsync(Captures an application backup archive asynchronously using the specified transport mode. |
abstract @NonNull BackupRestoreController |
performRestore(@NonNull Path backupFile, @NonNull Duration timeout)Restores application data from a backup archive. |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
performRestoreAsync(@NonNull Path backupFile)Restores application data asynchronously from a backup archive. |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
performRestoreAsync(@NonNull Path backupFile, @NonNull Duration timeout)Restores application data asynchronously from a backup archive. |
abstract @NonNull BackupRestoreController |
Copies a file from the device to the host machine via |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
pullFileAsync(@NonNull String devicePath, @NonNull Path hostDestination)Copies a file asynchronously from the device to the host machine. |
abstract @NonNull BackupRestoreController |
runBackupRestoreFlow(Runs a full backup and restore flow for a single storage domain. |
abstract @NonNull BackupRestoreController |
runBackupRestoreFlow(Runs a full backup and restore flow for multiple storage domains. |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
runBackupRestoreFlowAsync(Runs a full backup and restore flow asynchronously for a single storage domain. |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
runBackupRestoreFlowAsync(Runs a full backup and restore flow asynchronously for multiple storage domains. |
abstract @NonNull BackupActionResult |
runOnDevice(Runs an on-device action inside the target application process. |
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> |
runOnDeviceAsync(@NonNull String actionClassName)Runs an on-device action asynchronously inside the target application process. |
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> |
runOnDeviceAsync(Runs an on-device action asynchronously inside the target application process. |
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> |
runOnDeviceAsync(Runs an on-device action asynchronously inside the target application process. |
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> |
runOnDeviceAsync(Runs an on-device action asynchronously inside the target application process. |
abstract @NonNull BackupRestoreController |
stopApp()Force-stops the target application on the device via |
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> |
Force-stops the target application asynchronously on the device. |
Public fields
ACTION_ASSERT_STORAGE
default static final @NonNull String ACTION_ASSERT_STORAGE
Class name of the prebuilt action that verifies restored data in app storage.
ACTION_POPULATE_STORAGE
default static final @NonNull String ACTION_POPULATE_STORAGE
Class name of the prebuilt action that seeds test data into app storage.
DEFAULT_INSTALL_OPTIONS
default static final @NonNull List<@NonNull String> DEFAULT_INSTALL_OPTIONS
Default package installation flags: reinstall, allow test, grant all runtime permissions.
Public methods
clearAppData
abstract @NonNull BackupRestoreController clearAppData()
Clears application sandbox data on the device via pm clear.
| Returns | |
|---|---|
@NonNull BackupRestoreController |
this controller instance |
| Throws | |
|---|---|
IOException |
if clearing application data fails |
clearAppDataAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> clearAppDataAsync()
Clears application sandbox data asynchronously on the device.
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
clearDeviceLogs
abstract @NonNull BackupRestoreController clearDeviceLogs()
Clears the device logcat buffer via logcat -c.
| Returns | |
|---|---|
@NonNull BackupRestoreController |
this controller instance |
| Throws | |
|---|---|
IOException |
if clearing the logcat buffer fails |
clearDeviceLogsAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> clearDeviceLogsAsync()
Clears the device logcat buffer asynchronously.
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
close
abstract void close()
Closes open resources, including ADB connections.
fetchDeviceLogs
abstract @NonNull BackupRestoreController fetchDeviceLogs(@NonNull Path destinationPath, @NonNull Duration duration)
Saves recent device logcat entries to a local file.
| Parameters | |
|---|---|
@NonNull Path destinationPath |
local file path where logs will be written |
@NonNull Duration duration |
time window of historical logs to capture |
| Returns | |
|---|---|
@NonNull BackupRestoreController |
this controller instance |
| Throws | |
|---|---|
IOException |
if capturing logs fails |
fetchDeviceLogsAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> fetchDeviceLogsAsync(@NonNull Path destinationPath)
Saves recent device logcat entries asynchronously to a local file.
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
fetchDeviceLogsAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> fetchDeviceLogsAsync(
@NonNull Path destinationPath,
@NonNull Duration duration
)
Saves recent device logcat entries asynchronously to a local file.
| Parameters | |
|---|---|
@NonNull Path destinationPath |
local file path where logs will be written |
@NonNull Duration duration |
time window of historical logs to capture |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
getApiLevel
abstract int getApiLevel()
SDK API level of this device or emulator.
getApplicationId
abstract @NonNull String getApplicationId()
Application ID of the target package under test.
getSerialNumber
abstract @NonNull String getSerialNumber()
Serial number of this device or emulator.
installApk
abstract @NonNull BackupRestoreController installApk(@NonNull Path apkFile, @NonNull List<@NonNull String> options)
Installs an APK from the host onto the device via pm install.
| Parameters | |
|---|---|
@NonNull Path apkFile |
path to the APK on the host |
@NonNull List<@NonNull String> options |
installation flags to pass to package manager |
| Returns | |
|---|---|
@NonNull BackupRestoreController |
this controller instance |
| Throws | |
|---|---|
IOException |
if package installation fails |
installApkAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> installApkAsync(@NonNull Path apkFile)
Installs an APK asynchronously from the host onto the device.
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
installApkAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> installApkAsync(
@NonNull Path apkFile,
@NonNull List<@NonNull String> options
)
Installs an APK asynchronously from the host onto the device.
| Parameters | |
|---|---|
@NonNull Path apkFile |
path to the APK on the host |
@NonNull List<@NonNull String> options |
installation flags to pass to package manager |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
launchApp
abstract @NonNull BackupRestoreController launchApp(
String activityClass,
@NonNull Map<@NonNull String, @NonNull String> intentExtras,
String action
)
Starts the target application on the device via am start.
| Parameters | |
|---|---|
String activityClass |
activity class to launch, or null for default launcher activity |
@NonNull Map<@NonNull String, @NonNull String> intentExtras |
key-value pairs to pass as intent extras |
String action |
intent action string to launch with, or null for MAIN |
| Returns | |
|---|---|
@NonNull BackupRestoreController |
this controller instance |
| Throws | |
|---|---|
IOException |
if starting the application fails |
launchAppAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> launchAppAsync()
Starts the target application asynchronously on the device.
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
launchAppAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> launchAppAsync(String activityClass)
Starts the target application asynchronously on the device.
| Parameters | |
|---|---|
String activityClass |
activity class to launch, or null for default launcher activity |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
launchAppAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> launchAppAsync(
String activityClass,
@NonNull Map<@NonNull String, @NonNull String> intentExtras
)
Starts the target application asynchronously on the device.
| Parameters | |
|---|---|
String activityClass |
activity class to launch, or null for default launcher activity |
@NonNull Map<@NonNull String, @NonNull String> intentExtras |
key-value pairs to pass as intent extras |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
launchAppAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> launchAppAsync(
String activityClass,
@NonNull Map<@NonNull String, @NonNull String> intentExtras,
String action
)
Starts the target application asynchronously on the device.
| Parameters | |
|---|---|
String activityClass |
activity class to launch, or null for default launcher activity |
@NonNull Map<@NonNull String, @NonNull String> intentExtras |
key-value pairs to pass as intent extras |
String action |
intent action string to launch with |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
performBackup
abstract @NonNull Path performBackup(
@NonNull BackupTransportMode mode,
@NonNull Path outputDir,
@NonNull Duration timeout
)
Captures an application backup archive using the specified transport mode.
| Parameters | |
|---|---|
@NonNull BackupTransportMode mode |
transport mode to test |
@NonNull Path outputDir |
directory where the backup archive is saved |
@NonNull Duration timeout |
maximum duration to wait for the backup to complete |
| Throws | |
|---|---|
IOException |
if the backup operation fails |
performBackupAsync
abstract @NonNull ListenableFuture<@NonNull Path> performBackupAsync(
@NonNull BackupTransportMode mode,
@NonNull Path outputDir
)
Captures an application backup archive asynchronously using the specified transport mode.
| Parameters | |
|---|---|
@NonNull BackupTransportMode mode |
transport mode to test |
@NonNull Path outputDir |
directory where the backup archive is saved |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull Path> |
a |
performBackupAsync
abstract @NonNull ListenableFuture<@NonNull Path> performBackupAsync(
@NonNull BackupTransportMode mode,
@NonNull Path outputDir,
@NonNull Duration timeout
)
Captures an application backup archive asynchronously using the specified transport mode.
| Parameters | |
|---|---|
@NonNull BackupTransportMode mode |
transport mode to test |
@NonNull Path outputDir |
directory where the backup archive is saved |
@NonNull Duration timeout |
maximum duration to wait for the backup to complete |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull Path> |
a |
performRestore
abstract @NonNull BackupRestoreController performRestore(@NonNull Path backupFile, @NonNull Duration timeout)
Restores application data from a backup archive.
| Parameters | |
|---|---|
@NonNull Path backupFile |
backup archive generated by |
@NonNull Duration timeout |
maximum duration to wait for the restore to complete |
| Returns | |
|---|---|
@NonNull BackupRestoreController |
this controller instance |
| Throws | |
|---|---|
IOException |
if the restore operation fails |
performRestoreAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> performRestoreAsync(@NonNull Path backupFile)
Restores application data asynchronously from a backup archive.
| Parameters | |
|---|---|
@NonNull Path backupFile |
backup archive generated by |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
performRestoreAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> performRestoreAsync(@NonNull Path backupFile, @NonNull Duration timeout)
Restores application data asynchronously from a backup archive.
| Parameters | |
|---|---|
@NonNull Path backupFile |
backup archive generated by |
@NonNull Duration timeout |
maximum duration to wait for the restore to complete |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
pullFile
abstract @NonNull BackupRestoreController pullFile(@NonNull String devicePath, @NonNull Path hostDestination)
Copies a file from the device to the host machine via adb pull.
| Parameters | |
|---|---|
@NonNull String devicePath |
path to the file on the device |
@NonNull Path hostDestination |
path to write the file on the host |
| Returns | |
|---|---|
@NonNull BackupRestoreController |
this controller instance |
| Throws | |
|---|---|
IOException |
if copying the file fails |
pullFileAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> pullFileAsync(@NonNull String devicePath, @NonNull Path hostDestination)
Copies a file asynchronously from the device to the host machine.
| Parameters | |
|---|---|
@NonNull String devicePath |
path to the file on the device |
@NonNull Path hostDestination |
path to write the file on the host |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
runBackupRestoreFlow
abstract @NonNull BackupRestoreController runBackupRestoreFlow(
@NonNull StorageDomain storage,
@NonNull Path outputDir,
@NonNull BackupTransportMode mode
)
Runs a full backup and restore flow for a single storage domain.
Seeds test data into storage using ACTION_POPULATE_STORAGE, runs a backup to outputDir using mode, clears app data, restores the backup archive, and verifies data integrity using ACTION_ASSERT_STORAGE.
| Parameters | |
|---|---|
@NonNull StorageDomain storage |
storage domain to seed and verify |
@NonNull Path outputDir |
directory where the generated backup file is saved |
@NonNull BackupTransportMode mode |
transport mode to test |
| Returns | |
|---|---|
@NonNull BackupRestoreController |
this controller instance |
| Throws | |
|---|---|
IOException |
if any step fails |
runBackupRestoreFlow
abstract @NonNull BackupRestoreController runBackupRestoreFlow(
@NonNull List<@NonNull StorageDomain> storages,
@NonNull Path outputDir,
@NonNull BackupTransportMode mode
)
Runs a full backup and restore flow for multiple storage domains.
Seeds each domain in storages using ACTION_POPULATE_STORAGE, runs a backup to outputDir using mode, clears app data, restores the backup archive, and verifies each domain using ACTION_ASSERT_STORAGE.
| Parameters | |
|---|---|
@NonNull List<@NonNull StorageDomain> storages |
storage domains to seed and verify |
@NonNull Path outputDir |
directory where the generated backup file is saved |
@NonNull BackupTransportMode mode |
transport mode to test |
| Returns | |
|---|---|
@NonNull BackupRestoreController |
this controller instance |
| Throws | |
|---|---|
IOException |
if any step fails |
runBackupRestoreFlowAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> runBackupRestoreFlowAsync(
@NonNull StorageDomain storage,
@NonNull Path outputDir,
@NonNull BackupTransportMode mode
)
Runs a full backup and restore flow asynchronously for a single storage domain.
| Parameters | |
|---|---|
@NonNull StorageDomain storage |
storage domain to seed and verify |
@NonNull Path outputDir |
directory where the generated backup file is saved |
@NonNull BackupTransportMode mode |
transport mode to test |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
runBackupRestoreFlowAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> runBackupRestoreFlowAsync(
@NonNull List<@NonNull StorageDomain> storages,
@NonNull Path outputDir,
@NonNull BackupTransportMode mode
)
Runs a full backup and restore flow asynchronously for multiple storage domains.
| Parameters | |
|---|---|
@NonNull List<@NonNull StorageDomain> storages |
storage domains to seed and verify |
@NonNull Path outputDir |
directory where the generated backup file is saved |
@NonNull BackupTransportMode mode |
transport mode to test |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |
runOnDevice
abstract @NonNull BackupActionResult runOnDevice(
@NonNull String actionClassName,
@NonNull Map<@NonNull String, @NonNull String> args,
@NonNull Duration timeout,
boolean waitForDebugger
)
Runs an on-device action inside the target application process.
| Parameters | |
|---|---|
@NonNull String actionClassName |
class name of the |
@NonNull Map<@NonNull String, @NonNull String> args |
arguments to pass to the action |
@NonNull Duration timeout |
maximum duration to wait for the action to complete |
boolean waitForDebugger |
whether the runner waits for a debugger to attach before running |
| Returns | |
|---|---|
@NonNull BackupActionResult |
result of the action execution |
| Throws | |
|---|---|
IOException |
if communicating with the device fails |
runOnDeviceAsync
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> runOnDeviceAsync(@NonNull String actionClassName)
Runs an on-device action asynchronously inside the target application process.
| Parameters | |
|---|---|
@NonNull String actionClassName |
class name of the |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupActionResult> |
a |
runOnDeviceAsync
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> runOnDeviceAsync(
@NonNull String actionClassName,
@NonNull Map<@NonNull String, @NonNull String> args
)
Runs an on-device action asynchronously inside the target application process.
| Parameters | |
|---|---|
@NonNull String actionClassName |
class name of the |
@NonNull Map<@NonNull String, @NonNull String> args |
arguments to pass to the action |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupActionResult> |
a |
runOnDeviceAsync
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> runOnDeviceAsync(
@NonNull String actionClassName,
@NonNull Map<@NonNull String, @NonNull String> args,
@NonNull Duration timeout
)
Runs an on-device action asynchronously inside the target application process.
| Parameters | |
|---|---|
@NonNull String actionClassName |
class name of the |
@NonNull Map<@NonNull String, @NonNull String> args |
arguments to pass to the action |
@NonNull Duration timeout |
maximum duration to wait for the action to complete |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupActionResult> |
a |
runOnDeviceAsync
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> runOnDeviceAsync(
@NonNull String actionClassName,
@NonNull Map<@NonNull String, @NonNull String> args,
@NonNull Duration timeout,
boolean waitForDebugger
)
Runs an on-device action asynchronously inside the target application process.
| Parameters | |
|---|---|
@NonNull String actionClassName |
class name of the |
@NonNull Map<@NonNull String, @NonNull String> args |
arguments to pass to the action |
@NonNull Duration timeout |
maximum duration to wait for the action to complete |
boolean waitForDebugger |
whether the runner waits for a debugger to attach before running |
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupActionResult> |
a |
stopApp
abstract @NonNull BackupRestoreController stopApp()
Force-stops the target application on the device via am force-stop.
| Returns | |
|---|---|
@NonNull BackupRestoreController |
this controller instance |
| Throws | |
|---|---|
IOException |
if stopping the application fails |
stopAppAsync
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> stopAppAsync()
Force-stops the target application asynchronously on the device.
| Returns | |
|---|---|
@NonNull ListenableFuture<@NonNull BackupRestoreController> |
a |