測試控管包批註

發行項
07/10/2023

測試控管包提供公用程式批註，可用來執行特定狀態或裝置類型的測試。如果您需要測試在多個狀態之間切換的複雜應用程式流程，您應該模擬折迭功能，或改用撥動手勢。

針對只使用一種狀態的簡單測試，您可以使用注釋來：

以單一螢幕或雙螢幕模式執行測試
在特定目標裝置上執行測試
在特定裝置方向中執行測試
使用模擬折迭功能執行測試

重要

這些注釋只適用于 FoldableTestRule 和 FoldableJUnit4ClassRunner。在下方的 [測試控管包元件 ] 區段中，您可以找到如何搭配批註使用它們的相關資訊。

安裝程式

在 androidTest 目錄中建立新的測試類別檔案。您稍後會在此新增測試規則和測試的程式碼片段。

請確定您在最上層build.gradle檔案中有存放 mavenCentral() 庫：

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

將下列相依性新增至模組層級 build.gradle 檔案 (目前版本可能與此處所示) 不同：

檢視
組成

androidTestImplementation "com.microsoft.device.dualscreen.testing:testing-kotlin:1.0.0-alpha4"
androidTestImplementation "androidx.test.uiautomator:uiautomator:2.2.0"
androidTestImplementation "androidx.test.espresso:espresso-core:3.4.0"
androidTestImplementation "androidx.test:runner:1.4.0"
androidTestImplementation "androidx.test:rules:1.4.0"

androidTestImplementation "com.microsoft.device.dualscreen.testing:testing-compose:1.0.0-alpha04"
androidTestImplementation "androidx.test.uiautomator:uiautomator:2.2.0"
androidTestImplementation "androidx.compose.ui:ui-test-junit4:1.1.1"

compileSdkVersion請確定和 targetSdkVersion 已設定為模組層級build.gradle檔案中的 API 31 或更新版本：
```
android { 
    compileSdkVersion 31

    defaultConfig { 
        targetSdkVersion 31 
    } 
    ... 
}
```

TestRule建立可執行 UI 檢查和模擬折迭功能的。您可以將兩個規則鏈結在一 FoldableTestRule 起：規則和 ActivityScenarioRule 或 AndroidComposeTestRule。

您可以使用 foldableRuleChain 方法來建立規則鏈結，也可以建立自己的規則鏈結，如下列範例所示：

檢視
組成

private val activityScenarioRule = activityScenarioRule<MainActivity>()
private val foldableTestRule = FoldableTestRule()

@get:Rule
val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)

或

private val uiDevice: UiDevice = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
private val activityScenarioRule = activityScenarioRule<MainActivity>()
private val foldableTestRule = FoldableTestRule()

@get:Rule
val testRule: TestRule = if (uiDevice.isSurfaceDuo()) {
    RuleChain.outerRule(activityScenarioRule).around(foldableTestRule)
} else {
    RuleChain.outerRule(foldableTestRule).around(activityScenarioRule)
}

private val composeTestRule = createAndroidComposeRule<MainActivity>()
private val foldableTestRule = FoldableTestRule()

@get:Rule
val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

或

protected val uiDevice: UiDevice = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
private val composeTestRule = createAndroidComposeRule<MainActivity>()
private val foldableTestRule = FoldableTestRule()

@get:Rule
val testRule: TestRule = if (uiDevice.isSurfaceDuo()) {
    RuleChain.outerRule(composeTestRule).around(foldableTestRule)
} else {
    RuleChain.outerRule(foldableTestRule).around(composeTestRule)
}

如果您選擇建立自己的規則鏈結：

SurfaceDuo對於和 SurfaceDuo2 裝置，必須是外部規則， ActivityScenarioRule 因為應用程式應該在範圍/取消窗格作業之前啟動。
對於其他可折迭裝置，必須是外部規則， FoldableTestRule 因為應該在應用程式啟動之前模擬 FoldingFeature 。

如果您使用一元測試檢視，請務必停用裝置上的動畫。

Test Kit 元件

重要

請先參閱 FoldableTestRule 和 FoldableJUnit4ClassRunner 區段，再開始使用下列批註。

SingleScreenTest/DualScreenTest

如果您想要以單螢幕/雙螢幕模式執行測試，請為測試方法或測試類別新增此批註。此外，您也可以使用 orientation 參數，在指定的裝置方向中執行測試。參數 orientation 可以有下列值： UiAutomation.ROTATION_FREEZE_0 、、 UiAutomation.ROTATION_FREEZE_90 、 UiAutomation.ROTATION_FREEZE_180UiAutomation.ROTATION_FREEZE_270

檢視
組成

@RunWith(FoldableJUnit4ClassRunner::class)
@SingleScreenTest(orientation = UiAutomation.ROTATION_FREEZE_180)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

或

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()
    
    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)
    
    @Test
    @SingleScreenTest(orientation = UiAutomation.ROTATION_FREEZE_180)
    fun sampleTestMethod() {
    }
}

@RunWith(FoldableJUnit4ClassRunner::class)
@SingleScreenTest(orientation = UiAutomation.ROTATION_FREEZE_180)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

或

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    @SingleScreenTest(orientation = UiAutomation.ROTATION_FREEZE_180)
    fun sampleTestMethod() {
    }
}

MockFoldingFeature

如果您想要使用所需的資料模擬折迭功能，請使用測試方法或測試類別的這個注釋。

參數 windowBounds 是座標陣列，代表將包含 FoldingFeature的一些顯示區域，例如 [左、上、右、下]。 windowBounds 寬度和高度必須大於 0。根據預設，如果您未定義自己的 windowBounds 值，則會使用整個顯示區域;更具體來說，[0， 0， uiDevice.displayWidth， uiDevice.displayHeight]。
參數 center 是折迭與方向互補的中心。 HORIZONTAL對於折迭，這是 Y 軸，而 VERTICAL 折迭則為 X 軸。預設值為 -1。如果未提供此參數，則會根據指定的，根據指定的 orientation ，根據 windowBounds 參數計算為 windowBounds.centerY () 或 windowBounds.centerX () 。
參數 size 是折迭的較小維度。較大的維度一律涵蓋整個視窗。預設值為 0。
參數 state 代表折迭的狀態。可能的值為： FoldingFeatureState.HALF_OPENED 和 FoldingFeatureState.FLAT 。預設值是 FoldingFeatureState.HALF_OPENED。如需視覺範例和參考，請參閱官方檔中的「狀態」一節。
參數 orientation 是折迭的方向。可能的值為： FoldingFeatureOrientation.HORIZONTAL 和 FoldingFeatureOrientation.VERTICAL 。預設值是 FoldingFeatureOrientation.HORIZONTAL。

檢視
組成

@RunWith(FoldableJUnit4ClassRunner::class)
@MockFoldingFeature(
    size = 2, 
    state = FoldingFeatureState.FLAT, 
    orientation = FoldingFeatureOrientation.HORIZONTAL
)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

或

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)
    
    @Test
    @MockFoldingFeature(
        size = 2, 
        state = FoldingFeatureState.FLAT,
        orientation = FoldingFeatureOrientation.HORIZONTAL
    )
    fun sampleTestMethod() {
    }
}

@RunWith(FoldableJUnit4ClassRunner::class)
@MockFoldingFeature(
    windowBounds = [0, 0, 1768, 2208],
    center = 0,
    size = 2,
    state = FoldingFeatureState.HALF_OPENED,
    orientation = FoldingFeatureOrientation.HORIZONTAL
)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

或

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    @MockFoldingFeature(
        windowBounds = [0, 0, 1768, 2208],
        center = 0,
        size = 2,
        state = FoldingFeatureState.HALF_OPENED,
        orientation = FoldingFeatureOrientation.HORIZONTAL
    )
    fun sampleTestMethod() {
    }
}

TargetDevices

如果您想要只在指定的裝置上執行測試，或是想要忽略某些裝置，請使用測試方法或測試類別的這個注釋。

參數 devices 是想要裝置的陣列， ignoreDevices 而參數是一個陣列，其中包含要忽略的裝置。

使用方式範例： @TargetDevices(devices = [DeviceModel.SurfaceDuo, DeviceModel.SurfaceDuo2]), @TargetDevices(ignoreDevices = [DeviceModel.SurfaceDuo])

您無法同時使用這兩個參數。

裝置型號的可能值：

DeviceModel.SurfaceDuo - 裝置 SurfaceDuo1 或模擬器的標記法
DeviceModel.SurfaceDuo2 - 裝置 SurfaceDuo2 和模擬器的標記法
DeviceModel.HorizontalFoldIn - 裝置和模擬器的表示 6.7" horizontal Fold-In 法
DeviceModel.FoldInOuterDisplay - 使用外部顯示裝置和模擬器的表示 7.6" Fold-In 法
DeviceModel.FoldOut - 裝置和模擬器的表示 8" FoldOut 法
DeviceModel.Other - 其他可折迭裝置和模擬器的標記法

檢視
組成

@RunWith(FoldableJUnit4ClassRunner::class)
@TargetDevices(devices = [DeviceModel.SurfaceDuo])
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

或

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)
    
    @Test
    @TargetDevices(devices = [DeviceModel.SurfaceDuo])
    fun sampleTestMethod() {
    }
}

@RunWith(FoldableJUnit4ClassRunner::class)
@TargetDevices(devices = [DeviceModel.SurfaceDuo])
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

或

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    @TargetDevices(devices = [DeviceModel.SurfaceDuo])
    fun sampleTestMethod() {
    }
}

DeviceOrientation

如果您想要在指定的裝置方向上執行測試，請使用測試方法或測試類別的這個注釋。

參數 orientation 代表裝置方向，而且可以有下列值： UiAutomation.ROTATION_FREEZE_0 、、 UiAutomation.ROTATION_FREEZE_90 、 UiAutomation.ROTATION_FREEZE_180 、 UiAutomation.ROTATION_FREEZE_270

檢視
組成

@RunWith(FoldableJUnit4ClassRunner::class)
@DeviceOrientation(orientation = UiAutomation.ROTATION_FREEZE_180)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

或

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)
    
    @Test
    @DeviceOrientation(orientation = UiAutomation.ROTATION_FREEZE_180)
    fun sampleTestMethod() {
    }
}

@RunWith(FoldableJUnit4ClassRunner::class)
@DeviceOrientation(orientation = UiAutomation.ROTATION_FREEZE_180)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

或

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    @DeviceOrientation(orientation = UiAutomation.ROTATION_FREEZE_180)
    fun sampleTestMethod() {
    }
}

FoldableTestRule

FoldableTestRule是必須搭配、 @DualScreenTest 和批註一起使用 @SingleScreenTest 的自訂 TestRule 。 @DeviceOrientation@MockFoldingFeature 如果此測試規則未與批註搭配使用，批註將無法運作。這會 TestRule 使用反映來擷取這些注釋和參數，以在所需的狀態和裝置方向上執行測試。

FoldableJUnit4ClassRunner

FoldableJUnit4ClassRunner是必須搭配、 @DualScreenTest 、 @MockFoldingFeature@DeviceOrientation 和 @TargetDevices 批註一起使用 @SingleScreenTest 的自訂 AndroidJUnit4ClassRunner 。此執行器會驗證批註的參數。當目前的裝置不在目標裝置清單中，或位於忽略的裝置清單中時，它會忽略測試。如果未使用， Runner 則不會驗證批註，而且 @TargetDevices 批註不會有任何作用。

注釋的條件約束

@SingleScreenTest、、 @DualScreenTest@MockFoldingFeature 無法一起使用。例如，您不能有相同的方法或與注釋 @DualScreenTest 標注 @SingleScreenTest 的相同測試類別。
無法一起使用 @TargetDevices.devices 和 @TargetDevices.ignoreDevices。例如，您無法有與批註 @TargetDevices(devices = [DeviceModel.SurfaceDuo, DeviceModel.SurfaceDuo2], ignoreDevices = [DeviceModel.Other]) 相同的方法或測試類別。

正確的使用方式： @TargetDevices(devices = [DeviceModel.SurfaceDuo]) 或 @TargetDevices(ignoreDevices = [DeviceModel.SurfaceDuo])
@MockFoldingFeature.windowBounds 應該是四個元素的陣列，表示顯示視窗的左、上、右、下座標。例如，您無法像這樣使用： @MockFoldingFeature(windowBounds = [0, 0, 0]) 或 @MockFoldingFeature(windowBounds = [0, 0, 0, 0, 0]) 。

共用方式為