BackupRestoreController

public interface BackupRestoreController extends AutoCloseable

Controls backup, restore, and verification workflows for a test device.

Provides operations to seed test data with runOnDevice, run backups with performBackup, wipe app data with clearAppData, and restore data with performRestore.

Summary

Public fields
default static final @NonNull String

Class name of the prebuilt action that verifies restored data in app storage.
default static final @NonNull String

Class name of the prebuilt action that seeds test data into app storage.
default static final @NonNull List<@NonNull String>

Default package installation flags: reinstall, allow test, grant all runtime permissions.

Public methods
abstract @NonNull BackupRestoreController

Clears application sandbox data on the device via pm clear.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>

Clears application sandbox data asynchronously on the device.
abstract @NonNull BackupRestoreController

Clears the device logcat buffer via logcat -c.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>

Clears the device logcat buffer asynchronously.
abstract void

Releases the resources held by this controller.
abstract @NonNull BackupRestoreController
fetchDeviceLogs(@NonNull Path destinationPath, @NonNull Duration duration)

Saves recent device logcat entries to a local file.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>
fetchDeviceLogsAsync(@NonNull Path destinationPath)

Saves recent device logcat entries asynchronously to a local file.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>
fetchDeviceLogsAsync(
    @NonNull Path destinationPath,
    @NonNull Duration duration
)

Saves recent device logcat entries asynchronously to a local file.
abstract int

SDK API level of this device or emulator.
abstract @NonNull String

Application ID of the target package under test.
abstract @NonNull String

Serial number of this device or emulator.
abstract @NonNull BackupRestoreController
installApk(@NonNull Path apkFile, @NonNull List<@NonNull String> options)

Installs an APK from the host onto the device via pm install.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>

Installs an APK asynchronously from the host onto the device.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>
installApkAsync(
    @NonNull Path apkFile,
    @NonNull List<@NonNull String> options
)

Installs an APK asynchronously from the host onto the device.
abstract @NonNull BackupRestoreController
launchApp(
    String activityClass,
    @NonNull Map<@NonNull String, @NonNull String> intentExtras,
    String action
)

Starts the target application on the device via am start.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>

Starts the target application asynchronously on the device.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>
launchAppAsync(String activityClass)

Starts the target application asynchronously on the device.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>
launchAppAsync(
    String activityClass,
    @NonNull Map<@NonNull String, @NonNull String> intentExtras
)

Starts the target application asynchronously on the device.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>
launchAppAsync(
    String activityClass,
    @NonNull Map<@NonNull String, @NonNull String> intentExtras,
    String action
)

Starts the target application asynchronously on the device.
abstract @NonNull Path
performBackup(
    @NonNull BackupTransportMode mode,
    @NonNull Path outputDir,
    @NonNull Duration timeout
)

Captures an application backup archive using the specified transport mode.
abstract @NonNull ListenableFuture<@NonNull Path>
performBackupAsync(
    @NonNull BackupTransportMode mode,
    @NonNull Path outputDir
)

Captures an application backup archive asynchronously using the specified transport mode.
abstract @NonNull ListenableFuture<@NonNull Path>
performBackupAsync(
    @NonNull BackupTransportMode mode,
    @NonNull Path outputDir,
    @NonNull Duration timeout
)

Captures an application backup archive asynchronously using the specified transport mode.
abstract @NonNull BackupRestoreController
performRestore(@NonNull Path backupFile, @NonNull Duration timeout)

Restores application data from a backup archive.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>

Restores application data asynchronously from a backup archive.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>
performRestoreAsync(@NonNull Path backupFile, @NonNull Duration timeout)

Restores application data asynchronously from a backup archive.
abstract @NonNull BackupRestoreController
pullFile(@NonNull String devicePath, @NonNull Path hostDestination)

Copies a file from the device to the host machine via adb pull.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>
pullFileAsync(@NonNull String devicePath, @NonNull Path hostDestination)

Copies a file asynchronously from the device to the host machine.
abstract @NonNull BackupRestoreController
runBackupRestoreFlow(
    @NonNull StorageDomain storage,
    @NonNull Path outputDir,
    @NonNull BackupTransportMode mode
)

Runs a full backup and restore flow for a single storage domain.
abstract @NonNull BackupRestoreController
runBackupRestoreFlow(
    @NonNull List<@NonNull StorageDomain> storages,
    @NonNull Path outputDir,
    @NonNull BackupTransportMode mode
)

Runs a full backup and restore flow for multiple storage domains.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>
runBackupRestoreFlowAsync(
    @NonNull StorageDomain storage,
    @NonNull Path outputDir,
    @NonNull BackupTransportMode mode
)

Runs a full backup and restore flow asynchronously for a single storage domain.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>
runBackupRestoreFlowAsync(
    @NonNull List<@NonNull StorageDomain> storages,
    @NonNull Path outputDir,
    @NonNull BackupTransportMode mode
)

Runs a full backup and restore flow asynchronously for multiple storage domains.
abstract @NonNull BackupActionResult
runOnDevice(
    @NonNull String actionClassName,
    @NonNull Map<@NonNull String, @NonNull String> args,
    @NonNull Duration timeout,
    boolean waitForDebugger
)

Runs an on-device action inside the target application process.
abstract @NonNull ListenableFuture<@NonNull BackupActionResult>
runOnDeviceAsync(@NonNull String actionClassName)

Runs an on-device action asynchronously inside the target application process.
abstract @NonNull ListenableFuture<@NonNull BackupActionResult>
runOnDeviceAsync(
    @NonNull String actionClassName,
    @NonNull Map<@NonNull String, @NonNull String> args
)

Runs an on-device action asynchronously inside the target application process.
abstract @NonNull ListenableFuture<@NonNull BackupActionResult>
runOnDeviceAsync(
    @NonNull String actionClassName,
    @NonNull Map<@NonNull String, @NonNull String> args,
    @NonNull Duration timeout
)

Runs an on-device action asynchronously inside the target application process.
abstract @NonNull ListenableFuture<@NonNull BackupActionResult>
runOnDeviceAsync(
    @NonNull String actionClassName,
    @NonNull Map<@NonNull String, @NonNull String> args,
    @NonNull Duration timeout,
    boolean waitForDebugger
)

Runs an on-device action asynchronously inside the target application process.
abstract @NonNull BackupRestoreController

Force-stops the target application on the device via am force-stop.
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController>

Force-stops the target application asynchronously on the device.

Public fields

ACTION_ASSERT_STORAGE

default static final @NonNull String ACTION_ASSERT_STORAGE

Class name of the prebuilt action that verifies restored data in app storage.

ACTION_POPULATE_STORAGE

default static final @NonNull String ACTION_POPULATE_STORAGE

Class name of the prebuilt action that seeds test data into app storage.

DEFAULT_INSTALL_OPTIONS

default static final @NonNull List<@NonNull String> DEFAULT_INSTALL_OPTIONS

Default package installation flags: reinstall, allow test, grant all runtime permissions.

Public methods

clearAppData

abstract @NonNull BackupRestoreController clearAppData()

Clears application sandbox data on the device via pm clear.

Returns
@NonNull BackupRestoreController

this controller instance
Throws
IOException

if clearing application data fails

clearAppDataAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> clearAppDataAsync()

Clears application sandbox data asynchronously on the device.

Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

clearDeviceLogs

abstract @NonNull BackupRestoreController clearDeviceLogs()

Clears the device logcat buffer via logcat -c.

Returns
@NonNull BackupRestoreController

this controller instance
Throws
IOException

if clearing the logcat buffer fails

clearDeviceLogsAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> clearDeviceLogsAsync()

Clears the device logcat buffer asynchronously.

Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

close

Added in 1.0.0-alpha03
abstract void close()

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

abstract @NonNull BackupRestoreController fetchDeviceLogs(@NonNull Path destinationPath, @NonNull Duration duration)

Saves recent device logcat entries to a local file.

Parameters
@NonNull Path destinationPath

local file path where logs will be written
@NonNull Duration duration

time window of historical logs to capture
Returns
@NonNull BackupRestoreController

this controller instance
Throws
IOException

if capturing logs fails

fetchDeviceLogsAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> fetchDeviceLogsAsync(@NonNull Path destinationPath)

Saves recent device logcat entries asynchronously to a local file.

Parameters
@NonNull Path destinationPath

local file path where logs will be written
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

fetchDeviceLogsAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> fetchDeviceLogsAsync(
    @NonNull Path destinationPath,
    @NonNull Duration duration
)

Saves recent device logcat entries asynchronously to a local file.

Parameters
@NonNull Path destinationPath

local file path where logs will be written
@NonNull Duration duration

time window of historical logs to capture
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

getApiLevel

Added in 1.0.0-alpha03
abstract int getApiLevel()

SDK API level of this device or emulator.

getApplicationId

Added in 1.0.0-alpha03
abstract @NonNull String getApplicationId()

Application ID of the target package under test.

getSerialNumber

Added in 1.0.0-alpha03
abstract @NonNull String getSerialNumber()

Serial number of this device or emulator.

installApk

abstract @NonNull BackupRestoreController installApk(@NonNull Path apkFile, @NonNull List<@NonNull String> options)

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

Parameters
@NonNull Path apkFile

path to the APK on the host
@NonNull List<@NonNull String> options

installation flags to pass to package manager
Returns
@NonNull BackupRestoreController

this controller instance
Throws
IOException

if package installation fails

installApkAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> installApkAsync(@NonNull Path apkFile)

Installs an APK asynchronously from the host onto the device.

Parameters
@NonNull Path apkFile

path to the APK on the host
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

installApkAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> installApkAsync(
    @NonNull Path apkFile,
    @NonNull List<@NonNull String> options
)

Installs an APK asynchronously from the host onto the device.

Parameters
@NonNull Path apkFile

path to the APK on the host
@NonNull List<@NonNull String> options

installation flags to pass to package manager
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

launchApp

abstract @NonNull BackupRestoreController launchApp(
    String activityClass,
    @NonNull Map<@NonNull String, @NonNull String> intentExtras,
    String action
)

Starts the target application on the device via am start.

Parameters
String activityClass

activity class to launch, or null for default launcher activity
@NonNull Map<@NonNull String, @NonNull String> intentExtras

key-value pairs to pass as intent extras
String action

intent action string to launch with, or null for MAIN
Returns
@NonNull BackupRestoreController

this controller instance
Throws
IOException

if starting the application fails

launchAppAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> launchAppAsync()

Starts the target application asynchronously on the device.

Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

launchAppAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> launchAppAsync(String activityClass)

Starts the target application asynchronously on the device.

Parameters
String activityClass

activity class to launch, or null for default launcher activity
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

launchAppAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> launchAppAsync(
    String activityClass,
    @NonNull Map<@NonNull String, @NonNull String> intentExtras
)

Starts the target application asynchronously on the device.

Parameters
String activityClass

activity class to launch, or null for default launcher activity
@NonNull Map<@NonNull String, @NonNull String> intentExtras

key-value pairs to pass as intent extras
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

launchAppAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> launchAppAsync(
    String activityClass,
    @NonNull Map<@NonNull String, @NonNull String> intentExtras,
    String action
)

Starts the target application asynchronously on the device.

Parameters
String activityClass

activity class to launch, or null for default launcher activity
@NonNull Map<@NonNull String, @NonNull String> intentExtras

key-value pairs to pass as intent extras
String action

intent action string to launch with
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

performBackup

abstract @NonNull Path performBackup(
    @NonNull BackupTransportMode mode,
    @NonNull Path outputDir,
    @NonNull Duration timeout
)

Captures an application backup archive using the specified transport mode.

Parameters
@NonNull BackupTransportMode mode

transport mode to test
@NonNull Path outputDir

directory where the backup archive is saved
@NonNull Duration timeout

maximum duration to wait for the backup to complete. When it expires, the app is force-stopped and the backup fails with an IOException. Must be positive.
Returns
@NonNull Path

path to the generated backup archive. A BackupTransportMode.LOCAL archive only marks the backup, whose data stays on the device.
Throws
IOException

if the backup operation fails, or the app does not allow backups
IllegalArgumentException

if timeout is not positive

performBackupAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull Path> performBackupAsync(
    @NonNull BackupTransportMode mode,
    @NonNull Path outputDir
)

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

Parameters
@NonNull BackupTransportMode mode

transport mode to test
@NonNull Path outputDir

directory where the backup archive is saved
Returns
@NonNull ListenableFuture<@NonNull Path>

a ListenableFuture with the generated backup path

performBackupAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull Path> performBackupAsync(
    @NonNull BackupTransportMode mode,
    @NonNull Path outputDir,
    @NonNull Duration timeout
)

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

Parameters
@NonNull BackupTransportMode mode

transport mode to test
@NonNull Path outputDir

directory where the backup archive is saved
@NonNull Duration timeout

maximum duration to wait for the backup to complete. When it expires, the app is force-stopped and the backup fails with an IOException. Must be positive, or the returned future fails with an IllegalArgumentException.
Returns
@NonNull ListenableFuture<@NonNull Path>

a ListenableFuture with the generated backup path

performRestore

abstract @NonNull BackupRestoreController performRestore(@NonNull Path backupFile, @NonNull Duration timeout)

Restores application data from a backup archive.

Parameters
@NonNull Path backupFile

backup archive generated by performBackup
@NonNull Duration timeout

maximum duration to wait for the restore to complete. When it expires, the app is force-stopped and the restore fails with an IOException. Must be positive.
Returns
@NonNull BackupRestoreController

this controller instance
Throws
IOException

if the restore operation fails or restores no app data, if Google Play services on the device is too old to restore backupFile, or if backupFile is a BackupTransportMode.LOCAL archive of another app or of another device
IllegalArgumentException

if timeout is not positive

performRestoreAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> performRestoreAsync(@NonNull Path backupFile)

Restores application data asynchronously from a backup archive.

Parameters
@NonNull Path backupFile

backup archive generated by performBackup
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

performRestoreAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> performRestoreAsync(@NonNull Path backupFile, @NonNull Duration timeout)

Restores application data asynchronously from a backup archive.

Parameters
@NonNull Path backupFile

backup archive generated by performBackup
@NonNull Duration timeout

maximum duration to wait for the restore to complete. When it expires, the app is force-stopped and the restore fails with an IOException. Must be positive, or the returned future fails with an IllegalArgumentException.
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

pullFile

abstract @NonNull BackupRestoreController pullFile(@NonNull String devicePath, @NonNull Path hostDestination)

Copies a file from the device to the host machine via adb pull.

Parameters
@NonNull String devicePath

path to the file on the device
@NonNull Path hostDestination

path to write the file on the host
Returns
@NonNull BackupRestoreController

this controller instance
Throws
IOException

if copying the file fails

pullFileAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> pullFileAsync(@NonNull String devicePath, @NonNull Path hostDestination)

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

Parameters
@NonNull String devicePath

path to the file on the device
@NonNull Path hostDestination

path to write the file on the host
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

runBackupRestoreFlow

abstract @NonNull BackupRestoreController runBackupRestoreFlow(
    @NonNull StorageDomain storage,
    @NonNull Path outputDir,
    @NonNull BackupTransportMode mode
)

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

Seeds test data into storage using ACTION_POPULATE_STORAGE, runs a backup to outputDir using mode, clears app data, restores the backup archive, and verifies data integrity using ACTION_ASSERT_STORAGE.

Parameters
@NonNull StorageDomain storage

storage domain to seed and verify
@NonNull Path outputDir

directory where the generated backup file is saved
@NonNull BackupTransportMode mode

transport mode to test
Returns
@NonNull BackupRestoreController

this controller instance
Throws
IOException

if any step fails

runBackupRestoreFlow

abstract @NonNull BackupRestoreController runBackupRestoreFlow(
    @NonNull List<@NonNull StorageDomain> storages,
    @NonNull Path outputDir,
    @NonNull BackupTransportMode mode
)

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

Seeds each domain in storages using ACTION_POPULATE_STORAGE, runs a backup to outputDir using mode, clears app data, restores the backup archive, and verifies each domain using ACTION_ASSERT_STORAGE.

Parameters
@NonNull List<@NonNull StorageDomain> storages

storage domains to seed and verify
@NonNull Path outputDir

directory where the generated backup file is saved
@NonNull BackupTransportMode mode

transport mode to test
Returns
@NonNull BackupRestoreController

this controller instance
Throws
IOException

if any step fails

runBackupRestoreFlowAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> runBackupRestoreFlowAsync(
    @NonNull StorageDomain storage,
    @NonNull Path outputDir,
    @NonNull BackupTransportMode mode
)

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

Parameters
@NonNull StorageDomain storage

storage domain to seed and verify
@NonNull Path outputDir

directory where the generated backup file is saved
@NonNull BackupTransportMode mode

transport mode to test
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

runBackupRestoreFlowAsync

abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> runBackupRestoreFlowAsync(
    @NonNull List<@NonNull StorageDomain> storages,
    @NonNull Path outputDir,
    @NonNull BackupTransportMode mode
)

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

Parameters
@NonNull List<@NonNull StorageDomain> storages

storage domains to seed and verify
@NonNull Path outputDir

directory where the generated backup file is saved
@NonNull BackupTransportMode mode

transport mode to test
Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance

runOnDevice

abstract @NonNull BackupActionResult runOnDevice(
    @NonNull String actionClassName,
    @NonNull Map<@NonNull String, @NonNull String> args,
    @NonNull Duration timeout,
    boolean waitForDebugger
)

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

Parameters
@NonNull String actionClassName

class name of the androidx.test.backup.BackupDeviceAction to run
@NonNull Map<@NonNull String, @NonNull String> args

arguments to pass to the action. The keys actionClass, argsFile, debug and redirect_dir are reserved for the runner.
@NonNull Duration timeout

maximum duration to wait for the action to complete. When it expires, the app is force-stopped and a BackupActionResult.Failure is returned. Must be positive.
boolean waitForDebugger

whether the runner waits for a debugger to attach before running
Returns
@NonNull BackupActionResult

result of the action execution
Throws
IOException

if communicating with the device fails
IllegalArgumentException

if timeout is not positive, or if args uses a reserved key

runOnDeviceAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> runOnDeviceAsync(@NonNull String actionClassName)

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

Parameters
@NonNull String actionClassName

class name of the androidx.test.backup.BackupDeviceAction to run
Returns
@NonNull ListenableFuture<@NonNull BackupActionResult>

a ListenableFuture with the action result

runOnDeviceAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> runOnDeviceAsync(
    @NonNull String actionClassName,
    @NonNull Map<@NonNull String, @NonNull String> args
)

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

Parameters
@NonNull String actionClassName

class name of the androidx.test.backup.BackupDeviceAction to run
@NonNull Map<@NonNull String, @NonNull String> args

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 IllegalArgumentException.
Returns
@NonNull ListenableFuture<@NonNull BackupActionResult>

a ListenableFuture with the action result

runOnDeviceAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> runOnDeviceAsync(
    @NonNull String actionClassName,
    @NonNull Map<@NonNull String, @NonNull String> args,
    @NonNull Duration timeout
)

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

Parameters
@NonNull String actionClassName

class name of the androidx.test.backup.BackupDeviceAction to run
@NonNull Map<@NonNull String, @NonNull String> args

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 IllegalArgumentException.
@NonNull Duration timeout

maximum duration to wait for the action to complete. When it expires, the app is force-stopped and a BackupActionResult.Failure is returned. Must be positive, or the returned future fails with an IllegalArgumentException.
Returns
@NonNull ListenableFuture<@NonNull BackupActionResult>

a ListenableFuture with the action result

runOnDeviceAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupActionResult> runOnDeviceAsync(
    @NonNull String actionClassName,
    @NonNull Map<@NonNull String, @NonNull String> args,
    @NonNull Duration timeout,
    boolean waitForDebugger
)

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

Parameters
@NonNull String actionClassName

class name of the androidx.test.backup.BackupDeviceAction to run
@NonNull Map<@NonNull String, @NonNull String> args

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 IllegalArgumentException.
@NonNull Duration timeout

maximum duration to wait for the action to complete. When it expires, the app is force-stopped and a BackupActionResult.Failure is returned. Must be positive, or the returned future fails with an IllegalArgumentException.
boolean waitForDebugger

whether the runner waits for a debugger to attach before running
Returns
@NonNull ListenableFuture<@NonNull BackupActionResult>

a ListenableFuture with the action result

stopApp

abstract @NonNull BackupRestoreController stopApp()

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

Returns
@NonNull BackupRestoreController

this controller instance
Throws
IOException

if stopping the application fails

stopAppAsync

Added in 1.0.0-alpha03
abstract @NonNull ListenableFuture<@NonNull BackupRestoreController> stopAppAsync()

Force-stops the target application asynchronously on the device.

Returns
@NonNull ListenableFuture<@NonNull BackupRestoreController>

a ListenableFuture with this controller instance