可用來測試不同螢幕大小的程式庫和工具

Android 提供多種工具和 API，可協助您針對不同螢幕和視窗大小建立測試。

DeviceConfigurationOverride

DeviceConfigurationOverride 可組合項可讓您覆寫設定屬性，在 Compose 版面配置中測試多種螢幕和視窗大小。ForcedSize 覆寫值可配合可用空間中的任何版面配置，讓您在任何螢幕大小上執行任何 UI 測試。舉例來說，您可以使用小型手機板型規格執行所有 UI 測試，包括大螢幕手機、折疊式手機和平板電腦的 UI 測試。

   DeviceConfigurationOverride(
        DeviceConfigurationOverride.ForcedSize(DpSize(1280.dp, 800.dp))
    ) {
        MyScreen() // Will be rendered in the space for 1280dp by 800dp without clipping.
    }

此外，您可以使用這個可組合項，設定您可能想在不同視窗大小上測試的字型比例、主題和其他屬性。

Robolectric

使用 Robolectric 在 JVM 上本機執行 Compose 或以檢視為基礎的 UI 測試，無須使用裝置或模擬器。您可以設定 Robolectric 使用特定螢幕大小，以及其他實用的屬性。

在 Now in Android 的以下示例中，Robolectric 會模擬 1000x1000 dp 的螢幕大小，解析度為 480 dpi：

@RunWith(RobolectricTestRunner::class)
// Configure Robolectric to use a very large screen size that can fit all of the test sizes.
// This allows enough room to render the content under test without clipping or scaling.
@Config(qualifiers = "w1000dp-h1000dp-480dpi")
class NiaAppScreenSizesScreenshotTests { ... }

您也可以從測試主體設定限定條件，如 Now in Android 範例中的這段程式碼片段所示：

val (width, height, dpi) = ...

// Set qualifiers from specs.
RuntimeEnvironment.setQualifiers("w${width}dp-h${height}dp-${dpi}dpi")

請注意，RuntimeEnvironment.setQualifiers() 會使用新設定更新系統和應用程式資源，但不會在有效活動或其他元件上觸發任何動作。

詳情請參閱 Robolectric 的「裝置設定」說明文件。

Gradle 管理的裝置

Gradle 管理的裝置 (GMD) Android Gradle 外掛程式可讓您定義模擬器和實際裝置的規格，以便執行檢測設備測試。為不同螢幕大小的裝置建立規格，以便實作測試策略，也就是必須在特定螢幕大小上執行特定測試。您可以將 GMD 與持續整合 (CI) 搭配使用，確保系統在需要時執行適當的測試、佈建及啟動模擬器，並簡化 CI 設定。

android {
    testOptions {
        managedDevices {
            devices {
                // Run with ./gradlew nexusOneApi30DebugAndroidTest.
                nexusOneApi30(com.android.build.api.dsl.ManagedVirtualDevice) {
                    device = "Nexus One"
                    apiLevel = 30
                    // Use the AOSP ATD image for better emulator performance
                    systemImageSource = "aosp-atd"
                }
                // Run with ./gradlew  foldApi34DebugAndroidTest.
                foldApi34(com.android.build.api.dsl.ManagedVirtualDevice) {
                    device = "Pixel Fold"
                    apiLevel = 34
                    systemImageSource = "aosp-atd"
                }
            }
        }
    }
}

您可以在 testing-samples 專案中找到多個 GMD 範例。

Firebase Test Lab

您可以使用 Firebase Test Lab (FTL) 或類似的裝置農場服務，在您可能無法存取的特定實體裝置上執行測試，例如折疊式裝置或各種尺寸的平板電腦。Firebase Test Lab 是付費服務，提供免費方案。FTL 也支援在模擬器上執行測試。這些服務可提前佈建裝置和模擬器，因此可提升檢測設備測試的可靠性和速度。

如要瞭解如何搭配使用 FTL 和 GMD，請參閱「使用 Gradle 管理的裝置擴大測試規模」。

使用測試執行器測試篩選功能

最佳測試策略不應重複驗證相同內容，因此大部分的 UI 測試不需要在多個裝置上執行。通常，您會在手機板型規格上執行所有或大部分的 UI 測試，並在螢幕大小不同的裝置上執行部分測試。

您可以為特定測試加上註解，讓測試只在特定裝置上執行，然後使用執行測試的指令，將引數傳遞至 AndroidJUnitRunner。

舉例來說，您可以建立不同的註解：

annotation class TestExpandedWidth
annotation class TestCompactWidth

並在不同測試中使用：

class MyTestClass {

    @Test
    @TestExpandedWidth
    fun myExample_worksOnTablet() {
        ...
    }

    @Test
    @TestCompactWidth
    fun myExample_worksOnPortraitPhone() {
        ...
    }

}

接著，您可以在執行測試時使用 android.testInstrumentationRunnerArguments.annotation 屬性篩選特定測試。舉例來說，如果您使用 Gradle 管理的裝置：

$ ./gradlew pixelTabletApi30DebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.annotation='com.sample.TestExpandedWidth'

如果您未使用 GMD，且在 CI 上管理模擬器，請先確認正確的模擬器或裝置已就緒並連線，然後將參數傳遞至其中一個 Gradle 指令，以便執行檢測工具測試：

$ ./gradlew connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.annotation='com.sample.TestExpandedWidth'

請注意，Espresso Device (請參閱下一節) 也可以使用裝置屬性篩選測試。

濃縮咖啡機

使用 Espresso Device 時，您可以在測試中使用任何類型的檢測設備測試 (包括 Espresso、Compose 或 UI Automator 測試) 對模擬器執行動作。這些動作可能包括設定螢幕大小，或切換摺疊式裝置的狀態或姿勢。舉例來說，您可以控制折疊式模擬器，並將其設為桌面模式。Espresso Device 也包含 JUnit 規則和註解，用於要求特定功能：

@RunWith(AndroidJUnit4::class)
class OnDeviceTest {

    @get:Rule(order=1) val activityScenarioRule = activityScenarioRule<MainActivity>()

    @get:Rule(order=2) val screenOrientationRule: ScreenOrientationRule =
        ScreenOrientationRule(ScreenOrientation.PORTRAIT)

    @Test
    fun tabletopMode_playerIsDisplayed() {
        // Set the device to tabletop mode.
        onDevice().setTabletopMode()
        onView(withId(R.id.player)).check(matches(isDisplayed()))
    }
}

請注意，Espresso Device 仍處於 Alpha 階段，並具有下列需求：

• Android Gradle 外掛程式 8.3 以上版本
• Android Emulator 33.1.10 以上版本
• 搭載 API 級別 24 以上版本的 Android 虛擬裝置

篩選測試

Espresso Device 可讀取已連結裝置的屬性，讓您使用註解篩選測試。如果不符合註解規定，系統會略過測試。

RequiresDeviceMode 註解

RequiresDeviceMode 註解可重複使用，用來表示只有在裝置支援所有DeviceMode 值時才會執行的測試。

class OnDeviceTest {
    ...
    @Test
    @RequiresDeviceMode(TABLETOP)
    @RequiresDeviceMode(BOOK)
    fun tabletopMode_playerIdDisplayed() {
        // Set the device to tabletop mode.
        onDevice().setTabletopMode()
        onView(withId(R.id.player)).check(matches(isDisplayed()))
    }
}

需要顯示註解

您可以使用 RequiresDisplay 註解，透過大小類別指定裝置螢幕的寬度和高度。大小類別會依照官方的視窗大小類別定義尺寸分層。

class OnDeviceTest {
    ...
    @Test
    @RequiresDisplay(EXPANDED, COMPACT)
    fun myScreen_expandedWidthCompactHeight() {
        ...
    }
}

調整螢幕大小

使用 setDisplaySize() 方法，在執行階段調整螢幕的尺寸。請搭配使用該方法和 DisplaySizeRule 類別，確保在下次測試前，系統會撤銷在測試期間所做的任何變更。

@RunWith(AndroidJUnit4::class)
class ResizeDisplayTest {

    @get:Rule(order = 1) val activityScenarioRule = activityScenarioRule<MainActivity>()

    // Test rule for restoring device to its starting display size when a test case finishes.
    @get:Rule(order = 2) val displaySizeRule: DisplaySizeRule = DisplaySizeRule()

    @Test
    fun resizeWindow_compact() {
        onDevice().setDisplaySize(
            widthSizeClass = WidthSizeClass.COMPACT,
            heightSizeClass = HeightSizeClass.COMPACT
        )
        // Verify visual attributes or state restoration.
    }
}

使用 setDisplaySize() 調整螢幕大小時，不會影響裝置的密度，因此如果某個維度不符合目標裝置，測試就會失敗，並顯示 UnsupportedDeviceOperationException。如要避免在這種情況下執行測試，請使用 RequiresDisplay 註解篩除測試：

@RunWith(AndroidJUnit4::class)
class ResizeDisplayTest {

    @get:Rule(order = 1) var activityScenarioRule = activityScenarioRule<MainActivity>()

    // Test rule for restoring device to its starting display size when a test case finishes.
    @get:Rule(order = 2) var displaySizeRule: DisplaySizeRule = DisplaySizeRule()

    /**
     * Setting the display size to EXPANDED would fail in small devices, so the [RequiresDisplay]
     * annotation prevents this test from being run on devices outside the EXPANDED buckets.
     */
    @RequiresDisplay(
        widthSizeClass = WidthSizeClassEnum.EXPANDED,
        heightSizeClass = HeightSizeClassEnum.EXPANDED
    )
    @Test
    fun resizeWindow_expanded() {
        onDevice().setDisplaySize(
            widthSizeClass = WidthSizeClass.EXPANDED,
            heightSizeClass = HeightSizeClass.EXPANDED
        )
        // Verify visual attributes or state restoration.
    }
}

StateRestorationTester

StateRestorationTester 類別可用於測試可組合項件的狀態還原功能，而無需重新建立活動。這可讓測試更快速且更可靠，因為活動重建是一個複雜的程序，包含多種同步處理機制：

@Test
fun compactDevice_selectedEmailEmailRetained_afterConfigChange() {
    val stateRestorationTester = StateRestorationTester(composeTestRule)

    // Set content through the StateRestorationTester object.
    stateRestorationTester.setContent {
        MyApp()
    }

    // Simulate a config change.
    stateRestorationTester.emulateSavedInstanceStateRestore()
}

窗口測試程式庫

窗口測試程式庫包含公用程式，可協助您編寫依賴或驗證與視窗管理相關的功能的測試，例如活動嵌入或可折疊功能。您可以透過 Google 的 Maven 存放區取得此構件。

舉例來說，您可以使用 FoldingFeature() 函式產生自訂 FoldingFeature，並在 Compose 預覽畫面中使用。在 Java 中，請使用 createFoldingFeature() 函式。

在 Compose 預覽中，您可以採用下列方式實作 FoldingFeature：

@Preview(showBackground = true, widthDp = 480, heightDp = 480)
@Composable private fun FoldablePreview() =
    MyApplicationTheme {
        ExampleScreen(
            displayFeatures = listOf(FoldingFeature(Rect(0, 240, 480, 240)))
        )
 }

此外，您也可以使用 TestWindowLayoutInfo() 函式，在 UI 測試中模擬顯示功能。以下是模擬 FoldingFeature 的範例，其螢幕中心有一個 HALF_OPENED 垂直轉軸，然後檢查該版面配置是否符合預期：

import androidx.window.layout.FoldingFeature.Orientation.Companion.VERTICAL
import androidx.window.layout.FoldingFeature.State.Companion.HALF_OPENED
import androidx.window.testing.layout.FoldingFeature
import androidx.window.testing.layout.TestWindowLayoutInfo
import androidx.window.testing.layout.WindowLayoutInfoPublisherRule

@RunWith(AndroidJUnit4::class)
class MediaControlsFoldingFeatureTest {

    @get:Rule(order=1)
    val composeTestRule = createAndroidComposeRule<ComponentActivity>()

    @get:Rule(order=2)
    val windowLayoutInfoPublisherRule = WindowLayoutInfoPublisherRule()

    @Test
    fun foldedWithHinge_foldableUiDisplayed() {
        composeTestRule.setContent {
            MediaPlayerScreen()
        }

        val hinge = FoldingFeature(
            activity = composeTestRule.activity,
            state = HALF_OPENED,
            orientation = VERTICAL,
            size = 2
        )

        val expected = TestWindowLayoutInfo(listOf(hinge))
        windowLayoutInfoPublisherRule.overrideWindowLayoutInfo(expected)

        composeTestRule.waitForIdle()

        // Verify that the folding feature is detected and media controls shown.
        composeTestRule.onNodeWithTag("MEDIA_CONTROLS").assertExists()
    }
}

import androidx.window.layout.FoldingFeature.Orientation
import androidx.window.layout.FoldingFeature.State
import androidx.window.testing.layout.FoldingFeature
import androidx.window.testing.layout.TestWindowLayoutInfo
import androidx.window.testing.layout.WindowLayoutInfoPublisherRule

@RunWith(AndroidJUnit4::class)
class MediaControlsFoldingFeatureTest {

    @get:Rule(order=1)
    val activityRule = ActivityScenarioRule(MediaPlayerActivity::class.java)

    @get:Rule(order=2)
    val windowLayoutInfoPublisherRule = WindowLayoutInfoPublisherRule()

    @Test
    fun foldedWithHinge_foldableUiDisplayed() {
        activityRule.scenario.onActivity { activity ->
            val feature = FoldingFeature(
                activity = activity,
                state = State.HALF_OPENED,
                orientation = Orientation.VERTICAL)
            val expected = TestWindowLayoutInfo(listOf(feature))
            windowLayoutInfoPublisherRule.overrideWindowLayoutInfo(expected)
        }

        // Verify that the folding feature is detected and media controls shown.
        onView(withId(R.id.media_controls)).check(matches(isDisplayed()))
    }
}

您可以在 WindowManager 專案中找到更多範例。

其他資源

說明文件

• 大螢幕應用程式品質指南
• 在 Android 上測試應用程式
• 測試 Compose 版面配置

範例

• WindowManager 範例
• Espresso Device 範例
• Android 即時情報
  • 使用螢幕截圖測試來驗證不同螢幕大小

程式碼研究室

• 透過 Jetpack WindowManager 支援折疊式和雙螢幕裝置