使用 Espresso Device API 测试屏幕配置更改
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
当设备经历常见的配置变更(例如旋转和屏幕展开)时,使用 Espresso 设备 API 测试您的应用。借助 Espresso Device API,您可以在虚拟设备上模拟这些配置更改,并同步执行测试,这样一次只会发生一项界面操作或断言,测试结果也更可靠。如果您不熟悉如何使用 Espresso 编写界面测试,请参阅其文档。
如需使用 Espresso 设备 API,您需要满足以下条件:
- Android Studio Iguana 或更高版本
- Android Gradle 插件 8.3 或更高版本
- Android 模拟器 33.1.10 或更高版本
- 运行 API 级别 24 或更高级别的 Android 虚拟设备
为 Espresso 设备 API 设置项目
如需设置项目以使其支持 Espresso 设备 API,请执行以下操作:
如需让测试向测试设备传递命令,请向 androidTest
源代码集中的清单文件添加 INTERNET
和 ACCESS_NETWORK_STATE
权限:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
在 gradle.properties
文件中启用 enableEmulatorControl
实验性标志:
android.experimental.androidTest.enableEmulatorControl=true
在模块级 build 脚本中启用 emulatorControl
选项:
Kotlin
testOptions {
emulatorControl {
enable = true
}
}
Groovy
testOptions {
emulatorControl {
enable = true
}
}
在模块级 build 脚本中,将 Espresso 设备库导入到您的项目中:
Kotlin
dependencies {
androidTestImplementation("androidx.test.espresso:espresso-device:1.0.1")
}
Groovy
dependencies {
androidTestImplementation 'androidx.test.espresso:espresso-device:1.0.1'
}
针对常见配置变更进行测试
Espresso 设备 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 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-09-04。
[null,null,["最后更新时间 (UTC):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 }"]]