الاختبار للتأكّد من التغييرات في إعدادات الشاشة باستخدام Espresso Device API
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
استخدِم Espresso Device API لاختبار تطبيقك عندما يخضع الجهاز لتغييرات شائعة في الإعدادات، مثل التدوير وفتح الشاشة. تتيح لك واجهة برمجة التطبيقات Espresso Device API محاكاة تغييرات الإعدادات هذه على جهاز افتراضي وتنفيذ اختباراتك بشكل متزامن، وبالتالي لا يتم تنفيذ سوى إجراء واحد أو تأكيد واحد لواجهة المستخدم في كل مرة، وتكون نتائج الاختبار أكثر موثوقية. إذا كنت حديث العهد بكتابة اختبارات واجهة المستخدم باستخدام Espresso، يمكنك الاطّلاع على المستندات الخاصة بها.
لاستخدام Espresso Device API، يجب استيفاء الشروط التالية:
- الإصدار Iguana من "استوديو Android" أو إصدار أحدث
- الإصدار 8.3 من المكوّن الإضافي لنظام Gradle المتوافق مع Android أو إصدار أحدث
- الإصدار 33.1.10 من "محاكي Android" أو إصدار أحدث
- جهاز Android افتراضي يعمل بالمستوى 24 لواجهة برمجة التطبيقات أو مستوى أحدث
إعداد مشروعك لاستخدام Espresso Device API
لإعداد مشروعك بحيث يتوافق مع Espresso Device API، اتّبِع الخطوات التالية:
للسماح للاختبار بتمرير الأوامر إلى جهاز الاختبار، أضِف الإذنَين INTERNET
وACCESS_NETWORK_STATE
إلى ملف البيان في مجموعة المصادر androidTest
:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
فعِّل العلامة التجريبية enableEmulatorControl
في الملف gradle.properties
:
android.experimental.androidTest.enableEmulatorControl=true
فعِّل الخيار emulatorControl
في نص البرمجة على مستوى الوحدة:
Kotlin
testOptions {
emulatorControl {
enable = true
}
}
Groovy
testOptions {
emulatorControl {
enable = true
}
}
في نص برمجة الإصدار على مستوى الوحدة، استورِد مكتبة Espresso Device
إلى مشروعك:
Kotlin
dependencies {
androidTestImplementation("androidx.test.espresso:espresso-device:1.0.1")
}
Groovy
dependencies {
androidTestImplementation 'androidx.test.espresso:espresso-device:1.0.1'
}
اختبار التغييرات الشائعة في الإعدادات
تتضمّن واجهة برمجة التطبيقات Espresso Device API حالات متعددة لاتجاه الشاشة وحالات الأجهزة القابلة للطي، ويمكنك استخدامها لمحاكاة التغييرات في إعدادات الجهاز.
اختبار تدوير الشاشة
في ما يلي مثال على كيفية اختبار ما يحدث لتطبيقك عند تدوير شاشة الجهاز:
أولاً، لضبط حالة بدء متسقة، اضبط الجهاز على الوضع العمودي:
import androidx.test.espresso.device.action.ScreenOrientation
import androidx.test.espresso.device.rules.ScreenOrientationRule
...
@get:Rule
val screenOrientationRule: ScreenOrientationRule = ScreenOrientationRule(ScreenOrientation.PORTRAIT)
أنشئ اختبارًا يضبط الجهاز على الوضع الأفقي أثناء تنفيذ الاختبار:
@Test
fun myRotationTest() {
...
// Sets the device to landscape orientation during test execution.
onDevice().setScreenOrientation(ScreenOrientation.LANDSCAPE)
...
}
بعد تدوير الشاشة، تأكَّد من أنّ واجهة المستخدم تتكيّف مع التنسيق الجديد على النحو المتوقّع.
@Test
fun myRotationTest() {
...
// Sets the device to landscape orientation during test execution.
onDevice().setScreenOrientation(ScreenOrientation.LANDSCAPE)
composeTestRule.onNodeWithTag("NavRail").assertIsDisplayed()
composeTestRule.onNodeWithTag("BottomBar").assertDoesNotExist()
}
اختبار عدم طي الشاشة
في ما يلي مثال على كيفية اختبار ما يحدث لتطبيقك إذا كان على جهاز قابل للطي وتم فتح الشاشة:
أولاً، اختبِر الجهاز وهو في وضع الطي من خلال الاتصال بالرقم onDevice().setClosedMode()
. تأكَّد من أنّ تصميم تطبيقك يتكيّف مع عرض الشاشة المضغوط.
@Test
fun myUnfoldedTest() {
onDevice().setClosedMode()
composeTestRule.onNodeWithTag("BottomBar").assetIsDisplayed()
composeTestRule.onNodeWithTag("NavRail").assetDoesNotExist()
...
}
للانتقال إلى حالة فتح كامل، استخدِم
onDevice().setFlatMode()
. تحقَّق من أنّ تصميم التطبيق يتكيّف مع فئة الحجم الموسّعة.
@Test
fun myUnfoldedTest() {
onDevice().setClosedMode()
...
onDevice().setFlatMode()
composeTestRule.onNodeWithTag("NavRail").assertIsDisplayed()
composeTestRule.onNodeWithTag("BottomBar").assetDoesNotExist()
}
تحديد الأجهزة التي تحتاج إليها الاختبارات
إذا كنت تجري اختبارًا ينفّذ إجراءات طي على جهاز غير قابل للطي، من المحتمل أن يتعذّر إجراء الاختبار. لتنفيذ الاختبارات ذات الصلة بالجهاز الذي يتم تشغيله فقط، استخدِم التعليق التوضيحي @RequiresDeviceMode
. يتخطّى مشغّل الاختبار تلقائيًا إجراء الاختبارات على الأجهزة التي لا تتوافق مع الإعداد الذي يتم اختباره. يمكنك إضافة قاعدة متطلبات الجهاز إلى كل اختبار أو إلى فئة اختبار كاملة.
على سبيل المثال، لتحديد أنّه يجب إجراء الاختبار فقط على الأجهزة التي تتيح
الفتح إلى وضع مسطّح، أضِف الرمز @RequiresDeviceMode
التالي
إلى الاختبار:
@Test
@RequiresDeviceMode(mode = FLAT)
fun myUnfoldedTest() {
...
}
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-09-04 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-09-04 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["Use the Espresso Device API to test your app when the device undergoes common\nconfiguration changes, such as rotation and screen unfolding. The Espresso\nDevice API lets you simulate these configuration changes on a virtual device and\nexecutes your tests synchronously, so only one UI action or assertion happens at\na time and your test results are more reliable. If you're new to writing UI\ntests with Espresso, see its [documentation](/training/testing/espresso).\n\nTo use the Espresso Device API, you need the following:\n\n- Android Studio Iguana or higher\n- Android Gradle plugin 8.3 or higher\n- Android Emulator 33.1.10 or higher\n- Android virtual device that runs API level 24 or higher\n\nSet up your project for the Espresso Device API\n\nTo set up your project so it supports the Espresso Device API, do the following:\n\n1. To let the test pass commands to the test device, add the\n `INTERNET` and `ACCESS_NETWORK_STATE` permissions to the manifest file in the `androidTest` source set:\n\n ```\n \u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n \u003cuses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" /\u003e\n \n ```\n2. Enable the `enableEmulatorControl` experimental flag in the\n `gradle.properties` file:\n\n ```\n android.experimental.androidTest.enableEmulatorControl=true\n \n ```\n3. Enable the `emulatorControl` option in the module-level build\n script:\n\n Kotlin \n\n ```kotlin\n testOptions {\n emulatorControl {\n enable = true\n }\n }\n \n ```\n\n Groovy \n\n ```groovy\n testOptions {\n emulatorControl {\n enable = true\n }\n }\n \n ```\n4. In the module-level build script, import the Espresso Device library\n into your project:\n\n Kotlin \n\n ```kotlin\n dependencies {\n androidTestImplementation(\"androidx.test.espresso:espresso-device:1.0.1\")\n }\n \n ```\n\n Groovy \n\n ```groovy\n dependencies {\n androidTestImplementation 'androidx.test.espresso:espresso-device:1.0.1'\n }\n \n ```\n\nTest against common configuration changes\n\nThe Espresso Device API has multiple screen orientation and foldable states that\nyou can use to simulate device configuration changes.\n\nTest against screen rotation\n\nHere's an example of how to test what happens to your app when the device screen\nrotates:\n\n1. First, for a consistent starting state set the device to portrait\n mode:\n\n ```kotlin\n import androidx.test.espresso.device.action.ScreenOrientation\n import androidx.test.espresso.device.rules.ScreenOrientationRule\n ...\n @get:Rule\n val screenOrientationRule: ScreenOrientationRule = ScreenOrientationRule(ScreenOrientation.PORTRAIT)\n \n ```\n2. Create a test that sets the device to landscape orientation during test\n execution:\n\n ```kotlin\n @Test\n fun myRotationTest() {\n ...\n // Sets the device to landscape orientation during test execution.\n onDevice().setScreenOrientation(ScreenOrientation.LANDSCAPE)\n ...\n }\n \n ```\n3. After the screen rotates, check that the UI adapts to the new layout as expected.\n\n ```kotlin\n @Test\n fun myRotationTest() {\n ...\n // Sets the device to landscape orientation during test execution.\n onDevice().setScreenOrientation(ScreenOrientation.LANDSCAPE)\n composeTestRule.onNodeWithTag(\"NavRail\").assertIsDisplayed()\n composeTestRule.onNodeWithTag(\"BottomBar\").assertDoesNotExist()\n }\n \n ```\n\nTest against screen unfolding\n\nHere's an example of how to test what happens to your app if it's on a foldable\ndevice and the screen unfolds:\n\n1. First, test with the device in the folded state by calling\n `onDevice().setClosedMode()`. Make sure that your app's layout\n adapts to the compact screen width.\n\n ```kotlin\n @Test\n fun myUnfoldedTest() {\n onDevice().setClosedMode()\n composeTestRule.onNodeWithTag(\"BottomBar\").assetIsDisplayed()\n composeTestRule.onNodeWithTag(\"NavRail\").assetDoesNotExist()\n ...\n }\n \n ```\n2. To transition to a fully unfolded state, call\n `onDevice().setFlatMode()`. Check that the app's layout adapts to\n the expanded size class.\n\n ```kotlin\n @Test\n fun myUnfoldedTest() {\n onDevice().setClosedMode()\n ...\n onDevice().setFlatMode()\n composeTestRule.onNodeWithTag(\"NavRail\").assertIsDisplayed()\n composeTestRule.onNodeWithTag(\"BottomBar\").assetDoesNotExist()\n }\n \n ```\n\nSpecify what devices your tests need\n\nIf you're running a test that performs folding actions on a device that isn't\nfoldable, the test will likely fail. To execute only the tests that are relevant\nto the running device, use the `@RequiresDeviceMode` annotation. The test runner\nautomatically skips running tests on devices that don't support the\nconfiguration being tested. You can add the device requirement rule to each test\nor an entire test class.\n\nFor example, to specify that a test should only be run on devices that support\nunfolding to a flat configuration, add the following `@RequiresDeviceMode` code\nto your test: \n\n @Test\n @RequiresDeviceMode(mode = FLAT)\n fun myUnfoldedTest() {\n ...\n }"]]