本頁面由 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 管理的裝置

Android Gradle 外掛程式的Gradle 管理的裝置 (GMD) 可讓您定義模擬器和實際裝置的規格，以便執行檢測設備測試。為不同螢幕大小的裝置建立規格，以便實作測試策略，規定某些測試必須在特定螢幕大小的裝置上執行。搭配使用 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 測試，並只在不同螢幕大小的裝置上執行部分測試，藉此篩選 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 裝置 (請參閱下一節) 也可以使用裝置屬性篩選測試。

Espresso 裝置

使用 Espresso 裝置，在測試中對模擬器執行動作，包括 Espresso、Compose 或 UI Automator 測試等任何類型的檢測設備測試。這些動作可能包括設定螢幕大小、切換摺疊狀態或姿勢。舉例來說，您可以控制折疊式模擬器，並將其設為桌上模式。Espresso 裝置也包含 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 裝置仍處於 Alpha 階段，且有下列需求條件：

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

篩選測試

Espresso 裝置可以讀取連線裝置的屬性，讓您使用註解篩選測試。如果未符合註解要求，系統會略過測試。

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 註解

您可以使用 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()
}

Window 測試程式庫

Window 測試程式庫包含各種公用程式，可協助您編寫依賴或驗證視窗管理相關功能的測試，例如活動嵌入或摺疊式功能。您可以透過 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()
    }
}

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 裝置樣本
Android 即時情報
- 使用螢幕截圖測試驗證不同螢幕大小

程式碼研究室

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