Mit der Espresso Device API auf Änderungen der Bildschirmkonfiguration testen

Mit der Espresso Device API können Sie Ihre App testen, wenn das Gerät häufigen Konfigurationsänderungen unterzogen wird, z. B. Drehen und Aufklappen des Displays. Die Espresso Device API ist das empfohlene Tool zum Simulieren von Aktionen auf Geräteebene zusammen mit Ihren Jetpack Compose-Testregeln. Wenn Sie noch keine UI-Tests für Jetpack Compose geschrieben haben, lesen Sie den Artikel Compose-Layout testen.

Mit der Espresso Device API können Sie Konfigurationsänderungen auf einem virtuellen Gerät simulieren und Ihre Tests synchron ausführen. So erfolgt immer nur eine UI-Aktion oder ‑Assertion und Ihre Testergebnisse sind zuverlässiger. Wenn Sie noch keine UI Tests mit Espresso geschrieben haben, lesen Sie die Dokumentation.

Für die Verwendung der Espresso Device API benötigen Sie Folgendes:

  • Android Studio Iguana oder höher
  • Android-Gradle-Plug-in 8.3 oder höher
  • Android Emulator 33.1.10 oder höher
  • Virtuelles Android-Gerät mit API-Level 24 oder höher

Projekt für die Espresso Device API einrichten

So richten Sie Ihr Projekt ein, damit es die Espresso Device API unterstützt:

  1. Damit der Test Befehle an das Testgerät übergeben kann, fügen Sie der Manifestdatei im androidTest Source-Set die Berechtigungen INTERNET und ACCESS_NETWORK_STATE hinzu:

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

  2. Aktivieren Sie das experimentelle Flag enableEmulatorControl in der Datei gradle.properties:

      android.experimental.androidTest.enableEmulatorControl=true

  3. Aktivieren Sie die Option emulatorControl im Build-Skript auf Modulebene:

    Kotlin

      testOptions {
    emulatorControl {
      enable = true
    }
  }

    Groovy

      testOptions {
    emulatorControl {
      enable = true
    }
  }

  4. Importieren Sie im Build-Skript auf Modulebene die Espresso Device-Bibliothek in Ihr Projekt:

    Kotlin

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

    Groovy

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

Tests für häufige Konfigurationsänderungen

Die Espresso Device API bietet mehrere Ausrichtungen und faltbare Zustände, mit denen Sie Änderungen an der Gerätekonfiguration simulieren können. In den folgenden Beispielen wird gezeigt, wie Sie diese Gerätezustände auslösen und die resultierenden UI-Änderungen mit Compose-Testregeln überprüfen.

Tests für das Drehen des Displays

Hier ein Beispiel dafür, wie Sie testen können, was mit Ihrer App passiert, wenn das Display des Geräts gedreht wird:

  1. Definieren Sie zuerst Ihre Compose-Testregel und legen Sie für das Gerät einen einheitlichen Startzustand fest (z. B. Hochformat):

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

  2. Erstellen Sie einen Test, der das Gerät während der Testausführung in den Querformatmodus versetzt:

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

  3. Nachdem das Display gedreht wurde, prüfen Sie mit composeTestRule, ob sich Ihre komponierbaren Funktionen wie erwartet an den neuen Zustand anpassen.

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

Tests für das Aufklappen des Displays

Hier ein Beispiel dafür, wie Sie testen können, was mit Ihrer App passiert, wenn sie auf einem faltbaren Gerät ausgeführt wird und das Display aufgeklappt wird:

  1. Testen Sie zuerst mit dem Gerät im zusammengeklappten Zustand, indem Sie onDevice().setClosedMode() aufrufen. Prüfen Sie, ob sich Ihre Composables an die schmale Displaybreite anpassen.

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

  2. Um in den vollständig aufgeklappten Zustand zu wechseln, rufen Sie onDevice().setFlatMode() auf. Prüfen Sie, ob sich die Composables an die erweiterte Größenklasse anpassen.

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

Erforderliche Geräte für Tests angeben

Wenn Sie einen Test ausführen, bei dem Faltaktionen auf einem nicht faltbaren Gerät ausgeführt werden, schlägt der Test wahrscheinlich fehl. Verwenden Sie die Annotation @RequiresDeviceMode, um nur die Tests auszuführen, die für das aktuelle Gerät relevant sind. Der Testrunner überspringt automatisch Tests auf Geräten, die die getestete Konfiguration nicht unterstützen. Sie können die Regel für Geräteanforderungen jedem Test oder einer gesamten Testklasse hinzufügen.

Wenn Sie beispielsweise festlegen möchten, dass ein Test nur auf Geräten ausgeführt werden soll, die das Aufklappen in eine flache Konfiguration unterstützen, fügen Sie Ihrem Test den folgenden @RequiresDeviceMode-Code hinzu:

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