اختبار الاحتفاظ بنسخة احتياطية من البيانات واستعادتها بشكل آلي

عندما يضبط المستخدمون جهازًا جديدًا أو يعيدون تثبيت تطبيقك، يمكن لنظام التشغيل Android استعادة بيانات تطبيقك من نسخة احتياطية على السحابة الإلكترونية أو من خلال نقل البيانات من جهاز إلى آخر. إذا كانت قواعد الاحتفاظ بنسخة احتياطية تستبعد بيانات مهمة، أو إذا لم يتمكّن تطبيقك من استخدام البيانات التي يستعيدها، سيفقد المستخدمون إعداداتهم ومستوى تقدّمهم بدون ظهور أي خطأ.

تساعدك اختبارات النسخ الاحتياطي والاستعادة المبرمَجة في رصد هذه المشاكل قبل طرح تطبيقك، وهي اختبارات JUnit 5 يتم تنفيذها على جهاز التطوير وتتحكّم في الأجهزة المتصلة من خلال Android Debug Bridge (adb). تُعدّ كل عملية اختبار بيانات التطبيق على أحد الأجهزة، وتنشئ نسخة احتياطية من التطبيق وتستعيدها من خلال إطار عمل الاحتفاظ بنسخة احتياطية من البيانات في Android، ثم تتحقّق من سلامة البيانات. يمكنك ضبط الاختبارات كـ مجموعة اختبارات للمكوّن الإضافي لنظام Gradle المتوافق مع Android ‏ (AGP) في ملف إصدار الوحدة.

آلية العمل

تتضمّن مجموعة اختبارات الاحتفاظ بنسخة احتياطية والاستعادة جزأين يعملان معًا:

• اختبارات المضيف هي اختبارات JUnit 5 يتم إجراؤها على جهاز التطوير. يستخدمون BackupRestoreController لكل جهاز لتوفير البيانات الأولية، والاحتفاظ بنسخة احتياطية من تطبيقك واستعادته، والتحقّق من النتائج.
• إجراءات الجهاز هي فئات تنفّذ BackupDeviceAction. ويتم تشغيلها في عملية تطبيقك على الجهاز، لذا يمكنها قراءة البيانات وكتابتها من خلال الرمز البرمجي الخاص بتطبيقك. يختبر المضيف إجراءات الجهاز من خلال اسم الفئة.

عند تشغيل المجموعة، ينشئ AGP تطبيقك وحزمة اختبار APK تحتوي على إجراءات جهازك. قبل كل اختبار، يثبِّت إطار الاختبار حِزمتَي APK على كل جهاز يستخدمه الاختبار، ثم يمحو بيانات تطبيقك.

أنواع مساحة التخزين المضمّنة

يسرد الجدول التالي الفئات الفرعية StorageDomain التي تتيح لك إنشاء البيانات والتحقّق منها بدون كتابة إجراءات الجهاز:

لاختبار بيانات أخرى، مثل ملفات DataStore، عليك كتابة إجراءات الجهاز.

وسائل النقل

يستخدم كل احتياطي قيمة BackupTransportMode. يعرض الجدول التالي وسائل النقل المتوافقة:

تعمل ميزة LOCAL على أي جهاز متوافق. يؤدي وضعا السحابة الإلكترونية ونقل البيانات من جهاز إلى جهاز إلى إنشاء نُسخ احتياطية مماثلة لإجراء الاحتفاظ بنسخة احتياطية من بيانات التطبيق في "استوديو Android": يتم حفظ النسخة الاحتياطية على جهاز التطوير بدلاً من تحميلها أو إرسالها إلى جهاز آخر. يتطلّب وضعا السحابة الإلكترونية والنقل من جهاز إلى جهاز توفُّر "خدمات Google Play" على الجهاز وإنشاء نسخة من تطبيقك يمكن تصحيح أخطائها. وإذا كانت قواعد النسخ الاحتياطي تعتمد على التشفير من جهة العميل، اختبِر كلا الوضعين.

المتطلبات

لاستخدام ميزة "اختبار الاحتفاظ بنسخة احتياطية والاستعادة تلقائيًا"، تأكَّد من أنّ بيئتك تستوفي المتطلبات التالية:

• الإصدار 9.6.0 من Gradle أو إصدار أحدث
• الإصدار 17 من JDK أو إصدار أحدث
• جهاز أو محاكي يعمل بالإصدار 12 من نظام التشغيل Android (المستوى 31 لواجهة برمجة التطبيقات) أو إصدار أحدث ومتصل من خلال أداة تصحيح الأخطاء Android Debug Bridge (adb) لاختبار عمليات النقل بين جهازين، عليك ربط جهازين.

التوافق

يسرد الجدول التالي الحد الأدنى من الإصدارات والإصدارات المقترَحة لاختبار النسخ الاحتياطي والاستعادة التلقائيين:

يتطلّب كل إصدار مبكر حصري من AGP الإصدار المبكر الحصري المطابق من "استوديو Android". لمزيد من المعلومات، يُرجى الاطّلاع على مَعاينات AGP.

إعداد مشروعك

لإضافة مجموعة اختبارات الاحتفاظ بنسخة احتياطية والاستعادة إلى وحدة تطبيقك، أكمِل الخطوات التالية:

تفعيل العلامات التجريبية

في ملف gradle.properties الخاص بمشروعك، فعِّل الحزم الاختبارية والاختبارات الاحتياطية:

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

تعريف مجموعة الاختبار

في ملف build.gradle.kts الخاص بوحدة تطبيقك، أعلِن عن مجموعة اختبارات احتياطية في حزمة testOptions:

android {
    testOptions {
        backupTests {
            create("backupTest")
        }
    }
}

يحدّد اسم الحزمة، backupTest في هذا المثال، أدلة مجموعة رموز المصدر وأسماء مهام Gradle. يمكنك تخصيص المجموعة باستخدام السمات الاختيارية التالية:

• استخدِم backupTestLibraryVersion لضبط إصدار مكتبات androidx.test.backup التي يضيفها "مكوّن Android الإضافي في Gradle" إلى الحزمة، مثل "1.0.0-alpha02". هذه السمة اختيارية. وفي حال حذفه، يعود المكوّن الإضافي لنظام Gradle المتوافق مع Android إلى إصدار المكتبة التلقائي استنادًا إلى إصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android.
• استخدِم targetVariants لتحديد تنويعات التصميم التي تختبرها الحزمة، مثل targetVariants.add("demoDebug"). هذه السمة اختيارية. في حال عدم تضمينها، ستختبر المجموعة صيغ testBuildType في الوحدة، والتي تكون debug تلقائيًا. ننصح باختبار صيغة قابلة للتصحيح لأنّ وضعي النقل عبر السحابة الإلكترونية ومن جهاز إلى آخر يتطلبان تطبيقًا قابلاً للتصحيح.

يضيف مكوّن AGP الإضافي مكتبة المضيف androidx.test.backup:backup-host وJUnit 5 إلى اختبارات المضيف. وتضيف مكتبة الأجهزة androidx.test.backup:backup إلى حزمة APK الاختبارية وتضبط مشغّل حالة التطبيق لحزمة APK الاختبارية.

لإضافة تبعيات أخرى، استخدِم الحزمتَين hostJar وtestApk. على سبيل المثال، لاستخدام Truth في اختبارات المضيف، أضِفها إلى حظر hostJar:

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

إنشاء مجموعات رموز المصدر

أنشِئ أدلة مجموعات رموز المصدر التي تتطابق مع اسم الحزمة:

• ضَع اختبارات المضيف في src/{suiteName}/test/kotlin/.
• ضَع إجراءات الجهاز في src/{suiteName}/androidTest/kotlin/.

على سبيل المثال، تستخدم حزمة باسم backupTest بنية الدليل التالية:

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

التحقّق من إعدادات النسخ الاحتياطي

تختبر هذه الأداة الاحتفاظ بنسخة احتياطية من البيانات التي تتضمّنها إعدادات النسخ الاحتياطي في تطبيقك واستعادتها. تأكَّد من تفعيل ميزة الاحتفاظ بنسخة احتياطية لتطبيقك ومن أنّ قواعد الاحتفاظ بنسخة احتياطية تتضمّن البيانات التي تختبرها.

كتابة اختبارات النسخ الاحتياطي والاستعادة

اكتب اختبارات المضيف في مجموعة رموز المصدر test الخاصة بالحزمة. يحتاج كل صف اختبار إلى تعليقَين توضيحيَين:

• توفّر @ExtendWith(BackupRestoreExtension::class) أجهزة متصلة للاختبارات.
• يضبط @BackupRestoreConfig(applicationId = "...") رقم تعريف التطبيق الذي يتم اختباره. استخدِم معرّف التطبيق الخاص بالصيغة التي تختبرها، بما في ذلك أي applicationIdSuffix.

تُعلن كل طريقة اختبار عن مَعلمة BackupRestoreController لكل جهاز تستخدمه.

اختبار أنواع مساحة التخزين المدمجة

لاختبار أنواع مساحة التخزين المدمجة، يمكنك استدعاء runBackupRestoreFlow باستخدام البيانات المطلوب إدخالها ودليل لملف النسخة الاحتياطية ووضع النقل. تنفِّذ الطريقة الخطوات التالية على الجهاز:

1. تتم إضافة بيانات أولية إلى كل نطاق تخزين.
2. يؤدي هذا الإجراء إلى إيقاف التطبيق.
3. لإنشاء نسخة احتياطية من التطبيق
4. يمحو بيانات التطبيق.
5. استعادة النسخة الاحتياطية
6. تتحقّق هذه السمة من أنّ كل نطاق تخزين يتضمّن القيمة الأولية.

إذا تعذّرت خطوة معيّنة، ستعرض الطريقة استثناءً، ما يؤدي إلى تعذُّر الاختبار. يختبر المثال التالي مفتاح SharedPreferences وصف SQLite وصف ملف داخلي باستخدام أسلوب النقل الخاص بالنسخ الاحتياطية المحلية:

package com.example.myapp

import androidx.test.backup.host.BackupRestoreConfig
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)
@BackupRestoreConfig(applicationId = "com.example.myapp")
class SettingsBackupTest {

    @Test
    fun settingsSurviveBackupAndRestore(
        device: BackupRestoreController,
        @TempDir outputDir: Path,
    ): Unit = runBlocking {
        device.runBackupRestoreFlow(
            storages = listOf(
                StorageDomain.Preference(
                    prefName = "settings",
                    key = "theme",
                    value = "dark",
                ),
                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",
                ),
            ),
            outputDir = outputDir,
            mode = BackupTransportMode.LOCAL,
        )
    }
}

يُرجى مراعاة ما يلي عند تحديد نطاقات التخزين:

• يأخذ Preference اسم ملف SharedPreferences بدون الامتداد .xml.
• تعمل السمتان TextFile وBinaryFile على حل المسارات النسبية مقابل filesDir في تطبيقك.
• تكتب Database الصف باستخدام SQL، وتنشئ الجدول مع أعمدة TEXT إذا لم يكن الجدول متوفّرًا. إذا كان تطبيقك يستخدم Room، ننصحك باختبار محتوى قاعدة البيانات باستخدام إجراءات الجهاز التي تستخدم عناصر الوصول إلى البيانات (DAO) لكي تتضمّن قاعدة البيانات المخطط الذي تتوقّعه Room.

كتابة إجراءات الجهاز

To seed or verify data that the built-in storage types don't cover, write device actions in the suite's androidTest source set. ينفّذ إجراء الجهاز BackupDeviceAction ويلغي عضوَين:

• اضبط phase القيمة على BackupDeviceAction.PHASE_POPULATE لإجراء يضيف بيانات أولية، أو BackupDeviceAction.PHASE_VERIFY لإجراء يتحقّق من البيانات.
• يجب تنفيذ execute لتشغيل الإجراء باستخدام Context في تطبيقك والوسيطات من اختبار المضيف. يتم عرض نتيجة تم إنشاؤها باستخدام طريقة المصنع BackupDeviceActionResult.success أو BackupDeviceActionResult.failure وتمرير رسالة خطأ إلى failure.

يتم تنفيذ طريقة execute في عملية تطبيقك على سلسلة محادثات في الخلفية، لذا يمكن أن يتم حظرها إلى أن تنتهي عمليات القراءة والكتابة.

يُنشئ المثال التالي إعدادات المظهر التي يخزّنها التطبيق ويتحقّق منها باستخدام Preferences DataStore. يحدّد التطبيق DataStore في مجموعة رموز المصدر الرئيسية:

// In app/src/main/kotlin/com/example/myapp/Settings.kt
package com.example.myapp

import android.content.Context
import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.preferencesDataStore

val Context.settingsDataStore by preferencesDataStore(name = "settings")
val THEME_KEY = stringPreferencesKey("theme")

تستخدم إجراءات الجهاز التعريفات نفسها:

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

import android.content.Context
import androidx.datastore.preferences.core.edit
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 val phase = BackupDeviceAction.PHASE_POPULATE

    override fun execute(
        context: Context,
        args: BackupDeviceActionArgs,
    ): BackupDeviceActionResult {
        val theme = args["theme"]
            ?: return BackupDeviceActionResult.failure("Missing theme argument")
        runBlocking {
            context.settingsDataStore.edit { it[THEME_KEY] = theme }
        }
        return BackupDeviceActionResult.success()
    }
}

class VerifyThemeAction : BackupDeviceAction {
    override val phase = BackupDeviceAction.PHASE_VERIFY

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

لإرجاع البيانات إلى الاختبار المضيف، مرِّر خريطة إلى الطريقة success. يقرأ اختبار المضيف الخريطة من BackupActionResult.Success.data.

تشغيل كل خطوة من خطوات المسار

لاستخدام إجراءات الجهاز أو تخصيص المسار، عليك استدعاء كل خطوة بنفسك. يُجري اختبار المضيف التالي إجراءات الجهاز من القسم السابق بشأن الاحتفاظ بنسخة احتياطية من البيانات على السحابة الإلكترونية واستعادتها:

package com.example.myapp

import androidx.test.backup.host.BackupActionResult
import androidx.test.backup.host.BackupRestoreConfig
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.fail
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)
@BackupRestoreConfig(applicationId = "com.example.myapp")
class ThemeBackupTest {

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

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

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

fun BackupActionResult.assertSuccess() {
    if (this is BackupActionResult.Failure) fail(errorMessage)
}

عندما يتعذّر تنفيذ إجراء على جهاز، تعرض runOnDevice الرمز BackupActionResult.Failure بدلاً من عرض استثناء، لذا عليك التحقّق من النتيجة. تُصدر الخطوات الأخرى استثناءً في حال تعذُّرها.

اختبار عمليات النقل بين الأجهزة

لاختبار عملية نقل بين جهازَين، يجب تحديد مَعلمة BackupRestoreController لكل جهاز. احتفِظ بنسخة احتياطية من التطبيق على الجهاز المصدر، ثم استعِد ملف النسخة الاحتياطية على جهاز الاختبار. يعيد المثال التالي استخدام الثوابت والدالة المساعدة assertSuccess من المثال السابق:

package com.example.myapp

import androidx.test.backup.host.BackupRestoreConfig
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 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)
@BackupRestoreConfig(applicationId = "com.example.myapp")
class ThemeTransferTest {

    @Test
    fun themeTransfersToNewDevice(
        @Device(role = "source") source: BackupRestoreController,
        @Device(role = "target") target: BackupRestoreController,
        @TempDir outputDir: Path,
    ): Unit = runBlocking {
        val args = mapOf("theme" to "dark")
        source.runOnDevice(SEED_THEME, args).assertSuccess()
        source.stopApp()
        val backupFile = source.performBackup(
            BackupTransportMode.DEVICE_TO_DEVICE,
            outputDir,
        )

        target.clearAppData()
        target.performRestore(backupFile)
        target.runOnDevice(VERIFY_THEME, args).assertSuccess()
    }
}

قيمة role لـ @Device هي تسمية تجعل الاختبار أسهل في القراءة. ولا يؤثّر ذلك في الجهاز الذي يتلقّى المعلَمة. إذا كان هناك جهاز واحد فقط متصلاً، فستستخدم كلتا المعلمتين هذا الجهاز، وسيحاكي الاختبار عملية النقل على جهاز واحد. يضمن محو بيانات الجهاز المستهدَف أن تكون البيانات التي تمت استعادتها من النسخة الاحتياطية.

اختيار الأجهزة

بشكلٍ تلقائي، يرتّب إطار الاختبار الأجهزة المتصلة بالإنترنت حسب الرقم التسلسلي ويخصّصها لمَعلمات BackupRestoreController حسب الموضع. على سبيل المثال، تحصل المَعلمة الأولى لطريقة الاختبار على الجهاز الأول، وتحصل المَعلمة الثانية على الجهاز الثاني. إذا لم يكن هناك جهاز لموضع معيّن، ستحصل المَعلمة على الجهاز الأول. تحسب المواضع جميع مَعلمات الطريقة، لذا يجب تعريف مَعلمات الجهاز قبل المَعلمات الأخرى، مثل @TempDir. لا يؤثر متغيّر البيئة ANDROID_SERIAL في عملية تعيين الأجهزة.

لاختيار الأجهزة، اضبط قيم serial أو api لـ @Device، أو اضبط خصائص نظام JVM. تحظى خصائص النظام بالأولوية على قيم @Device. يسرد الجدول التالي سمات النظام المتوافقة:

مرِّر هذه السمات مع -D عند تشغيل الاختبارات من سطر الأوامر. تنطبق السمات على كل اختبار يتم إجراؤه، لذا استخدِم الخيار --tests لإجراء الاختبارات التي تحتاج إليها فقط. على سبيل المثال، ينفّذ الأمر التالي ThemeTransferTest مع ضبط emulator-5554 كجهاز مصدر وemulator-5556 كجهاز اختبار:

./gradlew :app:testDebugBackupTestDefaultTestSuite --tests "com.example.myapp.ThemeTransferTest" -Dandroidx.test.backup.device.serials=emulator-5554,emulator-5556

الاحتفاظ ببيانات التطبيق بين الاختبارات

قبل كل اختبار، يمحو إطار عمل الاختبار بيانات تطبيقك على كل جهاز يستخدمه الاختبار. لإيقاف هذا الإعداد لفئة أو طريقة اختبار، أضِف التعليق التوضيحي @Isolation(IsolationPolicy.MANUAL) إليها.

كتابة الاختبارات بلغة Java

الطرق BackupRestoreController هي دوال تعليق في Kotlin. إذا كنت تكتب اختبارات مضيف في Java، استخدِم الصيغة Async لكل طريقة، مثل runBackupRestoreFlowAsync، التي تعرض ListenableFuture.

إجراء اختبارات الاحتفاظ بنسخة احتياطية والاستعادة

ينشئ "مكوّن Android الإضافي لنظام Gradle" مهمة Gradle لكل صيغة تختبرها المجموعة، ويتم تسميتها test{Variant}{SuiteName}DefaultTestSuite. لتشغيل حزمة backupTest على صيغة debug، عليك توصيل أجهزتك وتشغيل المهمة:

./gradlew :app:testDebugBackupTestDefaultTestSuite

لا تنفّذ المهام check وtest وconnectedCheck مجموعات اختبارات النسخ الاحتياطي والاستعادة، لذا عليك تنفيذ مهمة المجموعة بشكل صريح.

لتشغيل فئة اختبار أو طريقة اختبار واحدة، استخدِم الخيار --tests:

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

فحص تقارير الاختبار

بعد اكتمال عملية الاختبار، ينشئ المكوّن الإضافي لنظام Gradle المتوافق مع Android تقرير اختبار HTML في {module}/build/reports/tests/{taskName}/index.html، مثل app/build/reports/tests/testDebugBackupTestDefaultTestSuite/index.html.

الحدود والمشاكل المعروفة

في ما يلي المشاكل والقيود المعروفة في اختبار الاحتفاظ بنسخة احتياطية واستعادتها تلقائيًا:

• لا يتوفّر حتى الآن دعم "استوديو Android" لحِزَم الاختبار. قد تعرض أداة تعديل الرموز أخطاء مراجع لم يتم حلّها في ملفات مصدر مجموعة الاختبارات حتى إذا تم ضبط مشروعك بشكل صحيح. يمكنك إنشاء اختبارات النسخ الاحتياطي والاستعادة وتشغيلها من سطر الأوامر باستخدام Gradle بدلاً من ذلك.
• يتم إجراء الاختبارات فقط على الأجهزة والمحاكيات المتصلة بجهاز التطوير من خلال adb. لا تتوافق هذه الميزة مع "مختبر Firebase الافتراضي".
• تمحو الاختبارات بيانات تطبيقك وتغيّر إعدادات الاحتفاظ بنسخة احتياطية على الأجهزة التي تستخدمها. ننصحك باستخدام أجهزة اختبار مخصّصة.

للاطّلاع على التغييرات في كل إصدار، راجِع ملاحظات إصدار اختبار ميزة "النسخ الاحتياطي والاستعادة".