Eseguire test sulle modifiche alla configurazione dello schermo con l'API Espresso Device

Utilizza l'API Espresso Device per testare la tua app quando il dispositivo subisce modifiche comuni alla configurazione, come la rotazione e l'apertura dello schermo. L'API Espresso Device è lo strumento consigliato per eseguire azioni a livello di dispositivo insieme alle regole di test di Jetpack Compose. Se non hai mai scritto test UI per Jetpack Compose, consulta Testare il layout di Compose.

L'API Espresso Device ti consente di attivare modifiche alla configurazione su un dispositivo virtuale ed eseguire i test in modo sincrono, in modo che venga eseguita una sola azione o asserzione dell'interfaccia utente alla volta e i risultati dei test siano più affidabili. Se non hai mai scritto test dell'interfaccia utente con Espresso, consulta la relativa documentazione.

Per utilizzare l'API Espresso Device, devi disporre di quanto segue:

  • Android Studio Iguana o versioni successive
  • Plug-in Android per Gradle 8.3 o versioni successive
  • Emulatore Android 33.1.10 o versioni successive
  • Dispositivo virtuale Android che esegue il livello API 24 o versioni successive

Configura il progetto per l'API Espresso Device

Per configurare il progetto in modo che supporti l'API Espresso Device, procedi nel seguente modo:

  1. Per consentire al test di passare comandi al dispositivo di test, aggiungi le autorizzazioni di rete richieste al file manifest nel set di risorse androidTest:

      <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    Se il test ha come target Android 17 (livello API 37) o versioni successive, devi anche dichiarare l'autorizzazione ACCESS_LOCAL_NETWORK:

      <uses-permission android:name="android.permission.ACCESS_LOCAL_NETWORK" />

  2. Attiva il flag sperimentale enableEmulatorControl nel file gradle.properties:

      android.experimental.androidTest.enableEmulatorControl=true

  3. Attiva l'opzione emulatorControl nello script di build a livello di modulo:

    Kotlin

      testOptions {
    emulatorControl {
      enable = true
    }
  }

    Alla moda

      testOptions {
    emulatorControl {
      enable = true
    }
  }

  4. Nello script di build a livello di modulo, importa la libreria Espresso Device nel tuo progetto:

    Kotlin

    dependencies {
  androidTestImplementation("androidx.test.espresso:espresso-device:1.1.0")
}

    Alla moda

    dependencies {
  androidTestImplementation 'androidx.test.espresso:espresso-device:1.1.0'
}

Testare le modifiche comuni alla configurazione

L'API Espresso Device ha più orientamenti dello schermo e stati di piegatura che puoi utilizzare per attivare modifiche alla configurazione del dispositivo. Gli esempi riportati di seguito mostrano come attivare questi stati del dispositivo e verificare le modifiche alla UI risultanti utilizzando le regole di test di Compose.

Testare la rotazione dello schermo

Per testare la rotazione dello schermo, puoi utilizzare la classe ScreenOrientationRule per definire l'orientamento del dispositivo durante il test.

Ecco un esempio di come testare cosa succede alla tua app quando lo schermo del dispositivo ruota:

  1. Innanzitutto, definisci la regola di test di Compose e utilizza la classe ScreenOrientationRule per impostare il dispositivo su uno stato iniziale coerente (ad esempio la modalità ritratto):

    import androidx.compose.ui.test.assertIsDisplayed
import androidx.compose.ui.test.assertDoesNotExist
import androidx.compose.ui.test.junit4.createComposeRule
import androidx.compose.ui.test.onNodeWithTag
import androidx.test.espresso.device.EspressoDevice.onDevice
import androidx.test.espresso.device.action.ScreenOrientation
import androidx.test.espresso.device.rules.ScreenOrientationRule
import org.junit.Rule
import org.junit.Test

class MyConfigurationTest {

    // 1. Define the Compose test rule
    @get:Rule
    val composeTestRule = createComposeRule()

    // 2. Define the Espresso Device rule for a consistent starting state
    @get:Rule
    val screenOrientationRule = ScreenOrientationRule(ScreenOrientation.PORTRAIT)
}

    Se il test ha come target Android 17 (livello API 37) o versioni successive, l'API Espresso Device richiede l'autorizzazione ACCESS_LOCAL_NETWORK. Devi assicurarti che questa autorizzazione venga concessa prima dell'esecuzione della regola ScreenOrientationRule. Utilizza RuleChain di JUnit per eseguire prima la regola GrantPermissionRule:

    import androidx.test.rule.GrantPermissionRule
import org.junit.rules.RuleChain

class MyConfigurationTest {
    val grantPermissionRule = GrantPermissionRule.grant(android.Manifest.permission.ACCESS_LOCAL_NETWORK)
    val composeTestRule = createComposeRule()
    val screenOrientationRule = ScreenOrientationRule(ScreenOrientation.PORTRAIT)

    @get:Rule
    val chain = RuleChain
        .outerRule(grantPermissionRule)
        .around(composeTestRule)
        .around(screenOrientationRule)
}

  2. Crea un test che imposta l'orientamento orizzontale del dispositivo durante l'esecuzione del test:

    @Test
fun myRotationTest() {
  ...
  // Sets the device to landscape orientation during test execution.
  onDevice().setScreenOrientation(ScreenOrientation.LANDSCAPE)
  ...
}

  3. Dopo la rotazione dello schermo, utilizza composeTestRule per verificare che i composables si adattino al nuovo stato come previsto.

    @Test
fun myRotationTest() {
  ...
  // Sets the device to landscape orientation during test execution.
  onDevice().setScreenOrientation(ScreenOrientation.LANDSCAPE)
  composeTestRule.onNodeWithTag("NavRail").assertIsDisplayed()
  composeTestRule.onNodeWithTag("BottomBar").assertDoesNotExist()
}

Testare l'apertura dello schermo

Ecco un esempio di come testare cosa succede alla tua app se si trova su un dispositivo pieghevole e lo schermo si apre:

  1. Innanzitutto, prova con il dispositivo chiuso chiamando onDevice().setClosedMode(). Assicurati che i tuoi composable si adattino alla larghezza dello schermo compatto.

    @Test
fun myUnfoldedTest() {
  onDevice().setClosedMode()
  composeTestRule.onNodeWithTag("BottomBar").assertIsDisplayed()
  composeTestRule.onNodeWithTag("NavRail").assertDoesNotExist()
  ...
}

  2. Per passare a uno stato completamente aperto, chiama onDevice().setFlatMode(). Verifica che i composable si adattino alla classe di dimensioni espansa.

    @Test
fun myUnfoldedTest() {
  onDevice().setClosedMode()
  ...
  onDevice().setFlatMode()
  composeTestRule.onNodeWithTag("NavRail").assertIsDisplayed()
  composeTestRule.onNodeWithTag("BottomBar").assertDoesNotExist()
}

Specifica i dispositivi necessari per i test

Se esegui un test che esegue azioni di piegatura su un dispositivo non pieghevole, è probabile che il test non vada a buon fine. Per eseguire solo i test pertinenti al dispositivo in esecuzione, utilizza l'annotazione @RequiresDeviceMode. Il test runner salta automaticamente l'esecuzione dei test sui dispositivi che non supportano la configurazione in fase di test. Puoi aggiungere la regola relativa ai requisiti del dispositivo a ogni test o a un'intera classe di test.

Ad esempio, per specificare che un test deve essere eseguito solo sui dispositivi che supportano l'apertura in una configurazione piatta, aggiungi il seguente codice @RequiresDeviceMode al test:

@Test
@RequiresDeviceMode(mode = FLAT)
fun myUnfoldedTest() {
  ...
}