# BackupRestoreController Artifact: [androidx.test.backup:backup-host](https://developer.android.com/jetpack/androidx/releases/test-backup) [View Source](https://cs.android.com/search?q=file:androidx/test/backup/host/BackupRestoreController.kt+class:androidx.test.backup.host.BackupRestoreController) Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) *** ** * ** *** ``` interface BackupRestoreController : AutoCloseable ```
*** ** * ** *** Controls backup, restore, and verification workflows for a test device. Provides operations to seed test data with `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runOnDevice(kotlin.String,kotlin.collections.Map,java.time.Duration,kotlin.Boolean)`, run backups with `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performBackup(androidx.test.backup.host.BackupTransportMode,java.nio.file.Path,java.time.Duration)`, wipe app data with `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#clearAppData()`, and restore data with `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performRestore(java.nio.file.Path,java.time.Duration)`. ## Summary | ### Public companion properties | |---|---| | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#ACTION_ASSERT_STORAGE()` Class name of the prebuilt action that verifies restored data in app storage. | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#ACTION_POPULATE_STORAGE()` Class name of the prebuilt action that seeds test data into app storage. | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#DEFAULT_INSTALL_OPTIONS()` Default package installation flags: reinstall, allow test, grant all runtime permissions. | | ### Public functions | |---|---| | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#clearAppData()()` Clears application sandbox data on the device via `pm clear`. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#clearAppDataAsync()()` Clears application sandbox data asynchronously on the device. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#clearDeviceLogs()()` Clears the device logcat buffer via `logcat -c`. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#clearDeviceLogsAsync()()` Clears the device logcat buffer asynchronously. | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#close()()` Releases the resources held by this controller. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#fetchDeviceLogs(java.nio.file.Path,java.time.Duration)(destinationPath: https://developer.android.com/reference/java/nio/file/Path.html, duration: https://developer.android.com/reference/java/time/Duration.html)` Saves recent device logcat entries to a local file. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#fetchDeviceLogsAsync(java.nio.file.Path)(destinationPath: https://developer.android.com/reference/java/nio/file/Path.html)` Saves recent device logcat entries asynchronously to a local file. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#fetchDeviceLogsAsync(java.nio.file.Path,java.time.Duration)(destinationPath: https://developer.android.com/reference/java/nio/file/Path.html, duration: https://developer.android.com/reference/java/time/Duration.html)` Saves recent device logcat entries asynchronously to a local file. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#installApk(java.nio.file.Path,kotlin.collections.List)(apkFile: https://developer.android.com/reference/java/nio/file/Path.html, options: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html)` Installs an APK from the host onto the device via `pm install`. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#installApkAsync(java.nio.file.Path)(apkFile: https://developer.android.com/reference/java/nio/file/Path.html)` Installs an APK asynchronously from the host onto the device. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#installApkAsync(java.nio.file.Path,kotlin.collections.List)(apkFile: https://developer.android.com/reference/java/nio/file/Path.html, options: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html)` Installs an APK asynchronously from the host onto the device. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#launchApp(kotlin.String,kotlin.collections.Map,kotlin.String)( activityClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?, intentExtras: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html, action: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html? )` Starts the target application on the device via `am start`. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#launchAppAsync()()` Starts the target application asynchronously on the device. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#launchAppAsync(kotlin.String)(activityClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?)` Starts the target application asynchronously on the device. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#launchAppAsync(kotlin.String,kotlin.collections.Map)(activityClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?, intentExtras: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html)` Starts the target application asynchronously on the device. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#launchAppAsync(kotlin.String,kotlin.collections.Map,kotlin.String)( activityClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?, intentExtras: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html, action: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html? )` Starts the target application asynchronously on the device. | | `suspend https://developer.android.com/reference/java/nio/file/Path.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performBackup(androidx.test.backup.host.BackupTransportMode,java.nio.file.Path,java.time.Duration)( mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode, outputDir: https://developer.android.com/reference/java/nio/file/Path.html, timeout: https://developer.android.com/reference/java/time/Duration.html )` Captures an application backup archive using the specified transport mode. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performBackupAsync(androidx.test.backup.host.BackupTransportMode,java.nio.file.Path)(mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode, outputDir: https://developer.android.com/reference/java/nio/file/Path.html)` Captures an application backup archive asynchronously using the specified transport mode. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performBackupAsync(androidx.test.backup.host.BackupTransportMode,java.nio.file.Path,java.time.Duration)( mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode, outputDir: https://developer.android.com/reference/java/nio/file/Path.html, timeout: https://developer.android.com/reference/java/time/Duration.html )` Captures an application backup archive asynchronously using the specified transport mode. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performRestore(java.nio.file.Path,java.time.Duration)(backupFile: https://developer.android.com/reference/java/nio/file/Path.html, timeout: https://developer.android.com/reference/java/time/Duration.html)` Restores application data from a backup archive. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performRestoreAsync(java.nio.file.Path)(backupFile: https://developer.android.com/reference/java/nio/file/Path.html)` Restores application data asynchronously from a backup archive. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performRestoreAsync(java.nio.file.Path,java.time.Duration)(backupFile: https://developer.android.com/reference/java/nio/file/Path.html, timeout: https://developer.android.com/reference/java/time/Duration.html)` Restores application data asynchronously from a backup archive. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#pullFile(kotlin.String,java.nio.file.Path)(devicePath: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, hostDestination: https://developer.android.com/reference/java/nio/file/Path.html)` Copies a file from the device to the host machine via `adb pull`. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#pullFileAsync(kotlin.String,java.nio.file.Path)(devicePath: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, hostDestination: https://developer.android.com/reference/java/nio/file/Path.html)` Copies a file asynchronously from the device to the host machine. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)( storage: https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain, outputDir: https://developer.android.com/reference/java/nio/file/Path.html, mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode, restoreOn: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController )` Runs a full backup and restore flow for a single storage domain. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)( storages: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html, outputDir: https://developer.android.com/reference/java/nio/file/Path.html, mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode, restoreOn: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController )` Runs a full backup and restore flow for multiple storage domains. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode)( storage: https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain, outputDir: https://developer.android.com/reference/java/nio/file/Path.html, mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode )` Runs a full backup and restore flow asynchronously for a single storage domain. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode)( storages: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html, outputDir: https://developer.android.com/reference/java/nio/file/Path.html, mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode )` Runs a full backup and restore flow asynchronously for multiple storage domains. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)( storage: https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain, outputDir: https://developer.android.com/reference/java/nio/file/Path.html, mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode, restoreOn: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController )` Runs a full backup and restore flow asynchronously for a single storage domain, restoring and verifying on `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)`. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)( storages: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html, outputDir: https://developer.android.com/reference/java/nio/file/Path.html, mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode, restoreOn: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController )` Runs a full backup and restore flow asynchronously for multiple storage domains, restoring and verifying on `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)`. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupActionResult` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runOnDevice(kotlin.String,kotlin.collections.Map,java.time.Duration,kotlin.Boolean)( actionClassName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, args: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html, timeout: https://developer.android.com/reference/java/time/Duration.html, waitForDebugger: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` Runs an on-device action inside the target application process. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runOnDeviceAsync(kotlin.String)(actionClassName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Runs an on-device action asynchronously inside the target application process. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runOnDeviceAsync(kotlin.String,kotlin.collections.Map)(actionClassName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, args: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html)` Runs an on-device action asynchronously inside the target application process. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runOnDeviceAsync(kotlin.String,kotlin.collections.Map,java.time.Duration)( actionClassName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, args: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html, timeout: https://developer.android.com/reference/java/time/Duration.html )` Runs an on-device action asynchronously inside the target application process. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runOnDeviceAsync(kotlin.String,kotlin.collections.Map,java.time.Duration,kotlin.Boolean)( actionClassName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, args: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html, timeout: https://developer.android.com/reference/java/time/Duration.html, waitForDebugger: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` Runs an on-device action asynchronously inside the target application process. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#stopApp()()` Force-stops the target application on the device via `am force-stop`. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#stopAppAsync()()` Force-stops the target application asynchronously on the device. | | `suspend https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#uninstallApp()()` Uninstalls the target application from the device via `pm uninstall`, if it is installed. | | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#uninstallAppAsync()()` Uninstalls the target application asynchronously from the device, if it is installed. | | ### Public properties | |---|---| | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#apiLevel()` SDK API level of this device or emulator. | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#applicationId()` Application ID of the target package under test. | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#serialNumber()` Serial number of this device or emulator. | ## Public companion properties ### ACTION_ASSERT_STORAGE ``` val ACTION_ASSERT_STORAGE: String ``` Class name of the prebuilt action that verifies restored data in app storage. ### ACTION_POPULATE_STORAGE ``` val ACTION_POPULATE_STORAGE: String ``` Class name of the prebuilt action that seeds test data into app storage. ### DEFAULT_INSTALL_OPTIONS ``` val DEFAULT_INSTALL_OPTIONS: List ``` Default package installation flags: reinstall, allow test, grant all runtime permissions. ## Public functions ### clearAppData ``` suspend fun clearAppData(): BackupRestoreController ``` Clears application sandbox data on the device via `pm clear`. | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if clearing application data fails | ### clearAppDataAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun clearAppDataAsync(): ListenableFuture ``` Clears application sandbox data asynchronously on the device. | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### clearDeviceLogs ``` suspend fun clearDeviceLogs(): BackupRestoreController ``` Clears the device logcat buffer via `logcat -c`. | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if clearing the logcat buffer fails | ### clearDeviceLogsAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun clearDeviceLogsAsync(): ListenableFuture ``` Clears the device logcat buffer asynchronously. | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### close Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun close(): Unit ``` Releases the resources held by this controller. The ADB session that the controller runs on stays open, since other controllers can share it. The session is closed by whoever created it. ### fetchDeviceLogs ``` suspend fun fetchDeviceLogs( destinationPath: Path, duration: Duration = Duration.ofSeconds(30) ): BackupRestoreController ``` Saves recent device logcat entries to a local file. | Parameters | |---|---| | `destinationPath: https://developer.android.com/reference/java/nio/file/Path.html` | local file path where logs will be written | | `duration: https://developer.android.com/reference/java/time/Duration.html = Duration.ofSeconds(30)` | time window of historical logs to capture | | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if capturing logs fails | ### fetchDeviceLogsAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun fetchDeviceLogsAsync(destinationPath: Path): ListenableFuture ``` Saves recent device logcat entries asynchronously to a local file. | Parameters | |---|---| | `destinationPath: https://developer.android.com/reference/java/nio/file/Path.html` | local file path where logs will be written | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### fetchDeviceLogsAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun fetchDeviceLogsAsync(destinationPath: Path, duration: Duration): ListenableFuture ``` Saves recent device logcat entries asynchronously to a local file. | Parameters | |---|---| | `destinationPath: https://developer.android.com/reference/java/nio/file/Path.html` | local file path where logs will be written | | `duration: https://developer.android.com/reference/java/time/Duration.html` | time window of historical logs to capture | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### installApk ``` suspend fun installApk(apkFile: Path, options: List = DEFAULT_INSTALL_OPTIONS): BackupRestoreController ``` Installs an APK from the host onto the device via `pm install`. | Parameters | |---|---| | `apkFile: https://developer.android.com/reference/java/nio/file/Path.html` | path to the APK on the host | | `options: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html = DEFAULT_INSTALL_OPTIONS` | installation flags to pass to package manager | | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if package installation fails | ### installApkAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun installApkAsync(apkFile: Path): ListenableFuture ``` Installs an APK asynchronously from the host onto the device. | Parameters | |---|---| | `apkFile: https://developer.android.com/reference/java/nio/file/Path.html` | path to the APK on the host | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### installApkAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun installApkAsync(apkFile: Path, options: List): ListenableFuture ``` Installs an APK asynchronously from the host onto the device. | Parameters | |---|---| | `apkFile: https://developer.android.com/reference/java/nio/file/Path.html` | path to the APK on the host | | `options: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html` | installation flags to pass to package manager | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### launchApp ``` suspend fun launchApp( activityClass: String? = null, intentExtras: Map = emptyMap(), action: String? = null ): BackupRestoreController ``` Starts the target application on the device via `am start`. | Parameters | |---|---| | `activityClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html? = null` | activity class to launch, or null for default launcher activity | | `intentExtras: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html = emptyMap()` | key-value pairs to pass as intent extras | | `action: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html? = null` | intent action string to launch with, or null for MAIN | | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if starting the application fails | ### launchAppAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun launchAppAsync(): ListenableFuture ``` Starts the target application asynchronously on the device. | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### launchAppAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun launchAppAsync(activityClass: String?): ListenableFuture ``` Starts the target application asynchronously on the device. | Parameters | |---|---| | `activityClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?` | activity class to launch, or null for default launcher activity | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### launchAppAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun launchAppAsync(activityClass: String?, intentExtras: Map): ListenableFuture ``` Starts the target application asynchronously on the device. | Parameters | |---|---| | `activityClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?` | activity class to launch, or null for default launcher activity | | `intentExtras: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html` | key-value pairs to pass as intent extras | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### launchAppAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun launchAppAsync( activityClass: String?, intentExtras: Map, action: String? ): ListenableFuture ``` Starts the target application asynchronously on the device. | Parameters | |---|---| | `activityClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?` | activity class to launch, or null for default launcher activity | | `intentExtras: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html` | key-value pairs to pass as intent extras | | `action: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?` | intent action string to launch with | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### performBackup ``` suspend fun performBackup( mode: BackupTransportMode, outputDir: Path, timeout: Duration = Duration.ofMinutes(5) ): Path ``` Captures an application backup archive using the specified transport mode. | Parameters | |---|---| | `mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode` | transport mode to test | | `outputDir: https://developer.android.com/reference/java/nio/file/Path.html` | directory where the backup archive is saved | | `timeout: https://developer.android.com/reference/java/time/Duration.html = Duration.ofMinutes(5)` | maximum duration to wait for the backup to complete. When it expires, the app is force-stopped and the backup fails with an `https://developer.android.com/reference/java/io/IOException.html`. Must be positive. | | Returns | |---|---| | `https://developer.android.com/reference/java/nio/file/Path.html` | path to the generated backup archive. A `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode#LOCAL()` archive only marks the backup, whose data stays on the device. | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if the backup operation fails, or the app does not allow backups | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performBackup(androidx.test.backup.host.BackupTransportMode,java.nio.file.Path,java.time.Duration)` is not positive | ### performBackupAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun performBackupAsync(mode: BackupTransportMode, outputDir: Path): ListenableFuture ``` Captures an application backup archive asynchronously using the specified transport mode. | Parameters | |---|---| | `mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode` | transport mode to test | | `outputDir: https://developer.android.com/reference/java/nio/file/Path.html` | directory where the backup archive is saved | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with the generated backup path | ### performBackupAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun performBackupAsync( mode: BackupTransportMode, outputDir: Path, timeout: Duration ): ListenableFuture ``` Captures an application backup archive asynchronously using the specified transport mode. | Parameters | |---|---| | `mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode` | transport mode to test | | `outputDir: https://developer.android.com/reference/java/nio/file/Path.html` | directory where the backup archive is saved | | `timeout: https://developer.android.com/reference/java/time/Duration.html` | maximum duration to wait for the backup to complete. When it expires, the app is force-stopped and the backup fails with an `https://developer.android.com/reference/java/io/IOException.html`. Must be positive, or the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with the generated backup path | ### performRestore ``` suspend fun performRestore(backupFile: Path, timeout: Duration = Duration.ofMinutes(5)): BackupRestoreController ``` Restores application data from a backup archive. | Parameters | |---|---| | `backupFile: https://developer.android.com/reference/java/nio/file/Path.html` | backup archive generated by `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performBackup(androidx.test.backup.host.BackupTransportMode,java.nio.file.Path,java.time.Duration)` | | `timeout: https://developer.android.com/reference/java/time/Duration.html = Duration.ofMinutes(5)` | maximum duration to wait for the restore to complete. When it expires, the app is force-stopped and the restore fails with an `https://developer.android.com/reference/java/io/IOException.html`. Must be positive. | | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if the restore operation fails or restores no app data, if Google Play services on the device is too old to restore `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performRestore(java.nio.file.Path,java.time.Duration)`, or if `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performRestore(java.nio.file.Path,java.time.Duration)` is a `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode#LOCAL()` archive of another app or of another device | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performRestore(java.nio.file.Path,java.time.Duration)` is not positive | ### performRestoreAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun performRestoreAsync(backupFile: Path): ListenableFuture ``` Restores application data asynchronously from a backup archive. | Parameters | |---|---| | `backupFile: https://developer.android.com/reference/java/nio/file/Path.html` | backup archive generated by `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performBackup(androidx.test.backup.host.BackupTransportMode,java.nio.file.Path,java.time.Duration)` | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### performRestoreAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun performRestoreAsync(backupFile: Path, timeout: Duration): ListenableFuture ``` Restores application data asynchronously from a backup archive. | Parameters | |---|---| | `backupFile: https://developer.android.com/reference/java/nio/file/Path.html` | backup archive generated by `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#performBackup(androidx.test.backup.host.BackupTransportMode,java.nio.file.Path,java.time.Duration)` | | `timeout: https://developer.android.com/reference/java/time/Duration.html` | maximum duration to wait for the restore to complete. When it expires, the app is force-stopped and the restore fails with an `https://developer.android.com/reference/java/io/IOException.html`. Must be positive, or the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### pullFile ``` suspend fun pullFile(devicePath: String, hostDestination: Path): BackupRestoreController ``` Copies a file from the device to the host machine via `adb pull`. | Parameters | |---|---| | `devicePath: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | path to the file on the device | | `hostDestination: https://developer.android.com/reference/java/nio/file/Path.html` | path to write the file on the host | | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if copying the file fails | ### pullFileAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun pullFileAsync(devicePath: String, hostDestination: Path): ListenableFuture ``` Copies a file asynchronously from the device to the host machine. | Parameters | |---|---| | `devicePath: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | path to the file on the device | | `hostDestination: https://developer.android.com/reference/java/nio/file/Path.html` | path to write the file on the host | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### runBackupRestoreFlow ``` suspend fun runBackupRestoreFlow( storage: StorageDomain, outputDir: Path, mode: BackupTransportMode, restoreOn: BackupRestoreController = this ): BackupRestoreController ``` Runs a full backup and restore flow for a single storage domain. Seeds `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` on this device, runs a backup to `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` using `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)`, then, on `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)`, clears app data, restores the backup archive, and verifies `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)`. | Parameters | |---|---| | `storage: https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain` | storage domain to seed and verify | | `outputDir: https://developer.android.com/reference/java/nio/file/Path.html` | directory where the generated backup file is saved | | `mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode` | transport mode to test | | `restoreOn: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController = this` | device controller on which app data is cleared, restored, and verified. Defaults to this controller. Must have the same `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#applicationId()` as this controller, and for `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode#LOCAL()`, the same `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#serialNumber()`. | | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance, even when the restore ran on `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if any step fails | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` is a `https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain.ExcludedData`, or if `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` has a different `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#applicationId()`, or a different `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#serialNumber()` with `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode#LOCAL()` | ### runBackupRestoreFlow ``` suspend fun runBackupRestoreFlow( storages: List, outputDir: Path, mode: BackupTransportMode, restoreOn: BackupRestoreController = this ): BackupRestoreController ``` Runs a full backup and restore flow for multiple storage domains. Seeds each domain in `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` on this device, runs a backup to `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` using `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)`, then, on `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)`, clears app data, restores the backup archive, and verifies each domain. | Parameters | |---|---| | `storages: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html` | storage domains to seed and verify | | `outputDir: https://developer.android.com/reference/java/nio/file/Path.html` | directory where the generated backup file is saved | | `mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode` | transport mode to test | | `restoreOn: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController = this` | device controller on which app data is cleared, restored, and verified. Defaults to this controller. Must have the same `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#applicationId()` as this controller, and for `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode#LOCAL()`, the same `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#serialNumber()`. | | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance, even when the restore ran on `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if any step fails | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` is empty or has only `https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain.ExcludedData`, or if `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` has a different `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#applicationId()`, or a different `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#serialNumber()` with `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode#LOCAL()` | ### runBackupRestoreFlowAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun runBackupRestoreFlowAsync( storage: StorageDomain, outputDir: Path, mode: BackupTransportMode ): ListenableFuture ``` Runs a full backup and restore flow asynchronously for a single storage domain. | Parameters | |---|---| | `storage: https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain` | storage domain to seed and verify. Must not be a `https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain.ExcludedData`, or the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | `outputDir: https://developer.android.com/reference/java/nio/file/Path.html` | directory where the generated backup file is saved | | `mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode` | transport mode to test | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### runBackupRestoreFlowAsync ``` fun runBackupRestoreFlowAsync( storages: List, outputDir: Path, mode: BackupTransportMode ): ListenableFuture ``` Runs a full backup and restore flow asynchronously for multiple storage domains. | Parameters | |---|---| | `storages: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html` | storage domains to seed and verify. Must not be empty or hold only `https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain.ExcludedData`, or the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | `outputDir: https://developer.android.com/reference/java/nio/file/Path.html` | directory where the generated backup file is saved | | `mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode` | transport mode to test | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### runBackupRestoreFlowAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun runBackupRestoreFlowAsync( storage: StorageDomain, outputDir: Path, mode: BackupTransportMode, restoreOn: BackupRestoreController ): ListenableFuture ``` Runs a full backup and restore flow asynchronously for a single storage domain, restoring and verifying on `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)`. | Parameters | |---|---| | `storage: https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain` | storage domain to seed and verify. Must not be a `https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain.ExcludedData`, or the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | `outputDir: https://developer.android.com/reference/java/nio/file/Path.html` | directory where the generated backup file is saved | | `mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode` | transport mode to test | | `restoreOn: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | device controller on which app data is cleared, restored, and verified. Must have the same `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#applicationId()` as this controller, and for `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode#LOCAL()`, the same `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#serialNumber()`, or the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance, even when the restore ran on `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` | ### runBackupRestoreFlowAsync ``` fun runBackupRestoreFlowAsync( storages: List, outputDir: Path, mode: BackupTransportMode, restoreOn: BackupRestoreController ): ListenableFuture ``` Runs a full backup and restore flow asynchronously for multiple storage domains, restoring and verifying on `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)`. | Parameters | |---|---| | `storages: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html` | storage domains to seed and verify. Must not be empty or hold only `https://developer.android.com/reference/kotlin/androidx/test/backup/host/StorageDomain.ExcludedData`, or the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | `outputDir: https://developer.android.com/reference/java/nio/file/Path.html` | directory where the generated backup file is saved | | `mode: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode` | transport mode to test | | `restoreOn: https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | device controller on which app data is cleared, restored, and verified. Must have the same `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#applicationId()` as this controller, and for `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupTransportMode#LOCAL()`, the same `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#serialNumber()`, or the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance, even when the restore ran on `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(kotlin.collections.List,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` | ### runOnDevice ``` suspend fun runOnDevice( actionClassName: String, args: Map = emptyMap(), timeout: Duration = Duration.ofMinutes(1), waitForDebugger: Boolean = false ): BackupActionResult ``` Runs an on-device action inside the target application process. | Parameters | |---|---| | `actionClassName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | class name of the `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceAction` to run | | `args: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html = emptyMap()` | arguments to pass to the action. The keys `actionClass`, `argsFile`, `debug` and `redirect_dir` are reserved for the runner. | | `timeout: https://developer.android.com/reference/java/time/Duration.html = Duration.ofMinutes(1)` | maximum duration to wait for the action to complete. When it expires, the app is force-stopped and a `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupActionResult.Failure` is returned. Must be positive. | | `waitForDebugger: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | whether the runner waits for a debugger to attach before running | | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupActionResult` | result of the action execution | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if communicating with the device fails | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runOnDevice(kotlin.String,kotlin.collections.Map,java.time.Duration,kotlin.Boolean)` is not positive, or if `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runOnDevice(kotlin.String,kotlin.collections.Map,java.time.Duration,kotlin.Boolean)` uses a reserved key | ### runOnDeviceAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun runOnDeviceAsync(actionClassName: String): ListenableFuture ``` Runs an on-device action asynchronously inside the target application process. | Parameters | |---|---| | `actionClassName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | class name of the `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceAction` to run | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with the action result | ### runOnDeviceAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun runOnDeviceAsync(actionClassName: String, args: Map): ListenableFuture ``` Runs an on-device action asynchronously inside the target application process. | Parameters | |---|---| | `actionClassName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | class name of the `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceAction` to run | | `args: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html` | arguments to pass to the action. The keys `actionClass`, `argsFile`, `debug` and `redirect_dir` are reserved for the runner; with one of them, the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with the action result | ### runOnDeviceAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun runOnDeviceAsync( actionClassName: String, args: Map, timeout: Duration ): ListenableFuture ``` Runs an on-device action asynchronously inside the target application process. | Parameters | |---|---| | `actionClassName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | class name of the `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceAction` to run | | `args: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html` | arguments to pass to the action. The keys `actionClass`, `argsFile`, `debug` and `redirect_dir` are reserved for the runner; with one of them, the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | `timeout: https://developer.android.com/reference/java/time/Duration.html` | maximum duration to wait for the action to complete. When it expires, the app is force-stopped and a `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupActionResult.Failure` is returned. Must be positive, or the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with the action result | ### runOnDeviceAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun runOnDeviceAsync( actionClassName: String, args: Map, timeout: Duration, waitForDebugger: Boolean ): ListenableFuture ``` Runs an on-device action asynchronously inside the target application process. | Parameters | |---|---| | `actionClassName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | class name of the `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceAction` to run | | `args: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html` | arguments to pass to the action. The keys `actionClass`, `argsFile`, `debug` and `redirect_dir` are reserved for the runner; with one of them, the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | `timeout: https://developer.android.com/reference/java/time/Duration.html` | maximum duration to wait for the action to complete. When it expires, the app is force-stopped and a `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupActionResult.Failure` is returned. Must be positive, or the returned future fails with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. | | `waitForDebugger: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | whether the runner waits for a debugger to attach before running | | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with the action result | ### stopApp ``` suspend fun stopApp(): BackupRestoreController ``` Force-stops the target application on the device via `am force-stop`. | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if stopping the application fails | ### stopAppAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun stopAppAsync(): ListenableFuture ``` Force-stops the target application asynchronously on the device. | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ### uninstallApp ``` suspend fun uninstallApp(): BackupRestoreController ``` Uninstalls the target application from the device via `pm uninstall`, if it is installed. The test APK stays installed. Until `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#installApk(java.nio.file.Path,kotlin.collections.List)` installs the app again, the calls that need it, such as `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runOnDevice(kotlin.String,kotlin.collections.Map,java.time.Duration,kotlin.Boolean)`, `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlow(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode,androidx.test.backup.host.BackupRestoreController)` and `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#launchApp(kotlin.String,kotlin.collections.Map,kotlin.String)`, fail. | Returns | |---|---| | `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController` | this controller instance | | Throws | |---|---| | `https://developer.android.com/reference/java/io/IOException.html` | if uninstalling the application fails | ### uninstallAppAsync Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` fun uninstallAppAsync(): ListenableFuture ``` Uninstalls the target application asynchronously from the device, if it is installed. The test APK stays installed. Until `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#installApkAsync(java.nio.file.Path)` installs the app again, the calls that need it, such as `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runOnDeviceAsync(kotlin.String)`, `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#runBackupRestoreFlowAsync(androidx.test.backup.host.StorageDomain,java.nio.file.Path,androidx.test.backup.host.BackupTransportMode)` and `https://developer.android.com/reference/kotlin/androidx/test/backup/host/BackupRestoreController#launchAppAsync()`, fail. | Returns | |---|---| | `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` | a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with this controller instance | ## Public properties ### apiLevel Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` val apiLevel: Int ``` SDK API level of this device or emulator. ### applicationId Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` val applicationId: String ``` Application ID of the target package under test. ### serialNumber Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04) ``` val serialNumber: String ``` Serial number of this device or emulator.