BackupRestoreController

Artifact: androidx.test.backup:backup-host

Kotlin |Java

interface BackupRestoreController : 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 companion properties
`String`	`ACTION_ASSERT_STORAGE` Class name of the prebuilt action that verifies restored data in app storage.
`String`	`ACTION_POPULATE_STORAGE` Class name of the prebuilt action that seeds test data into app storage.
`List<String>`	`DEFAULT_INSTALL_OPTIONS` Default package installation flags: reinstall, allow test, grant all runtime permissions.

Public functions
`suspend BackupRestoreController`	`clearAppData()` Clears application sandbox data on the device via `pm clear`.
`ListenableFuture<BackupRestoreController>`	`clearAppDataAsync()` Clears application sandbox data asynchronously on the device.
`suspend BackupRestoreController`	`clearDeviceLogs()` Clears the device logcat buffer via `logcat -c`.
`ListenableFuture<BackupRestoreController>`	`clearDeviceLogsAsync()` Clears the device logcat buffer asynchronously.
`Unit`	`close()` Closes open resources, including ADB connections.
`suspend BackupRestoreController`	`fetchDeviceLogs(destinationPath: Path, duration: Duration)` Saves recent device logcat entries to a local file.
`ListenableFuture<BackupRestoreController>`	`fetchDeviceLogsAsync(destinationPath: Path)` Saves recent device logcat entries asynchronously to a local file.
`ListenableFuture<BackupRestoreController>`	`fetchDeviceLogsAsync(destinationPath: Path, duration: Duration)` Saves recent device logcat entries asynchronously to a local file.
`suspend BackupRestoreController`	`installApk(apkFile: Path, options: List<String>)` Installs an APK from the host onto the device via `pm install`.
`ListenableFuture<BackupRestoreController>`	`installApkAsync(apkFile: Path)` Installs an APK asynchronously from the host onto the device.
`ListenableFuture<BackupRestoreController>`	`installApkAsync(apkFile: Path, options: List<String>)` Installs an APK asynchronously from the host onto the device.
`suspend BackupRestoreController`	`launchApp( activityClass: String?, intentExtras: Map<String, String>, action: String? )` Starts the target application on the device via `am start`.
`ListenableFuture<BackupRestoreController>`	`launchAppAsync()` Starts the target application asynchronously on the device.
`ListenableFuture<BackupRestoreController>`	`launchAppAsync(activityClass: String?)` Starts the target application asynchronously on the device.
`ListenableFuture<BackupRestoreController>`	`launchAppAsync(activityClass: String?, intentExtras: Map<String, String>)` Starts the target application asynchronously on the device.
`ListenableFuture<BackupRestoreController>`	`launchAppAsync( activityClass: String?, intentExtras: Map<String, String>, action: String? )` Starts the target application asynchronously on the device.
`suspend Path`	`performBackup( mode: BackupTransportMode, outputDir: Path, timeout: Duration )` Captures an application backup archive using the specified transport mode.
`ListenableFuture<Path>`	`performBackupAsync(mode: BackupTransportMode, outputDir: Path)` Captures an application backup archive asynchronously using the specified transport mode.
`ListenableFuture<Path>`	`performBackupAsync( mode: BackupTransportMode, outputDir: Path, timeout: Duration )` Captures an application backup archive asynchronously using the specified transport mode.
`suspend BackupRestoreController`	`performRestore(backupFile: Path, timeout: Duration)` Restores application data from a backup archive.
`ListenableFuture<BackupRestoreController>`	`performRestoreAsync(backupFile: Path)` Restores application data asynchronously from a backup archive.
`ListenableFuture<BackupRestoreController>`	`performRestoreAsync(backupFile: Path, timeout: Duration)` Restores application data asynchronously from a backup archive.
`suspend BackupRestoreController`	`pullFile(devicePath: String, hostDestination: Path)` Copies a file from the device to the host machine via `adb pull`.
`ListenableFuture<BackupRestoreController>`	`pullFileAsync(devicePath: String, hostDestination: Path)` Copies a file asynchronously from the device to the host machine.
`suspend BackupRestoreController`	`runBackupRestoreFlow( storage: StorageDomain, outputDir: Path, mode: BackupTransportMode )` Runs a full backup and restore flow for a single storage domain.
`suspend BackupRestoreController`	`runBackupRestoreFlow( storages: List<StorageDomain>, outputDir: Path, mode: BackupTransportMode )` Runs a full backup and restore flow for multiple storage domains.
`ListenableFuture<BackupRestoreController>`	`runBackupRestoreFlowAsync( storage: StorageDomain, outputDir: Path, mode: BackupTransportMode )` Runs a full backup and restore flow asynchronously for a single storage domain.
`ListenableFuture<BackupRestoreController>`	`runBackupRestoreFlowAsync( storages: List<StorageDomain>, outputDir: Path, mode: BackupTransportMode )` Runs a full backup and restore flow asynchronously for multiple storage domains.
`suspend BackupActionResult`	`runOnDevice( actionClassName: String, args: Map<String, String>, timeout: Duration, waitForDebugger: Boolean )` Runs an on-device action inside the target application process.
`ListenableFuture<BackupActionResult>`	`runOnDeviceAsync(actionClassName: String)` Runs an on-device action asynchronously inside the target application process.
`ListenableFuture<BackupActionResult>`	`runOnDeviceAsync(actionClassName: String, args: Map<String, String>)` Runs an on-device action asynchronously inside the target application process.
`ListenableFuture<BackupActionResult>`	`runOnDeviceAsync( actionClassName: String, args: Map<String, String>, timeout: Duration )` Runs an on-device action asynchronously inside the target application process.
`ListenableFuture<BackupActionResult>`	`runOnDeviceAsync( actionClassName: String, args: Map<String, String>, timeout: Duration, waitForDebugger: Boolean )` Runs an on-device action asynchronously inside the target application process.
`suspend BackupRestoreController`	`stopApp()` Force-stops the target application on the device via `am force-stop`.
`ListenableFuture<BackupRestoreController>`	`stopAppAsync()` Force-stops the target application asynchronously on the device.

Public properties
`Int`	`apiLevel` SDK API level of this device or emulator.
`String`	`applicationId` Application ID of the target package under test.
`String`	`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<String>

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
`BackupRestoreController`	this controller instance

Throws
`IOException`	if clearing application data fails

clearAppDataAsync

Added in 1.0.0-alpha01

fun clearAppDataAsync(): ListenableFuture<BackupRestoreController>

Clears application sandbox data asynchronously on the device.

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

clearDeviceLogs

suspend fun clearDeviceLogs(): BackupRestoreController

Clears the device logcat buffer via logcat -c.

Returns
`BackupRestoreController`	this controller instance

Throws
`IOException`	if clearing the logcat buffer fails

clearDeviceLogsAsync

Added in 1.0.0-alpha01

fun clearDeviceLogsAsync(): ListenableFuture<BackupRestoreController>

Clears the device logcat buffer asynchronously.

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

close

Added in 1.0.0-alpha01

fun close(): Unit

Closes open resources, including ADB connections.

fetchDeviceLogs

suspend fun fetchDeviceLogs(
    destinationPath: Path,
    duration: Duration = Duration.ofSeconds(30)
): BackupRestoreController

Saves recent device logcat entries to a local file.

Parameters
`destinationPath: Path`	local file path where logs will be written
`duration: Duration = Duration.ofSeconds(30)`	time window of historical logs to capture

Returns
`BackupRestoreController`	this controller instance

Throws
`IOException`	if capturing logs fails

fetchDeviceLogsAsync

Added in 1.0.0-alpha01

fun fetchDeviceLogsAsync(destinationPath: Path): ListenableFuture<BackupRestoreController>

Saves recent device logcat entries asynchronously to a local file.

Parameters
`destinationPath: Path`	local file path where logs will be written

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

fetchDeviceLogsAsync

Added in 1.0.0-alpha01

fun fetchDeviceLogsAsync(destinationPath: Path, duration: Duration): ListenableFuture<BackupRestoreController>

Saves recent device logcat entries asynchronously to a local file.

Parameters
`destinationPath: Path`	local file path where logs will be written
`duration: Duration`	time window of historical logs to capture

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

installApk

suspend fun installApk(apkFile: Path, options: List<String> = DEFAULT_INSTALL_OPTIONS): BackupRestoreController

Installs an APK from the host onto the device via pm install.

Parameters
`apkFile: Path`	path to the APK on the host
`options: List<String> = DEFAULT_INSTALL_OPTIONS`	installation flags to pass to package manager

Returns
`BackupRestoreController`	this controller instance

Throws
`IOException`	if package installation fails

installApkAsync

Added in 1.0.0-alpha01

fun installApkAsync(apkFile: Path): ListenableFuture<BackupRestoreController>

Installs an APK asynchronously from the host onto the device.

Parameters
`apkFile: Path`	path to the APK on the host

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

installApkAsync

Added in 1.0.0-alpha01

fun installApkAsync(apkFile: Path, options: List<String>): ListenableFuture<BackupRestoreController>

Installs an APK asynchronously from the host onto the device.

Parameters
`apkFile: Path`	path to the APK on the host
`options: List<String>`	installation flags to pass to package manager

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

launchApp

suspend fun launchApp(
    activityClass: String? = null,
    intentExtras: Map<String, String> = emptyMap(),
    action: String? = null
): BackupRestoreController

Starts the target application on the device via am start.

Parameters
`activityClass: String? = null`	activity class to launch, or null for default launcher activity
`intentExtras: Map<String, String> = emptyMap()`	key-value pairs to pass as intent extras
`action: String? = null`	intent action string to launch with, or null for MAIN

Returns
`BackupRestoreController`	this controller instance

Throws
`IOException`	if starting the application fails

launchAppAsync

Added in 1.0.0-alpha01

fun launchAppAsync(): ListenableFuture<BackupRestoreController>

Starts the target application asynchronously on the device.

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

launchAppAsync

Added in 1.0.0-alpha01

fun launchAppAsync(activityClass: String?): ListenableFuture<BackupRestoreController>

Starts the target application asynchronously on the device.

Parameters
`activityClass: String?`	activity class to launch, or null for default launcher activity

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

launchAppAsync

Added in 1.0.0-alpha01

fun launchAppAsync(activityClass: String?, intentExtras: Map<String, String>): ListenableFuture<BackupRestoreController>

Starts the target application asynchronously on the device.

Parameters
`activityClass: String?`	activity class to launch, or null for default launcher activity
`intentExtras: Map<String, String>`	key-value pairs to pass as intent extras

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

launchAppAsync

Added in 1.0.0-alpha01

fun launchAppAsync(
    activityClass: String?,
    intentExtras: Map<String, String>,
    action: String?
): ListenableFuture<BackupRestoreController>

Starts the target application asynchronously on the device.

Parameters
`activityClass: String?`	activity class to launch, or null for default launcher activity
`intentExtras: Map<String, String>`	key-value pairs to pass as intent extras
`action: String?`	intent action string to launch with

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` 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: BackupTransportMode`	transport mode to test
`outputDir: Path`	directory where the backup archive is saved
`timeout: Duration = Duration.ofMinutes(5)`	maximum duration to wait for the backup to complete

Returns
`Path`	path to the generated backup archive

Throws
`IOException`	if the backup operation fails

performBackupAsync

Added in 1.0.0-alpha01

fun performBackupAsync(mode: BackupTransportMode, outputDir: Path): ListenableFuture<Path>

Captures an application backup archive asynchronously using the specified transport mode.

Parameters
`mode: BackupTransportMode`	transport mode to test
`outputDir: Path`	directory where the backup archive is saved

Returns
`ListenableFuture<Path>`	a `ListenableFuture` with the generated backup path

performBackupAsync

Added in 1.0.0-alpha01

fun performBackupAsync(
    mode: BackupTransportMode,
    outputDir: Path,
    timeout: Duration
): ListenableFuture<Path>

Captures an application backup archive asynchronously using the specified transport mode.

Parameters
`mode: BackupTransportMode`	transport mode to test
`outputDir: Path`	directory where the backup archive is saved
`timeout: Duration`	maximum duration to wait for the backup to complete

Returns
`ListenableFuture<Path>`	a `ListenableFuture` 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: Path`	backup archive generated by `performBackup`
`timeout: Duration = Duration.ofMinutes(5)`	maximum duration to wait for the restore to complete

Returns
`BackupRestoreController`	this controller instance

Throws
`IOException`	if the restore operation fails

performRestoreAsync

Added in 1.0.0-alpha01

fun performRestoreAsync(backupFile: Path): ListenableFuture<BackupRestoreController>

Restores application data asynchronously from a backup archive.

Parameters
`backupFile: Path`	backup archive generated by `performBackup`

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

performRestoreAsync

Added in 1.0.0-alpha01

fun performRestoreAsync(backupFile: Path, timeout: Duration): ListenableFuture<BackupRestoreController>

Restores application data asynchronously from a backup archive.

Parameters
`backupFile: Path`	backup archive generated by `performBackup`
`timeout: Duration`	maximum duration to wait for the restore to complete

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` 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: String`	path to the file on the device
`hostDestination: Path`	path to write the file on the host

Returns
`BackupRestoreController`	this controller instance

Throws
`IOException`	if copying the file fails

pullFileAsync

Added in 1.0.0-alpha01

fun pullFileAsync(devicePath: String, hostDestination: Path): ListenableFuture<BackupRestoreController>

Copies a file asynchronously from the device to the host machine.

Parameters
`devicePath: String`	path to the file on the device
`hostDestination: Path`	path to write the file on the host

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

runBackupRestoreFlow

suspend fun runBackupRestoreFlow(
    storage: StorageDomain,
    outputDir: Path,
    mode: BackupTransportMode
): BackupRestoreController

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
`storage: StorageDomain`	storage domain to seed and verify
`outputDir: Path`	directory where the generated backup file is saved
`mode: BackupTransportMode`	transport mode to test

Returns
`BackupRestoreController`	this controller instance

Throws
`IOException`	if any step fails

runBackupRestoreFlow

suspend fun runBackupRestoreFlow(
    storages: List<StorageDomain>,
    outputDir: Path,
    mode: BackupTransportMode
): BackupRestoreController

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
`storages: List<StorageDomain>`	storage domains to seed and verify
`outputDir: Path`	directory where the generated backup file is saved
`mode: BackupTransportMode`	transport mode to test

Returns
`BackupRestoreController`	this controller instance

Throws
`IOException`	if any step fails

runBackupRestoreFlowAsync

Added in 1.0.0-alpha01

fun runBackupRestoreFlowAsync(
    storage: StorageDomain,
    outputDir: Path,
    mode: BackupTransportMode
): ListenableFuture<BackupRestoreController>

Runs a full backup and restore flow asynchronously for a single storage domain.

Parameters
`storage: StorageDomain`	storage domain to seed and verify
`outputDir: Path`	directory where the generated backup file is saved
`mode: BackupTransportMode`	transport mode to test

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

runBackupRestoreFlowAsync

fun runBackupRestoreFlowAsync(
    storages: List<StorageDomain>,
    outputDir: Path,
    mode: BackupTransportMode
): ListenableFuture<BackupRestoreController>

Runs a full backup and restore flow asynchronously for multiple storage domains.

Parameters
`storages: List<StorageDomain>`	storage domains to seed and verify
`outputDir: Path`	directory where the generated backup file is saved
`mode: BackupTransportMode`	transport mode to test

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

runOnDevice

suspend fun runOnDevice(
    actionClassName: String,
    args: Map<String, String> = emptyMap(),
    timeout: Duration = Duration.ofMinutes(1),
    waitForDebugger: Boolean = false
): BackupActionResult

Runs an on-device action inside the target application process.

Parameters
`actionClassName: String`	class name of the `androidx.test.backup.BackupDeviceAction` to run
`args: Map<String, String> = emptyMap()`	arguments to pass to the action
`timeout: Duration = Duration.ofMinutes(1)`	maximum duration to wait for the action to complete
`waitForDebugger: Boolean = false`	whether the runner waits for a debugger to attach before running

Returns
`BackupActionResult`	result of the action execution

Throws
`IOException`	if communicating with the device fails

runOnDeviceAsync

Added in 1.0.0-alpha01

fun runOnDeviceAsync(actionClassName: String): ListenableFuture<BackupActionResult>

Runs an on-device action asynchronously inside the target application process.

Parameters
`actionClassName: String`	class name of the `androidx.test.backup.BackupDeviceAction` to run

Returns
`ListenableFuture<BackupActionResult>`	a `ListenableFuture` with the action result

runOnDeviceAsync

Added in 1.0.0-alpha01

fun runOnDeviceAsync(actionClassName: String, args: Map<String, String>): ListenableFuture<BackupActionResult>

Runs an on-device action asynchronously inside the target application process.

Parameters
`actionClassName: String`	class name of the `androidx.test.backup.BackupDeviceAction` to run
`args: Map<String, String>`	arguments to pass to the action

Returns
`ListenableFuture<BackupActionResult>`	a `ListenableFuture` with the action result

runOnDeviceAsync

Added in 1.0.0-alpha01

fun runOnDeviceAsync(
    actionClassName: String,
    args: Map<String, String>,
    timeout: Duration
): ListenableFuture<BackupActionResult>

Runs an on-device action asynchronously inside the target application process.

Parameters
`actionClassName: String`	class name of the `androidx.test.backup.BackupDeviceAction` to run
`args: Map<String, String>`	arguments to pass to the action
`timeout: Duration`	maximum duration to wait for the action to complete

Returns
`ListenableFuture<BackupActionResult>`	a `ListenableFuture` with the action result

runOnDeviceAsync

Added in 1.0.0-alpha01

fun runOnDeviceAsync(
    actionClassName: String,
    args: Map<String, String>,
    timeout: Duration,
    waitForDebugger: Boolean
): ListenableFuture<BackupActionResult>

Runs an on-device action asynchronously inside the target application process.

Parameters
`actionClassName: String`	class name of the `androidx.test.backup.BackupDeviceAction` to run
`args: Map<String, String>`	arguments to pass to the action
`timeout: Duration`	maximum duration to wait for the action to complete
`waitForDebugger: Boolean`	whether the runner waits for a debugger to attach before running

Returns
`ListenableFuture<BackupActionResult>`	a `ListenableFuture` with the action result

stopApp

suspend fun stopApp(): BackupRestoreController

Force-stops the target application on the device via am force-stop.

Returns
`BackupRestoreController`	this controller instance

Throws
`IOException`	if stopping the application fails

stopAppAsync

Added in 1.0.0-alpha01

fun stopAppAsync(): ListenableFuture<BackupRestoreController>

Force-stops the target application asynchronously on the device.

Returns
`ListenableFuture<BackupRestoreController>`	a `ListenableFuture` with this controller instance

Public properties

apiLevel

Added in 1.0.0-alpha01

val apiLevel: Int

SDK API level of this device or emulator.

applicationId

Added in 1.0.0-alpha01

val applicationId: String

Application ID of the target package under test.

serialNumber

Added in 1.0.0-alpha01

val serialNumber: String

Serial number of this device or emulator.