测试备份

  
自动化测试框架，用于验证用户数据和账号凭证在设备升级和云端恢复后是否安全无损。
最近更新时间 稳定版 候选版 Beta 版 Alpha 版
2026 年 10 月 21 日 - - - 1.0.0-alpha03

声明依赖项

如需添加测试备份的依赖项，您必须将 Google Maven 制品库添加到项目中。如需了解详情，请参阅 Google 的 Maven 代码库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

Groovy

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

Kotlin

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

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

自动备份恢复测试版本 1.0

版本 1.0.0-alpha03

2026 年 10 月 21 日

发布了 androidx.test.backup:backup:1.0.0-alpha03 和 androidx.test.backup:backup-host:1.0.0-alpha03。版本 1.0.0-alpha03 包含这些提交内容。

新功能

  • 简化了 Android Gradle 插件备份测试套件中的测试设置，在省略 @BackupRestoreConfig 时会自动定位到被测应用。(I1452b)
  • 添加了对在 @Nested 测试类中从外部测试类继承 @BackupRestoreConfig 和 @Isolation 设置的支持。(Ia45a8)
  • 添加了对将 BackupRestoreController 直接注入测试类构造函数和 @BeforeAll 设置方法的支持。（I6e822、Ia2ebd）
  • 添加了对使用 androidx.test.backup.device.serial.{role} 属性将特定设备固定到多设备测试中的 @Device 角色的支持。(I484be)

bug 修复

  • 修复了 performBackup 和 performRestore，以便在备份被跳过或为空、备份服务出错或本地备份归档属于其他应用或设备时，测试会立即失败，而不是静默通过。（I7673d、I478ad、I0b989、I9a0ea、I79567）
  • 通过在备份、恢复、设备操作和清理步骤中强制执行超时，修复了测试在无响应设备上无限期挂起的问题。（I10661、I9cdee、If5f92）
  • 修复了 performBackup 在测试运行完成后删除生成的备份文件的问题，现在测试退出后备份归档会保留在磁盘上。(I8c13f)
  • 修复了数据库测试辅助程序 (StorageDomain.Database)，以便正确存储和检查 null 值、在播种测试数据时覆盖现有行、尽早捕获无效的表配置，以及在缺少预期的数据库文件时失败。（Ib4767、Iddf87、I19c43、Ie8d78、I8bc18）
  • 修复了 SharedPreferences 测试辅助程序，以便准确保留数据类型并支持检查 null 或已移除的偏好设置。(I8456d9、I1d0fc2)
  • 修复了 runOnDevice，使其能够处理大型测试载荷而不会崩溃，在启用 waitForDebugger 时暂停调试程序，在自定义测试 APK 软件包名称中查找测试运行程序，并阻止内部运行程序标志泄露到设备操作中。（Ic73bd、Iede17、I1d172、I84c15）
  • 通过在整个测试运行期间共享单个 ADB 连接、每个设备仅安装一次 APK，以及在 APK 无法安装或启动时明确失败，提高了测试稳定性和速度。（I62717、Iabf75、I14e6f、I4c3da5、I54077、Iee84e）
  • 修复了 fetchDeviceLogs 写入空日志文件的问题，并阻止了已取消的测试运行生成虚假失败报告。（I736c4、I7b199、Ia847e）
  • 清理了 backup-host 依赖项，以便调用方可以直接使用 adblib，并且内部日志记录或测试库不再与项目的类路径发生冲突。（I6e822、Iba9a4、Ib4ec9）

版本 1.0.0-alpha02

2026 年 10 月 7 日

发布了 androidx.test.backup:backup:1.0.0-alpha02 和 androidx.test.backup:backup-host:1.0.0-alpha02。版本 1.0.0-alpha02 包含这些提交内容。

API 变更

  • 载荷键现在记录为 BackupActionInputKeys、BackupActionOutputKeys 和 BackupActionValues，取代了 BackupDeviceAction 上的常量。添加了 BackupDeviceActionResult.success() 和 failure() 工厂，以及 isSuccess 和 errorMessage 访问器。(Ibd493)

bug 修复

  • 现在，当 pm clear 未报告成功时，BackupRestoreController.clearAppData 会抛出 IOException，而不是静默继续。(I61556)
  • 现在，传递给 BackupRestoreController 以便在设备上执行的 shell 参数会正确转义，以防止命令注入，并确保安全地处理包含空格的文件路径。
  • 强化了捆绑式存储操作（PopulateStorageAction 和 AssertStorageAction），以防止静默验证通过，从而确保在缺少预期数据时测试严格失败。
  • 主机端测试编排器现在可以正确遵循设备报告的带内操作失败，而不是忽略它们。
  • 修复了数据库行填充问题，方法是对数据库 'values' 传输格式进行百分比编码，以防止载荷传输期间数据损坏。
  • 通过升级依赖项解决了 androidx.test.backup:backup-host 中的安全漏洞。

版本 1.0.0-alpha01

2026 年 9 月 23 日

发布了 androidx.test.backup:backup:1.0.0-alpha01 和 androidx.test.backup:backup-host:1.0.0-alpha01。版本 1.0.0-alpha01 包含这些提交内容。

初始版本的功能

Android 自动备份和恢复测试框架的初始版本。此库提供了一种自动化的端到端方式，用于测试用户数据和账号凭证在设备升级和云端恢复后是否安全无虞。开发者无需依赖手动测试，而是可以自动执行整个生命周期：填充应用状态、根据配置的规则（dataExtractionRules 和 fullBackupContent）进行备份、擦除应用，以及验证恢复后的数据完整性。该框架提供两个工件：androidx.test.backup:backup-host（在主机上运行，用于通过 ADB 编排备份、擦除和恢复过程）和 androidx.test.backup:backup（在设备上运行，用于填充和验证应用数据）。

  • BackupRestoreController：主要的主机端接口，用于控制测试设备的备份、擦除、恢复和验证工作流。提供便捷流水线（例如 runBackupRestoreFlow）以及精细操作（performBackup、performRestore、clearAppData、fetchDeviceLogs 和 runOnDevice）。同时支持 Kotlin 协程和 Java ListenableFuture 异步执行。
  • BackupRestoreExtension：一个 JUnit 5 Jupiter 扩展程序，用于解析 BackupRestoreController 参数并将其注入测试方法。管理独立或共享的 ADB 会话，自动安装受测 APK 和测试 APK，关闭设备锁屏和键盘锁以解锁受凭据保护的存储空间，并强制执行测试沙盒隔离。
  • BackupRestoreTestRunner：在应用沙盒内执行的设备端 Instrumentation 测试运行程序。动态解析并执行由主机编排器分发的请求 BackupDeviceAction 实现，并安全地将大型 JSON 结果载荷重定向到磁盘，以防止 Binder 事务缓冲区限制。
  • BackupDeviceAction：在数据播种 (PHASE_POPULATE) 或恢复后验证 (PHASE_VERIFY) 期间，直接在目标应用沙盒中执行的自定义设备端操作的协定。
  • StorageDomain：强类型描述符（Preference、Database、TextFile 和 BinaryFile）与预构建的操作辅助程序（PopulateStorageAction 和 AssertStorageAction）结合使用，可在凭据保护 (CE) 和设备保护 (DE) 存储上下文中自动播种和断言 SharedPreferences、SQLite 数据库和原始文件，而无需样板代码。
  • BackupTransportMode：指定在测试运行期间要模拟的平台备份传输拓扑，包括 DEVICE_TO_DEVICE（通过 USB 或 WLAN 直连进行实体设备迁移）、CLOUD_ENCRYPTED（采用客户端端到端加密的云端备份）、CLOUD_UNENCRYPTED（标准云端备份）和 LOCAL（离线本地文件系统备份）。
  • @Device 和 @Isolation：主机注解，用于选择与特定序列号、API 级别或多设备角色匹配的已连接设备，以及在测试运行之间配置沙盒隔离政策（IsolationPolicy.AUTOMATIC 与 IsolationPolicy.MANUAL）。