Test Backup

Declaring dependencies

To add a dependency on test backup, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

dependencies {
    implementation "androidx.test.backup:backup:1.0.0-alpha03"
    implementation "androidx.test.backup:backup-host:1.0.0-alpha03"
}

dependencies {
    implementation("androidx.test.backup:backup:1.0.0-alpha03")
    implementation("androidx.test.backup:backup-host:1.0.0-alpha03")
}

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Backup

Version 1.0

Version 1.0.0-alpha02

October 07, 2026

androidx.test.backup:backup:1.0.0-alpha02 and androidx.test.backup:backup-host:1.0.0-alpha02 are released. Version 1.0.0-alpha02 contains these commits.

API Changes

• Payload keys are now documented as BackupActionInputKeys, BackupActionOutputKeys, and BackupActionValues, replacing the constants on BackupDeviceAction. Added BackupDeviceActionResult.success() and failure() factories, along with isSuccess and errorMessage accessors. (Ibd493)

Bug Fixes

• BackupRestoreController.clearAppData now throws IOException when pm clear does not report success, instead of continuing silently. (I61556)
• Shell arguments passed to BackupRestoreController for device execution are now correctly escaped to prevent command injection and ensure file paths with spaces are handled securely.
• Hardened the bundled storage actions (PopulateStorageAction and AssertStorageAction) against silent verification passes to ensure tests strictly fail when expected data is missing.
• Host-side test orchestrators now correctly honor in-band action failures reported by the device instead of ignoring them.
• Fixed an issue with database row population by percent-encoding the database 'values' wire format, preventing data corruption during payload transport.
• Addressed security vulnerabilities in androidx.test.backup:backup-host by upgrading dependencies.

Automated Backup Restore Test Version 1.0

Version 1.0.0-alpha03

October 21, 2026

androidx.test.backup:backup:1.0.0-alpha03 and androidx.test.backup:backup-host:1.0.0-alpha03 are released. Version 1.0.0-alpha03 contains these commits.

New Features

• Simplified test setup in Android Gradle Plugin backup test suites by automatically targeting the tested app when @BackupRestoreConfig is omitted. (I1452b)
• Added support for inheriting @BackupRestoreConfig and @Isolation settings from an outer test class in @Nested test classes. (Ia45a8)
• Added support for injecting BackupRestoreController directly into test class constructors and @BeforeAll setup methods. (I6e822, Ia2ebd)
• Added support for pinning a specific device to a @Device role in multi-device tests using the androidx.test.backup.device.serial.{role} property. (I484be)

Bug Fixes

• Fixed performBackup and performRestore so tests fail immediately instead of passing silently when a backup is skipped or empty, when the backup service errors out, or when a local backup archive belongs to a different app or device. (I7673d, I478ad, I0b989, I9a0ea, I79567)
• Fixed tests hanging indefinitely on unresponsive devices by enforcing timeouts across backup, restore, device actions, and cleanup steps. (I10661, I9cdee, If5f92)
• Fixed performBackup deleting generated backup files when the test run finished, so backup archives are now kept on disk after tests exit. (I8c13f)
• Fixed database test helpers (StorageDomain.Database) to properly store and check null values, overwrite existing rows when seeding test data, catch invalid table configurations early, and fail when an expected database file is missing. (Ib4767, Iddf87, I19c43, Ie8d78, I8bc18)
• Fixed SharedPreferences test helpers to preserve data types accurately and support checking for null or removed preferences. (I8456d9, I1d0fc2)
• Fixed runOnDevice to handle large test payloads without crashing, pause for the debugger when waitForDebugger is enabled, find the test runner in custom test APK package names, and block internal runner flags from leaking into device actions. (Ic73bd, Iede17, I1d172, I84c15)
• Improved test stability and speed by sharing a single ADB connection across the test run, installing APKs only once per device, and failing clearly when an APK fails to install or launch. (I62717, Iabf75, I14e6f, I4c3da5, I54077, Iee84e)
• Fixed fetchDeviceLogs writing empty log files, and stopped cancelled test runs from generating false failure reports. (I736c4, I7b199, Ia847e)
• Cleaned up backup-host dependencies so adblib is available directly to callers and internal logging or test libraries no longer clash with your project's classpath. (I6e822, Iba9a4, Ib4ec9)

Version 1.0.0-alpha01

September 23, 2026

androidx.test.backup:backup:1.0.0-alpha01 and androidx.test.backup:backup-host:1.0.0-alpha01 are released. Version 1.0.0-alpha01 contains these commits.

Features of Initial Release

Initial release of the Automated Backup and Restore Testing framework for Android. This library provides an automated, end-to-end way to test that user data and account credentials safely survive device upgrades and cloud restores. Instead of relying on manual testing, developers can automate the full lifecycle: seeding app state, backing it up according to your configured rules (dataExtractionRules and fullBackupContent), wiping the app, and verifying post-restore data integrity. The framework provides two artifacts: androidx.test.backup:backup-host (which runs on the host computer to orchestrate backup, wipe, and restore passes over ADB) and androidx.test.backup:backup (which runs on the device to populate and verify app data).

• BackupRestoreController: The primary host-side interface used to control backup, wipe, restore, and verification workflows for a test device. Provides convenience pipelines such as runBackupRestoreFlow as well as fine-grained operations (performBackup, performRestore, clearAppData, fetchDeviceLogs, and runOnDevice). Supports both Kotlin coroutines and Java ListenableFuture asynchronous execution.
• BackupRestoreExtension: A JUnit 5 Jupiter extension that resolves and injects BackupRestoreController parameters into test methods. Manages standalone or shared ADB sessions, automatically installs tested and test APKs, dismisses device lockscreens and keyguards to unlock credential-protected storage, and enforces test sandbox isolation.
• BackupRestoreTestRunner: An on-device Instrumentation test runner executing inside the application sandbox. Dynamically resolves and executes requested BackupDeviceAction implementations dispatched by host orchestrators and safely redirects large JSON result payloads to disk to prevent Binder transaction buffer limits.
• BackupDeviceAction: The contract for custom device-side actions executing directly within the target application sandbox during data seeding (PHASE_POPULATE) or post-restore validation (PHASE_VERIFY).
• StorageDomain: Strongly typed descriptors (Preference, Database, TextFile, and BinaryFile) used alongside prebuilt action helpers (PopulateStorageAction and AssertStorageAction) to automatically seed and assert SharedPreferences, SQLite databases, and raw files across both Credential Protected (CE) and Device Protected (DE) storage contexts without boilerplate.
• BackupTransportMode: Specifies the platform backup transport topology to simulate during test passes, including DEVICE_TO_DEVICE (physical device migration via USB or Wi-Fi Direct), CLOUD_ENCRYPTED (cloud backup with client-side end-to-end encryption), CLOUD_UNENCRYPTED (standard cloud backup), and LOCAL (offline local filesystem backup).
• @Device and @Isolation: Host annotations for selecting connected devices matching specific serials, API levels, or multi-device roles, and configuring sandbox isolation policies between test runs (IsolationPolicy.AUTOMATIC vs. IsolationPolicy.MANUAL).