Annotations du kit de test

Article
07/10/2023

Le kit de test fournit des annotations utilitaires qui permettent d’exécuter des tests pour une posture ou un type d’appareil spécifique. Si vous devez tester des flux d’application complexes qui changent selon plusieurs postures, vous devez simuler une fonctionnalité de pliage ou utiliser des mouvements de balayage à la place.

Dans le cas de tests plus simples qui n’utilisent qu’une seule posture, vous pouvez utiliser des annotations pour :

exécuter des tests en mode mono-écran ou double écran
exécuter des tests sur des appareils cibles spécifiques
exécuter des tests dans une orientation d’appareil spécifique
exécuter des tests avec une fonctionnalité de simulation de pliage

Important

Ces annotations fonctionnent uniquement avec FoldableTestRule et FoldableJUnit4ClassRunner. Dans la section Composants du kit de test ci-dessous, vous trouverez des informations sur leur utilisation avec les annotations.

Configuration

Créez un fichier de classe de test dans le répertoire androidTest. C’est là que vous ajouterez les extraits de code pour les tests et les règles de test.
Vérifiez que vous disposez du référentiel mavenCentral() dans votre fichier build.gradle de premier niveau :
```
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}
```

Ajoutez les dépendances suivantes au fichier build.gradle de niveau module (la version actuelle peut être différente de ce qui est illustré ici) :

Views
Composer.

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"

Vérifiez que compileSdkVersion et targetSdkVersion sont définis sur API 31 ou version ultérieure dans le fichier build.gradle au niveau du module :
```
android { 
    compileSdkVersion 31

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

Créez un TestRule qui peut effectuer des vérifications d’interface utilisateur et simuler des fonctionnalités de repli. Pour ce faire, vous pouvez chaîner deux règles : une règle FoldableTestRule et une règle ActivityScenarioRule ou AndroidComposeTestRule.

Vous pouvez utiliser la méthode foldableRuleChain pour créer la chaîne de règles, ou vous pouvez créer votre propre chaîne de règles, comme indiqué dans l’exemple suivant :

Views
Composer.

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

Si vous choisissez de créer votre propre chaîne de règles :

Pour les appareils SurfaceDuo et SurfaceDuo2, ActivityScenarioRule doit être la règle externe, car l’application doit avoir démarré avant les opérations span/unspan.
Pour les autres appareils de type tablette, FoldableTestRule doit être la règle externe, car FoldingFeature doit être simulé avant le lancement de l’application.

Si vous utilisez Espresso pour tester les affichages, veillez à désactiver les animations sur votre appareil.

Composants du kit de test

Important

Consultez les sections FoldableTestRule et FoldableJUnit4ClassRunner avant de commencer à utiliser les annotations suivantes.

SingleScreenTest/DualScreenTest

Ajoutez cette annotation pour la méthode de test ou la classe de test, si vous souhaitez exécuter le test en mode mono-écran/double écran. De plus, à l’aide du paramètre orientation, vous pouvez exécuter le test dans l’orientation d’appareil spécifiée. Le paramètre orientation peut avoir les valeurs suivantes : UiAutomation.ROTATION_FREEZE_0, UiAutomation.ROTATION_FREEZE_90, UiAutomation.ROTATION_FREEZE_180, UiAutomation.ROTATION_FREEZE_270

Views
Composer.

@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

Utilisez cette annotation pour la méthode de test ou la classe de test, si vous souhaitez simuler la fonctionnalité de pliage avec les données souhaitées.

Le paramètre windowBounds est un tableau de coordonnées qui représente une zone d’affichage destinée à contenir FoldingFeature, par exemple [gauche, haut, droite, bas]. La largeur et la hauteur de windowBounds doivent être supérieures à 0. Par défaut, si vous ne définissez pas vos propres valeurs windowBounds, toute la zone d’affichage est utilisée, [0, 0, uiDevice.displayWidth, uiDevice.displayHeight].
Le paramètre center est le centre du pli complémentaire à l’orientation. Pour un pli HORIZONTAL, il s’agit de l’axe Y et pour un pli VERTICAL, il s’agit de l’axe X. La valeur par défaut est -1. Si ce paramètre n’est pas fourni, il est calculé en fonction du paramètre windowBounds sous la forme windowBounds.centerY() ou windowBounds.centerX(), en fonction du orientation spécifié.
Le paramètre size est la plus petite dimension du pli. La plus grande dimension couvre toujours la totalité de la fenêtre. La valeur par défaut est 0.
Le paramètre state représente l’état du pli. Les valeurs possibles sont FoldingFeatureState.HALF_OPENED et FoldingFeatureState.FLAT. La valeur par défaut est FoldingFeatureState.HALF_OPENED. Consultez la section Posture dans la documentation officielle pour obtenir des exemples visuels et des références.
Le paramètre orientation représente l’ orientation du pli. Les valeurs possibles sont FoldingFeatureOrientation.HORIZONTAL et FoldingFeatureOrientation.VERTICAL. La valeur par défaut est FoldingFeatureOrientation.HORIZONTAL.

Views
Composer.

@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

Utilisez cette annotation pour la méthode de test ou la classe de test, si vous souhaitez exécuter le test uniquement sur les appareils spécifiés, ou si vous souhaitez ignorer certains appareils.

Le paramètre devices est un tableau des appareils souhaités alors que le paramètre ignoreDevices est un tableau des appareils à ignorer.

Exemple d’utilisation : @TargetDevices(devices = [DeviceModel.SurfaceDuo, DeviceModel.SurfaceDuo2]), @TargetDevices(ignoreDevices = [DeviceModel.SurfaceDuo])

Vous ne pouvez pas utiliser les deux paramètres en même temps.

Valeurs possibles pour le modèle d’appareil :

DeviceModel.SurfaceDuo - représentation pour l’appareil ou l’émulateur SurfaceDuo1
DeviceModel.SurfaceDuo2 - représentation pour l’appareil et l’émulateur SurfaceDuo2
DeviceModel.HorizontalFoldIn - représentation pour les appareils et les émulateurs 6.7" horizontal Fold-In
DeviceModel.FoldInOuterDisplay - représentation pour 7.6" Fold-In avec des émulateurs et des périphériques d’affichage externes
DeviceModel.FoldOut - représentation pour les appareils et les émulateurs 8" FoldOut
DeviceModel.Other - représentation pour d’autres appareils et émulateurs de type tablette

Views
Composer.

@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

Utilisez cette annotation pour la méthode de test ou la classe de test, si vous souhaitez exécuter le test dans l’orientation d’appareil spécifiée.

Le paramètre orientation représente l’orientation de l’appareil et peut avoir les valeurs suivantes : UiAutomation.ROTATION_FREEZE_0, UiAutomation.ROTATION_FREEZE_90, UiAutomation.ROTATION_FREEZE_180, UiAutomation.ROTATION_FREEZE_270

Views
Composer.

@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 est un TestRule personnalisé qui doit être utilisé avec les annotations @SingleScreenTest, @DualScreenTest, @MockFoldingFeature et @DeviceOrientation. Les annotations ne fonctionneront pas sans l’utilisation de cette règle de test. Ce TestRule utilise la réflexion pour récupérer ces annotations et paramètres afin d’exécuter les tests dans la posture et l’orientation d’appareil souhaitées.

FoldableJUnit4ClassRunner

FoldableJUnit4ClassRunner est un AndroidJUnit4ClassRunner personnalisé qui doit être utilisé avec les annotations @SingleScreenTest, @DualScreenTest, @MockFoldingFeature, @DeviceOrientation et @TargetDevices. Cet exécuteur valide les paramètres des annotations. Il ignore les tests quand l’appareil actuel ne figure pas dans la liste des appareils cibles ou dans la liste des appareils ignorés. Si ce Runner n’est pas utilisé, les annotations ne sont pas validées, et l’annotation @TargetDevices n’a aucun effet.

Contraintes relatives aux annotations

@SingleScreenTest, @DualScreenTest, @MockFoldingFeature ne peuvent pas être utilisés ensemble. Par exemple, vous ne pouvez pas avoir la même méthode ou la même classe de test annotée avec les annotations @SingleScreenTest et @DualScreenTest.
@TargetDevices.devices et @TargetDevices.ignoreDevices ne peuvent pas être utilisés conjointement. Par exemple, vous ne pouvez pas avoir la même méthode ou la même classe de test annotée avec @TargetDevices(devices = [DeviceModel.SurfaceDuo, DeviceModel.SurfaceDuo2], ignoreDevices = [DeviceModel.Other]).

Utilisation correcte : @TargetDevices(devices = [DeviceModel.SurfaceDuo]) ou @TargetDevices(ignoreDevices = [DeviceModel.SurfaceDuo])
@MockFoldingFeature.windowBounds doit être un tableau de quatre éléments représentant les coordonnées de gauche, du haut, de droite et du bas de la fenêtre d’affichage. Par exemple, vous ne pouvez pas l’utiliser comme ceci : @MockFoldingFeature(windowBounds = [0, 0, 0]) ou @MockFoldingFeature(windowBounds = [0, 0, 0, 0, 0]).

Partager via