本頁面由 Cloud Translation API 翻譯而成。

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

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.
    }

**圖 1.** 使用 DeviceConfigurationOverride 將平板電腦版版面配置套用至較小的裝置板型規格，如「*Now in Android*」一文所述。

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

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 垂直轉軸，然後檢查該版面配置是否符合預期：

Compose

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()
    }
}

View

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 專案中找到更多範例。

其他資源

說明文件

範例

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

程式碼研究室

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