測試備份

  
自動化測試架構，可驗證使用者資料和帳戶憑證在裝置升級和雲端還原後，是否仍安全無虞。
最近更新時間 穩定版 候選版 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")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

自動備份還原測試 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)

修正錯誤

  • 修正 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)

修正錯誤

  • pm clear 未回報成功時，BackupRestoreController.clearAppData 現在會擲回 IOException，而不是繼續執行。(I61556)
  • 傳遞至 BackupRestoreController 以在裝置上執行的殼層引數現在會正確逸出，防止指令插入，並確保含有空格的檔案路徑能安全處理。
  • 強化套裝儲存動作 (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、關閉裝置螢幕鎖定和按鍵鎖，解鎖受憑證保護的儲存空間，以及強制執行測試沙箱隔離。
  • 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 或 Wi-Fi Direct 遷移實體裝置)、CLOUD_ENCRYPTED (採用用戶端端對端加密的雲端備份)、CLOUD_UNENCRYPTED (標準雲端備份) 和 LOCAL (離線本機檔案系統備份)。
  • @Device 和 @Isolation：主機註解，用於選取符合特定序號、API 級別或支援多種裝置角色的連結裝置，以及設定測試執行之間的沙箱隔離政策 (IsolationPolicy.AUTOMATIC 與 IsolationPolicy.MANUAL)。