Kiểm thử tự động chức năng sao lưu và khôi phục

Khi người dùng thiết lập thiết bị mới hoặc cài đặt lại ứng dụng, Android có thể khôi phục dữ liệu của ứng dụng từ bản sao lưu trên đám mây hoặc quá trình chuyển dữ liệu từ thiết bị này sang thiết bị khác. Nếu quy tắc sao lưu của bạn bỏ qua dữ liệu quan trọng hoặc ứng dụng của bạn không thể sử dụng dữ liệu mà ứng dụng khôi phục, thì người dùng sẽ mất chế độ cài đặt và tiến trình mà không thấy lỗi.

Các chương trình kiểm thử sao lưu và khôi phục tự động giúp bạn phát hiện những vấn đề này trước khi phát hành ứng dụng. Đó là các chương trình kiểm thử JUnit 5 chạy trên máy phát triển và điều khiển các thiết bị thông minh thông qua Cầu gỡ lỗi Android (adb). Mỗi quy trình kiểm thử sẽ gieo dữ liệu ứng dụng trên một thiết bị, sao lưu và khôi phục ứng dụng thông qua khung sao lưu của Android, sau đó kiểm tra để đảm bảo dữ liệu còn nguyên vẹn. Bạn định cấu hình các kiểm thử dưới dạng bộ kiểm thử của trình bổ trợ Android cho Gradle (AGP) trong tệp bản dựng của mô-đun.

Cách hoạt động

Bộ kiểm thử sao lưu và khôi phục có hai phần hoạt động cùng nhau:

  • Kiểm thử máy chủ là các kiểm thử JUnit 5 chạy trên máy phát triển của bạn. Họ sử dụng một BackupRestoreController cho mỗi thiết bị để gieo dữ liệu, sao lưu và khôi phục ứng dụng, đồng thời kiểm tra kết quả.
  • Hành động trên thiết bị là các lớp triển khai BackupDeviceAction. Các SDK này chạy trong quy trình của ứng dụng trên thiết bị, vì vậy, chúng có thể đọc và ghi dữ liệu thông qua mã của ứng dụng. Các chương trình kiểm thử máy chủ gọi các thao tác trên thiết bị theo tên lớp.

Khi bạn chạy bộ kiểm thử, AGP sẽ tạo ứng dụng và một tệp APK kiểm thử chứa các hành động trên thiết bị. Khung kiểm thử cài đặt cả hai tệp APK trên mỗi thiết bị mà kiểm thử sử dụng và xoá dữ liệu của ứng dụng trước mỗi lần kiểm thử.

Các loại bộ nhớ tích hợp sẵn

Bảng sau đây liệt kê các lớp con StorageDomain cho phép bạn gieo và xác minh dữ liệu mà không cần viết hành động trên thiết bị:

Miền lưu trữ Dữ liệu
StorageDomain.Preference Khoá trong tệp SharedPreferences.
StorageDomain.DataStorePreference Khoá trong tệp Preferences DataStore.
StorageDomain.Database Một hàng trong bảng cơ sở dữ liệu SQLite.
StorageDomain.TextFile Một tệp văn bản trong bộ nhớ trong của ứng dụng.
StorageDomain.BinaryFile Tệp nhị phân trong bộ nhớ trong của ứng dụng.
StorageDomain.ExcludedData Một miền lưu trữ tích hợp khác có dữ liệu không nên được khôi phục, chẳng hạn như dữ liệu bị loại trừ theo quy tắc sao lưu của bạn.

Để kiểm thử dữ liệu khác, chẳng hạn như tệp Proto DataStore hoặc cơ sở dữ liệu Room, hãy ghi thao tác trên thiết bị.

Phương tiện đi lại

Mỗi bản sao lưu đều sử dụng một giá trị BackupTransportMode. Bảng sau đây liệt kê các phương tiện đi lại được hỗ trợ:

Chế độ Trường hợp
LOCAL Bản sao lưu vào phương tiện sao lưu cục bộ của thiết bị. Dữ liệu sao lưu vẫn nằm trên thiết bị.
CLOUD_ENCRYPTED Bản sao lưu trên đám mây, chẳng hạn như bản sao lưu được lưu vào Tài khoản Google của người dùng từ một thiết bị có tính năng mã hoá phía máy khách.
CLOUD_UNENCRYPTED Bản sao lưu trên đám mây từ một thiết bị không có tính năng mã hoá phía máy khách.
DEVICE_TO_DEVICE Chuyển dữ liệu từ thiết bị này sang thiết bị khác, chẳng hạn như qua cáp hoặc Wi-Fi.

LOCAL hoạt động trên mọi thiết bị được hỗ trợ. Chế độ đám mây và chế độ thiết bị với thiết bị tạo ra các bản sao lưu giống như thao tác Sao lưu dữ liệu ứng dụng trong Android Studio: bản sao lưu được lưu vào máy phát triển thay vì được tải lên hoặc gửi đến một thiết bị khác. Chế độ đám mây và chế độ thiết bị với thiết bị yêu cầu Dịch vụ Google Play trên thiết bị và một bản dựng có thể gỡ lỗi của ứng dụng. Nếu quy tắc sao lưu của bạn phụ thuộc vào phương thức mã hoá phía máy khách, hãy kiểm thử cả hai chế độ đám mây.

Yêu cầu

Để sử dụng tính năng kiểm thử sao lưu và khôi phục tự động, hãy đảm bảo rằng môi trường của bạn đáp ứng các yêu cầu sau:

  • Gradle phiên bản 9.6.0 trở lên.
  • JDK phiên bản 17 trở lên.
  • Thiết bị hoặc trình mô phỏng chạy Android 12 (cấp độ API 31) trở lên được kết nối thông qua adb:
    • Thiết bị hoặc trình mô phỏng ở cấp độ API 36.1 trở lên yêu cầu Dịch vụ Google Play phiên bản 26.33.30 trở lên.
    • Để kiểm tra quá trình chuyển giữa hai thiết bị, hãy kết nối hai thiết bị.

Khả năng tương thích

Bảng sau đây liệt kê các phiên bản tối thiểu và phiên bản đề xuất để thử nghiệm tính năng sao lưu và khôi phục tự động:

Thành phần Phiên bản tối thiểu Phiên bản nên dùng
Android Studio Rabbit 2 Canary 1 Rabbit 2 Canary 4 trở lên
Trình bổ trợ Android cho Gradle (AGP) 9.5.0-alpha06 9.5.0-alpha09 trở lên
androidx.test.backup thư viện 1.0.0-alpha01 1.0.0-alpha04 trở lên

Mỗi phiên bản xem trước của AGP đều yêu cầu phiên bản xem trước tương ứng của Android Studio. Để biết thêm thông tin, hãy xem phần Bản xem trước AGP.

Thiết lập dự án

Để thêm bộ kiểm thử sao lưu và khôi phục vào mô-đun ứng dụng, hãy hoàn tất các bước sau:

Bật cờ thử nghiệm

Trong tệp gradle.properties của dự án, hãy bật bộ kiểm thử và kiểm thử sao lưu:

android.experimental.testSuiteSupport=true
android.experimental.enableBackupTest=true

Khai báo bộ kiểm thử

Trong tệp build.gradle.kts của mô-đun ứng dụng, hãy khai báo một bộ kiểm thử sao lưu trong khối testOptions:

android {
    testOptions {
        backupTests {
            create("backupTest") {
                backupTestLibraryVersion = "1.0.0-alpha04"
            }
        }
    }
}

Tên bộ kiểm thử, backupTest trong ví dụ này, xác định các thư mục nhóm tài nguyên và tên tác vụ Gradle. Bạn có thể tuỳ chỉnh bộ ứng dụng bằng các thuộc tính không bắt buộc sau:

  • Sử dụng backupTestLibraryVersion để đặt phiên bản của thư viện androidx.test.backup mà AGP thêm vào bộ thư viện, chẳng hạn như "1.0.0-alpha04". Thuộc tính này không bắt buộc. Nếu bạn bỏ qua, AGP sẽ quay lại phiên bản thư viện mặc định dựa trên phiên bản AGP. Các ví dụ trên trang này yêu cầu phiên bản 1.0.0-alpha04 trở lên.
  • Sử dụng targetVariants để chỉ định các biến thể bản dựng mà bộ kiểm thử, chẳng hạn như targetVariants.add("demoDebug"). Thuộc tính này không bắt buộc. Nếu bạn bỏ qua, bộ kiểm thử sẽ kiểm thử các biến thể của testBuildType trong mô-đun, theo mặc định là debug. Bạn nên thử nghiệm một biến thể có thể gỡ lỗi vì chế độ vận chuyển từ thiết bị sang thiết bị và đám mây yêu cầu một ứng dụng có thể gỡ lỗi.

AGP thêm thư viện lưu trữ, androidx.test.backup:backup-host và JUnit 5 vào các bài kiểm thử lưu trữ. Thao tác này sẽ thêm thư viện thiết bị, androidx.test.backup:backup, vào tệp APK kiểm thử và đặt trình chạy đo lường của tệp APK kiểm thử.

Để thêm các phần phụ thuộc khác, hãy sử dụng khối hostJar và testApk của bộ ứng dụng. Ví dụ: để sử dụng Truth trong các kiểm thử máy chủ, hãy thêm thư viện này vào khối hostJar:

create("backupTest") {
    hostJar {
        dependencies {
            implementation("com.google.truth:truth:1.4.2")
        }
    }
}

Tạo nhóm tài nguyên

Tạo các thư mục nhóm tài nguyên khớp với tên bộ:

  • Đặt các bài kiểm thử máy chủ lưu trữ trong src/{suiteName}/test/kotlin/.
  • Đặt các thao tác trên thiết bị vào src/{suiteName}/androidTest/kotlin/.

Ví dụ: một bộ có tên là backupTest sử dụng cấu trúc thư mục sau:

app/src/backupTest/
├── androidTest/
│   └── kotlin/com/example/myapp/ThemeActions.kt
└── test/
    └── kotlin/com/example/myapp/SettingsBackupTest.kt

Kiểm tra cấu hình sao lưu

Kiểm thử sao lưu và khôi phục dữ liệu mà cấu hình sao lưu của ứng dụng bao gồm. Đảm bảo rằng bạn đã bật tính năng sao lưu cho ứng dụng và quy tắc sao lưu của bạn bao gồm cả dữ liệu mà bạn kiểm thử.

Viết mã kiểm thử sao lưu và khôi phục

Viết mã kiểm thử máy chủ lưu trữ trong nhóm tài nguyên test của bộ kiểm thử. Chú thích từng lớp kiểm thử bằng @ExtendWith(BackupRestoreExtension::class), cung cấp các thiết bị thông minh cho các kiểm thử. Các kiểm thử chạy dựa trên biến thể ứng dụng mà bộ kiểm thử nhắm đến, vì vậy, bạn không cần đặt mã ứng dụng cho biến thể đó.

Mỗi phương thức kiểm thử khai báo một tham số BackupRestoreController cho mỗi thiết bị mà phương thức đó sử dụng.

Kiểm thử các loại bộ nhớ tích hợp sẵn

Để kiểm thử các loại bộ nhớ tích hợp, hãy gọi runBackupRestoreFlow bằng dữ liệu cần gieo, thư mục cho tệp sao lưu và chế độ vận chuyển. Phương thức này chạy các bước sau trên thiết bị:

  1. Cung cấp dữ liệu cho từng miền lưu trữ.
  2. Dừng ứng dụng.
  3. Sao lưu ứng dụng.
  4. Xoá dữ liệu của ứng dụng.
  5. Khôi phục bản sao lưu.
  6. Xác minh rằng mỗi miền lưu trữ đều có giá trị được gieo hoặc không có giá trị nào khi được gói trong StorageDomain.ExcludedData.

Nếu một bước không thành công, phương thức này sẽ gửi một ngoại lệ, khiến kiểm thử không đạt. Ví dụ sau đây kiểm thử SharedPreferences, Preferences DataStore, SQLite, một tệp nội bộ và một tệp loại trừ bằng cách sử dụng phương thức sao lưu cục bộ:

package com.example.myapp

import androidx.test.backup.host.BackupRestoreController
import androidx.test.backup.host.BackupRestoreExtension
import androidx.test.backup.host.BackupTransportMode
import androidx.test.backup.host.StorageDomain
import java.nio.file.Path
import kotlinx.coroutines.runBlocking
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.extension.ExtendWith
import org.junit.jupiter.api.io.TempDir

@ExtendWith(BackupRestoreExtension::class)
class SettingsBackupTest {

    @Test
    fun settingsSurviveBackupAndRestore(
        device: BackupRestoreController,
        @TempDir outputDir: Path,
    ): Unit = runBlocking {
        device.runBackupRestoreFlow(
            storages = listOf(
                StorageDomain.Preference(
                    prefName = "settings",
                    key = "channels",
                    value = setOf("news", "alerts"),
                ),
                StorageDomain.DataStorePreference(
                    dataStoreName = "user_prefs",
                    key = "font_scale",
                    value = 1.25f,
                ),
                StorageDomain.Database(
                    dbName = "notes.db",
                    table = "notes",
                    primaryKeyCol = "id",
                    primaryKeyVal = 1,
                    columnValues = mapOf("title" to "Groceries"),
                ),
                StorageDomain.TextFile(
                    path = "drafts/note.txt",
                    content = "Buy milk",
                ),
                // Check that a file excluded by backup rules isn't restored.
                StorageDomain.ExcludedData(
                    StorageDomain.TextFile(
                        path = "auth/session.txt",
                        content = "temp-token",
                    )
                ),
            ),
            outputDir = outputDir,
            mode = BackupTransportMode.LOCAL,
        )
    }
}

Hãy lưu ý những điều sau khi bạn xác định miền lưu trữ:

  • Preference lấy tên của tệp SharedPreferences mà không có đuôi .xml.
  • DataStorePreference lấy tên được truyền đến preferencesDataStore. Sử dụng cùng một loại Kotlin cho value làm khoá lựa chọn ưu tiên của ứng dụng, chẳng hạn như 1.25f cho floatPreferencesKey, để ứng dụng có thể đọc mục đã khôi phục.
  • TextFile và BinaryFile phân giải các đường dẫn tương đối theo filesDir của ứng dụng.
  • Database ghi hàng bằng SQL và tạo bảng có các cột TEXT nếu bảng không tồn tại. Nếu ứng dụng của bạn sử dụng Room, hãy kiểm thử nội dung cơ sở dữ liệu bằng thao tác trên thiết bị sử dụng DAO để cơ sở dữ liệu khớp với giản đồ của Room.
  • ExcludedData yêu cầu ít nhất một miền lưu trữ không bị loại trừ trong cùng một lệnh gọi runBackupRestoreFlow.
  • Preference, DataStorePreference, Database, TextFile và BinaryFile nhắm đến bộ nhớ được bảo vệ bằng thiết bị thay vì bộ nhớ mặc định của ứng dụng khi bạn đặt isDeviceProtectedStorage = true.

Ghi hành động trên thiết bị

Để gieo mầm hoặc xác minh dữ liệu mà các loại bộ nhớ tích hợp sẵn không bao gồm, hãy viết các thao tác trên thiết bị trong nhóm tài nguyên androidTest của bộ kiểm thử. Triển khai BackupDeviceAction và ghi đè execute để chạy hành động bằng Context của ứng dụng và các đối số từ kiểm thử máy chủ lưu trữ. Trả về một BackupDeviceActionResult được tạo bằng BackupDeviceActionResult.success hoặc BackupDeviceActionResult.failure, truyền thông báo lỗi đến failure.

Phương thức execute chạy trong quy trình của ứng dụng trên một luồng trong nền, vì vậy, phương thức này có thể chặn cho đến khi quá trình đọc và ghi hoàn tất. Để truy cập vào khả năng đo lường của trình chạy kiểm thử, chẳng hạn như UiAutomation, hãy gọi InstrumentationRegistry.getInstrumentation.

Ví dụ sau đây sẽ gieo mầm và xác minh chế độ cài đặt giao diện trong Proto DataStore, trong đó settingsDataStore là thuộc tính DataStore<Settings> được xác định trong ứng dụng của bạn:

// In app/src/backupTest/androidTest/kotlin/com/example/myapp/ThemeActions.kt
package com.example.myapp

import android.content.Context
import androidx.test.backup.BackupDeviceAction
import androidx.test.backup.BackupDeviceActionArgs
import androidx.test.backup.BackupDeviceActionResult
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.runBlocking

class SeedThemeAction : BackupDeviceAction {
    override fun execute(
        context: Context,
        args: BackupDeviceActionArgs,
    ): BackupDeviceActionResult {
        val theme = args["theme"]
            ?: return BackupDeviceActionResult.failure("Missing theme argument")
        runBlocking {
            context.settingsDataStore.updateData {
                it.toBuilder().setTheme(theme).build()
            }
        }
        return BackupDeviceActionResult.success()
    }
}

class VerifyThemeAction : BackupDeviceAction {
    override fun execute(
        context: Context,
        args: BackupDeviceActionArgs,
    ): BackupDeviceActionResult {
        val expected = args["theme"]
        val actual = runBlocking {
            context.settingsDataStore.data.first().theme
        }
        return if (actual == expected) {
            BackupDeviceActionResult.success()
        } else {
            BackupDeviceActionResult.failure("Expected $expected, found $actual")
        }
    }
}

Để chạy các thao tác điền sẵn và xác minh trong runBackupRestoreFlow, hãy truyền tên lớp của các thao tác đó vào StorageDomain.CustomData:

package com.example.myapp

import androidx.test.backup.host.BackupRestoreController
import androidx.test.backup.host.BackupRestoreExtension
import androidx.test.backup.host.BackupTransportMode
import androidx.test.backup.host.StorageDomain
import java.nio.file.Path
import kotlinx.coroutines.runBlocking
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.extension.ExtendWith
import org.junit.jupiter.api.io.TempDir

const val SEED_THEME = "com.example.myapp.SeedThemeAction"
const val VERIFY_THEME = "com.example.myapp.VerifyThemeAction"

@ExtendWith(BackupRestoreExtension::class)
class ThemeBackupTest {

    @Test
    fun themeSurvivesCloudBackup(
        device: BackupRestoreController,
        @TempDir outputDir: Path,
    ): Unit = runBlocking {
        device.runBackupRestoreFlow(
            storage = StorageDomain.CustomData(
                populateAction = SEED_THEME,
                verifyAction = VERIFY_THEME,
                args = mapOf("theme" to "dark"),
            ),
            outputDir = outputDir,
            mode = BackupTransportMode.CLOUD_ENCRYPTED,
        )
    }
}

Để truyền các giá trị được tạo trong quá trình gieo hạt đến hành động xác minh, hãy truyền một bản đồ đến BackupDeviceActionResult.success. CustomData hợp nhất các mục đó vào đối số của hành động xác minh.

Chạy từng bước của quy trình

Để tuỳ chỉnh quy trình (ví dụ: gọi uninstallApp và installApk để kiểm thử một bản nâng cấp hoặc gọi launchApp), hãy tự chạy từng bước:

package com.example.myapp

import androidx.test.backup.host.BackupRestoreController
import androidx.test.backup.host.BackupRestoreExtension
import androidx.test.backup.host.BackupTransportMode
import java.nio.file.Path
import kotlinx.coroutines.runBlocking
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.extension.ExtendWith
import org.junit.jupiter.api.io.TempDir

@ExtendWith(BackupRestoreExtension::class)
class CustomFlowBackupTest {

    @Test
    fun themeSurvivesLaunchAfterRestore(
        device: BackupRestoreController,
        @TempDir outputDir: Path,
    ): Unit = runBlocking {
        val args = mapOf("theme" to "dark")
        device.runOnDevice(SEED_THEME, args).getOrThrow()

        device.stopApp()
        val backupFile = device.performBackup(
            BackupTransportMode.CLOUD_ENCRYPTED,
            outputDir,
        )
        device.clearAppData()
        device.performRestore(backupFile)
        device.launchApp()

        device.runOnDevice(VERIFY_THEME, args).getOrThrow()
    }
}

Khi một thao tác trên thiết bị không thành công, runOnDevice sẽ trả về BackupActionResult.Failure thay vì gửi một ngoại lệ. Gọi getOrThrow để lấy bản đồ data được trả về khi thành công hoặc gửi IOException khi không thành công.

Kiểm thử việc chuyển giữa các thiết bị

Để kiểm thử quá trình chuyển giữa hai thiết bị, hãy khai báo tham số BackupRestoreController cho từng thiết bị và truyền thiết bị mục tiêu đến restoreOn trong runBackupRestoreFlow:

package com.example.myapp

import androidx.test.backup.host.BackupRestoreController
import androidx.test.backup.host.BackupRestoreExtension
import androidx.test.backup.host.BackupTransportMode
import androidx.test.backup.host.Device
import androidx.test.backup.host.StorageDomain
import java.nio.file.Path
import kotlinx.coroutines.runBlocking
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.extension.ExtendWith
import org.junit.jupiter.api.io.TempDir

@ExtendWith(BackupRestoreExtension::class)
class ThemeTransferTest {

    @Test
    fun themeTransfersToNewDevice(
        @Device(role = "source") source: BackupRestoreController,
        @Device(role = "target") target: BackupRestoreController,
        @TempDir outputDir: Path,
    ): Unit = runBlocking {
        source.runBackupRestoreFlow(
            storage = StorageDomain.DataStorePreference(
                dataStoreName = "settings",
                key = "theme",
                value = "dark",
            ),
            outputDir = outputDir,
            mode = BackupTransportMode.DEVICE_TO_DEVICE,
            restoreOn = target,
        )
    }
}

Trên source, quy trình này sẽ tạo và sao lưu ứng dụng. Trên target, quy trình này sẽ xoá dữ liệu ứng dụng, khôi phục bản sao lưu và xác minh dữ liệu. Việc khôi phục trên một thiết bị khác yêu cầu DEVICE_TO_DEVICE hoặc chế độ vận chuyển qua đám mây, vì dữ liệu sao lưu LOCAL vẫn nằm trên thiết bị nguồn.

Giá trị role của @Device cho phép bạn chọn một thiết bị cho mỗi tham số khi chạy kiểm thử. Nếu chỉ có một thiết bị phù hợp được kết nối, thì cả hai tham số sẽ dùng chung thiết bị đó và mô phỏng quá trình chuyển trên một thiết bị.

Chọn thiết bị

Theo mặc định, khung kiểm thử sẽ sắp xếp các thiết bị trực tuyến theo số sê-ri và cung cấp cho mỗi tham số BackupRestoreController thiết bị phù hợp riêng khi có đủ thiết bị được kết nối. Các tham số không thể lấy một thiết bị riêng biệt sẽ dùng chung thiết bị khớp đầu tiên. Biến môi trường ANDROID_SERIAL không ảnh hưởng đến việc chỉ định thiết bị.

Để chọn thiết bị mà không cần đưa số sê-ri vào chương trình kiểm thử, hãy chỉ định vai trò cho từng tham số thiết bị bằng @Device(role = "..."). Sau đó, khi bạn chạy kiểm thử, hãy liên kết từng vai trò với một thiết bị có thuộc tính hệ thống androidx.test.backup.device.serial.{role}. Ví dụ: lệnh sau đây chạy bộ kiểm thử với emulator-5554 là thiết bị nguồn và emulator-5556 là thiết bị mục tiêu:

./gradlew :app:testDebugBackupTestDefaultTestSuite -Dandroidx.test.backup.device.serial.source=emulator-5554 -Dandroidx.test.backup.device.serial.target=emulator-5556

Một liên kết chỉ áp dụng cho các tham số có vai trò đó. Các tham số khác sẽ nhận được những thiết bị phù hợp còn lại.

Bạn cũng có thể lọc thiết bị bằng serial, api, minApi và maxApi trên @Device, chẳng hạn như @Device(role = "target", minApi = 35). Để đặt số sê-ri hoặc cấp độ API chính xác từ dòng lệnh, hãy truyền các thuộc tính hệ thống sau bằng -D:

Thuộc tính hệ thống Mô tả
androidx.test.backup.device.serial.{role} Số sê-ri của thiết bị cho các tham số được chú thích bằng @Device(role = "{role}"). Được ưu tiên hơn serials, serial và giá trị serial của @Device.
androidx.test.backup.device.serials Danh sách số sê-ri được phân tách bằng dấu phẩy, được chỉ định cho các tham số thiết bị theo thứ tự. Được ưu tiên hơn serial và giá trị serial của @Device.
androidx.test.backup.device.serial Số sê-ri cho các thông số thiết bị mà serials không bao gồm. Được ưu tiên hơn giá trị serial của @Device.
androidx.test.backup.device.apis Danh sách các cấp độ API được phân tách bằng dấu phẩy, được chỉ định cho các thông số thiết bị theo thứ tự. Sử dụng 0 để khớp với mọi cấp độ API. Thay thế api trên @Device, trong minApi và maxApi.
androidx.test.backup.device.api Cấp độ API cho các thông số thiết bị mà apis không bao gồm. Sử dụng 0 để khớp với mọi cấp độ API. Thay thế api trên @Device, trong minApi và maxApi.

Các thuộc tính serial, serials, api và apis áp dụng cho mọi kiểm thử chạy, vì vậy, hãy sử dụng tuỳ chọn --tests để chỉ chạy các kiểm thử cần đến các thuộc tính đó.

Thông tin đăng nhập để kiểm tra việc khôi phục

Nếu ứng dụng của bạn sử dụng tính năng Khôi phục thông tin đăng nhập, hãy kiểm tra để đảm bảo khoá khôi phục của ứng dụng vẫn hoạt động sau khi sao lưu và khôi phục. Chế độ đám mây và chế độ thiết bị với thiết bị sao lưu khoá bằng dữ liệu của ứng dụng, nhưng LOCAL thì không.

Viết các hành động trên thiết bị để tạo khoá và lấy khoá bằng Trình quản lý thông tin xác thực. Thao tác tạo sẽ trả về mã thông tin xác thực của khoá để thao tác xác minh có thể kiểm tra xem thao tác khôi phục có trả về cùng một khoá hay không. Trong ví dụ này, createRequestJson và getRequestJson là các chuỗi JSON yêu cầu mà ứng dụng của bạn truyền đến Trình quản lý thông tin xác thực:

// In app/src/backupTest/androidTest/kotlin/com/example/myapp/RestoreKeyActions.kt
package com.example.myapp

import android.content.Context
import androidx.credentials.CreateRestoreCredentialRequest
import androidx.credentials.CreateRestoreCredentialResponse
import androidx.credentials.CredentialManager
import androidx.credentials.GetCredentialRequest
import androidx.credentials.GetRestoreCredentialOption
import androidx.credentials.RestoreCredential
import androidx.test.backup.BackupDeviceAction
import androidx.test.backup.BackupDeviceActionArgs
import androidx.test.backup.BackupDeviceActionResult
import kotlinx.coroutines.runBlocking
import org.json.JSONObject

class CreateRestoreKeyAction : BackupDeviceAction {
    override fun execute(
        context: Context,
        args: BackupDeviceActionArgs,
    ): BackupDeviceActionResult {
        val request = CreateRestoreCredentialRequest(createRequestJson)
        val response = runBlocking {
            CredentialManager.create(context).createCredential(context, request)
        } as CreateRestoreCredentialResponse
        val credentialId = JSONObject(response.responseJson).getString("id")
        return BackupDeviceActionResult.success(mapOf("credential_id" to credentialId))
    }
}

class VerifyRestoreKeyAction : BackupDeviceAction {
    override fun execute(
        context: Context,
        args: BackupDeviceActionArgs,
    ): BackupDeviceActionResult {
        val option = GetRestoreCredentialOption(getRequestJson)
        val response = runBlocking {
            CredentialManager.create(context)
                .getCredential(context, GetCredentialRequest(listOf(option)))
        }
        val credential = response.credential as RestoreCredential
        val credentialId = JSONObject(credential.authenticationResponseJson).getString("id")
        val expected = args["credential_id"]
        return if (credentialId == expected) {
            BackupDeviceActionResult.success()
        } else {
            BackupDeviceActionResult.failure("Expected key $expected, found $credentialId")
        }
    }
}

Kiểm thử máy chủ lưu trữ sau đây sẽ tạo khoá trên thiết bị nguồn, khôi phục khoá đó trên thiết bị mục tiêu và xác minh rằng mã thông tin xác thực khớp:

package com.example.myapp

import androidx.test.backup.host.BackupRestoreController
import androidx.test.backup.host.BackupRestoreExtension
import androidx.test.backup.host.BackupTransportMode
import androidx.test.backup.host.Device
import androidx.test.backup.host.StorageDomain
import java.nio.file.Path
import kotlinx.coroutines.runBlocking
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.extension.ExtendWith
import org.junit.jupiter.api.io.TempDir

const val CREATE_RESTORE_KEY = "com.example.myapp.CreateRestoreKeyAction"
const val VERIFY_RESTORE_KEY = "com.example.myapp.VerifyRestoreKeyAction"

@ExtendWith(BackupRestoreExtension::class)
class RestoreKeyTest {

    @Test
    fun restoreKeyTransfersToNewDevice(
        @Device(role = "source") source: BackupRestoreController,
        @Device(role = "target") target: BackupRestoreController,
        @TempDir outputDir: Path,
    ): Unit = runBlocking {
        // Clears target (including any existing restore key) before restoring.
        source.runBackupRestoreFlow(
            storage = StorageDomain.CustomData(
                populateAction = CREATE_RESTORE_KEY,
                verifyAction = VERIFY_RESTORE_KEY,
            ),
            outputDir = outputDir,
            mode = BackupTransportMode.DEVICE_TO_DEVICE,
            restoreOn = target,
        )
    }
}

Để tạo khoá khi isCloudBackupEnabled được đặt thành true (mặc định), thiết bị nguồn cần có một Tài khoản Google đã bật tính năng sao lưu và một phương thức khoá màn hình. Nếu không, Trình quản lý thông tin xác thực sẽ gửi E2eeUnavailableException.

Không giống như quy trình khôi phục trên đám mây trên thiết bị mới, các chế độ đám mây không yêu cầu cùng một Tài khoản Google hoặc phương thức khoá màn hình của thiết bị nguồn, đồng thời khôi phục các khoá được tạo bằng isCloudBackupEnabled được đặt thành false.

Giữ lại dữ liệu ứng dụng giữa các lần kiểm thử

Trước mỗi lần kiểm thử, khung kiểm thử sẽ xoá dữ liệu của ứng dụng trên mỗi thiết bị mà chương trình kiểm thử sử dụng. Để tắt tính năng này cho một lớp hoặc phương thức kiểm thử, hãy chú thích lớp hoặc phương thức đó bằng @Isolation(IsolationPolicy.MANUAL).

Viết mã kiểm thử bằng Java

Các phương thức BackupRestoreController là hàm tạm ngưng trong Kotlin. Nếu bạn viết kiểm thử máy chủ bằng Java, hãy sử dụng biến thể Async của mỗi phương thức, chẳng hạn như runBackupRestoreFlowAsync, trả về ListenableFuture.

Chạy kiểm thử sao lưu và khôi phục

AGP tạo một tác vụ Gradle cho mỗi biến thể mà bộ kiểm thử, có tên là test{Variant}{SuiteName}DefaultTestSuite. Để chạy bộ kiểm thử backupTest cho biến thể debug, hãy kết nối thiết bị và chạy tác vụ:

./gradlew :app:testDebugBackupTestDefaultTestSuite

Các tác vụ check, test và connectedCheck không chạy bộ kiểm thử sao lưu và khôi phục, vì vậy, hãy chạy tác vụ của bộ kiểm thử một cách rõ ràng.

Để chạy một lớp hoặc phương thức kiểm thử, hãy sử dụng tuỳ chọn --tests:

./gradlew :app:testDebugBackupTestDefaultTestSuite --tests "com.example.myapp.ThemeBackupTest"

Kiểm tra báo cáo thử nghiệm

Sau khi chạy kiểm thử xong, AGP sẽ tạo một báo cáo kiểm thử HTML tại {module}/build/reports/tests/{taskName}/index.html, chẳng hạn như app/build/reports/tests/testDebugBackupTestDefaultTestSuite/index.html.

Khi một chương trình kiểm thử không thành công, khung kiểm thử sẽ lưu logcat từ mỗi thiết bị mà chương trình kiểm thử đã sử dụng và liệt kê các đường dẫn tệp đã lưu trong kết quả không thành công. Để tắt tính năng lưu nhật ký, hãy truyền -Dandroidx.test.backup.device.logs.enabled=false.

Khắc phục sự cố khôi phục không thành công

Quá trình khôi phục qua đám mây hoặc từ thiết bị này sang thiết bị khác không thành công và có thông báo lỗi trong các trường hợp sau:

  • Dịch vụ Google Play bỏ qua ứng dụng của bạn, ví dụ: vì mã ứng dụng của ứng dụng đó bắt đầu bằng com.google. hoặc com.android., bản sao lưu của ứng dụng đó trống hoặc ứng dụng đó đặt android:allowBackup="false". Để kiểm thử một ứng dụng có mã ứng dụng như vậy, hãy sử dụng chế độ LOCAL.
  • Phiên bản Dịch vụ Google Play thấp hơn 26.33.30 trên thiết bị hoặc trình mô phỏng chạy cấp độ API 36.1 trở lên. Cập nhật Dịch vụ Google Play thông qua Cửa hàng Play trên thiết bị hoặc sử dụng hình ảnh hệ thống đi kèm với phiên bản 26.33.30 trở lên.

Các vấn đề và hạn chế đã biết

Tính năng kiểm thử sao lưu và khôi phục tự động có các vấn đề và hạn chế đã biết sau đây:

  • Android Studio chưa hỗ trợ bộ kiểm thử. Trình soạn thảo mã có thể hiển thị lỗi tham chiếu chưa được giải quyết trong các tệp nguồn của bộ kiểm thử ngay cả khi dự án của bạn được định cấu hình chính xác. Thay vào đó, hãy tạo và chạy các kiểm thử sao lưu và khôi phục từ dòng lệnh bằng Gradle.
  • Các chương trình kiểm thử chỉ chạy trên các thiết bị và trình mô phỏng được kết nối với máy phát triển của bạn thông qua adb. Phòng thử nghiệm Firebase không được hỗ trợ.
  • Các chương trình kiểm thử sẽ xoá dữ liệu của ứng dụng và thay đổi chế độ cài đặt sao lưu trên thiết bị mà chúng sử dụng. Bạn nên sử dụng thiết bị kiểm thử chuyên dụng.

Để biết các thay đổi trong mỗi bản phát hành, hãy xem ghi chú phát hành về việc kiểm thử tính năng sao lưu và khôi phục.