Tests über Befehlszeile durchführen

In diesem Dokument wird beschrieben, wie Sie Tests direkt über die Befehlszeile ausführen. In diesem Dokument wird davon ausgegangen, dass Sie bereits wissen, wie Sie eine Android-App erstellen und Tests für Ihre App schreiben können. Weitere Informationen zum Erstellen von Tests für Ihre App finden Sie unter Apps auf Android-Geräten testen.

Wenn Sie Ihre App mit dem Gradle-Build-System erstellen, können Sie mit dem Android Gradle-Plug-in Tests über Ihr Gradle-Projekt über die Befehlszeile ausführen. Für eine genauere Steuerung können Sie Ihre Tests über eine Android Debug Bridge (ADB)-Shell ausführen. Dies kann nützlich sein, wenn Tests in einer Umgebung mit Continuous Integration ausgeführt werden.

Informationen zum Ausführen automatisierter instrumentierter Tests über die Befehlszeile mit virtuellen Geräten, die Gradle für Sie verwaltet, finden Sie unter Tests mit Gradle Managed Devices skalieren.

Tests mit Gradle ausführen

Mit dem Android-Gradle-Plug-in können Sie Tests von Ihrem Gradle-Projekt aus über die Befehlszeile ausführen.

In der folgenden Tabelle ist zusammengefasst, wie Sie Ihre Tests mit Gradle ausführen:

Tabelle 1 Verschiedene Möglichkeiten zum Ausführen von Tests mit Gradle

Unittesttyp Auszuführender Befehl Ort des Testergebnisses
Lokaler Unittest Führen Sie die Aufgabe test aus:

./gradlew test
HTML-Testergebnisdateien:
path_to_your_project/module_name/build/reports/tests/ Verzeichnis.

XML-Testergebnisdateien:
path_to_your_project/module_name/build/test-results/ Verzeichnis.

Instrumentierter Einheitentest Führen Sie die Aufgabe connectedAndroidTest aus:

./gradlew connectedAndroidTest
HTML-Testergebnisdateien:
path_to_your_project/module_name/build/reports/androidTests/connected/ Verzeichnis.

XML-Testergebnisdateien:
path_to_your_project/module_name/build/outputs/androidTest-results/connected/ Verzeichnis.

Gradle unterstützt Abkürzungen für Aufgabennamen. Sie können z. B. die Aufgabe connectedAndroidTest initiieren, indem Sie den folgenden Befehl eingeben:

./gradlew cAT

Du kannst auch die Gradle-Tasks check und connectedCheck ausführen. Diese Aufgaben führen Ihre lokalen bzw. instrumentierten Tests aus, umfassen aber auch andere Prüfungen, die von anderen Gradle-Plug-ins hinzugefügt wurden.

Tests für ein Modul ausführen

Die Aufgaben test und connectedAndroidTest führen Tests für jedes Modul in Ihrem Projekt aus. Sie können Tests für ein bestimmtes Modul ausführen, indem Sie der Aufgabe test oder connectedAndroidTest den Modulnamen und einen Doppelpunkt (:) voranstellen. Mit dem folgenden Befehl werden beispielsweise instrumentierte Tests nur für das Modul mylibrary ausgeführt:

./gradlew mylibrary:connectedAndroidTest

Tests für eine Build-Variante ausführen

Mit den Aufgaben test und connectedAndroidTest werden Tests für jede Build-Variante in Ihrem Projekt ausgeführt. Mithilfe der folgenden Syntax können Sie ein Targeting auf eine bestimmte Build-Variante vornehmen:

  • Für lokale Einheitentests:
    ./gradlew testVariantNameUnitTest
  • Für instrumentierte Tests:
    ./gradlew connectedVariantNameAndroidTest

Bestimmte Testmethoden oder -klassen ausführen

Wenn Sie lokale Einheitentests ausführen, können Sie mit Gradle bestimmte Tests mit dem Flag --tests ausrichten. Mit dem folgenden Befehl werden beispielsweise nur die sampleTestMethod-Tests für die angegebene Build-Variante ausgeführt. Weitere Informationen zum Verwenden des Flags --tests finden Sie in der Gradle-Dokumentation zur Testfilterung.


./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'

Berichte mit mehreren Modulen für instrumentierte Tests

Wie in Tabelle 1 beschrieben, speichert Gradle instrumentierte Testergebnisse im Verzeichnis build/ jedes Moduls, das getestet wird. Wenn Sie jedoch Tests über mehrere Module hinweg ausführen, kann es sinnvoll sein, alle Testergebnisse in einem einzigen Bericht zusammenzufassen. So erstellen Sie beim Ausführen von Tests für mehrere Module einen einzelnen Bericht:

  1. Fügen Sie in der Datei build.gradle auf Projektebene nach dem Block buildscript{} Folgendes hinzu:

    Groovig

    apply plugin: 'android-reporting'
    

    Kotlin

    apply(plugin = "android-reporting")
    
  2. Rufen Sie die Aufgabe test oder connectedAndroidTest mit der Aufgabe mergeAndroidReports auf. Beispiele:

    ./gradlew connectedAndroidTest mergeAndroidReports
    

    Wenn Sie Testfehler überspringen möchten, sodass Gradle alle verbleibenden Tests beendet, fügen Sie die Option --continue hinzu:

    ./gradlew connectedAndroidTest mergeAndroidReports --continue
    

Wenn Gradle die Ausführung der Tests abgeschlossen hat, werden die kombinierten Ergebnisse im Verzeichnis path_to_your_project/build/ gespeichert.

Tests mit ADB ausführen

Wenn Sie Tests mit Android Debug Bridge (ADB) über die Befehlszeile ausführen, stehen mehr Optionen zur Auswahl der auszuführenden Tests zur Verfügung als mit jeder anderen Methode. Sie können einzelne Testmethoden auswählen, Tests anhand einer benutzerdefinierten Annotation filtern oder Testoptionen angeben. Da der Testlauf vollständig über die Befehlszeile gesteuert wird, können Sie ihn mit Shell-Skripts auf verschiedene Arten anpassen.

Wenn Sie einen Test über die Befehlszeile ausführen möchten, führen Sie adb shell aus, um eine Befehlszeilen-Shell auf Ihrem Gerät oder Emulator zu starten. Innerhalb dieser Shell können Sie mit dem Aktivitätsmanager mit dem Befehl am und dem Unterbefehl instrument interagieren.

Als Abkürzung können Sie eine ADB-Shell starten, am instrument aufrufen und Befehlszeilen-Flags in einer Eingabezeile angeben. Die Shell wird auf dem Gerät oder Emulator geöffnet, führt die Tests aus, erzeugt die Ausgabe und kehrt dann zur Befehlszeile auf Ihrem Computer zurück.

So führen Sie einen Test mit am instrument aus:

  1. Erstellen Sie einen neuen Build Ihrer Hauptanwendung und Ihr Testpaket.
  2. Installieren Sie das Testpaket und die Android-Hauptanwendungspaketdateien (APK-Dateien) auf Ihrem aktuellen Android-Gerät oder Emulator.
  3. Geben Sie in der Befehlszeile Folgendes ein:

    adb shell am instrument -w <test_package_name>/<runner_class>
    

    Dabei ist <test_package_name> der Android-Paketname Ihrer Test-App und <runner_class> der Name der Android-Test-Runner-Klasse, die Sie verwenden. Der Android-Paketname ist der Wert des Paketattributs des Manifestelements in der Manifestdatei des Testpakets (AndroidManifest.xml).

    Die Android-Test-Runner-Klasse ist in der Regel AndroidJUnitRunner:

    adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner
    

Deine Testergebnisse werden in STDOUT angezeigt.

instrumente flaggen

Führen Sie adb shell am help aus, um eine Liste aller Flags abzurufen, die mit dem Befehl am instrument verwendet werden sollen. In der folgenden Tabelle werden einige wichtige Flags beschrieben:

Tabelle 2 Wichtige am instrument-Flags

Melden Antwort Beschreibung
-w (keine) Erzwingt, dass am instrument wartet, bis die Instrumentierung beendet wird, bevor sie sich selbst beendet. Dadurch bleibt die Shell geöffnet, bis die Tests abgeschlossen sind. Dieses Flag ist erforderlich, um die Ergebnisse Ihrer Tests anzusehen.
-r (keine) Gibt Ergebnisse im Rohformat aus. Verwenden Sie dieses Flag, wenn Sie Leistungsmessungen erfassen möchten, damit sie nicht als Testergebnisse formatiert werden. Dieses Flag ist zur Verwendung mit dem Flag -e perf true vorgesehen (dokumentiert im Abschnitt am instrument options).
-e <test_options> Stellt Testoptionen als Schlüssel/Wert-Paare bereit. Das am instrument-Tool übergibt diese mithilfe seiner Methode onCreate() an die angegebene Instrumentierungsklasse. Sie können -e <test_options> mehrmals angeben. Die Schlüssel und Werte werden im Abschnitt am instrument options beschrieben. Sie können diese Schlüssel/Wert-Paare nur mit AndroidJUnitRunner oder mit InstrumentationTestRunner und den zugehörigen abgeleiteten Klassen verwenden. Die Verwendung mit einer anderen Klasse hat keine Auswirkungen.
--no-hidden-api-checks (keine) Deaktiviert Einschränkungen für die Verwendung ausgeblendeter APIs. Weitere Informationen zu ausgeblendeten APIs und deren Auswirkungen auf Ihre Anwendung finden Sie unter Einschränkungen für Nicht-SDK-Schnittstellen.

am instrument optionen

Das am instrument-Tool übergibt Testoptionen mithilfe des Flags -e und mit der folgenden Syntax an AndroidJUnitRunner oder InstrumentationTestRunner in Form von Schlüssel/Wert-Paaren:

-e <key> <value>

Einige Schlüssel akzeptieren mehrere Werte. Sie geben mehrere Werte in einer durch Kommas getrennten Liste an. Dieser Aufruf von AndroidJUnitRunner liefert beispielsweise mehrere Werte für den Schlüssel package:

adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
> com.android.test/androidx.test.runner.AndroidJUnitRunner

In der folgenden Tabelle sind die Schlüssel/Wert-Paare aufgeführt, die Sie mit dem Test-Runner verwenden können:

Tabelle 3 -e-Flag-Schlüssel/Wert-Paare zur Verwendung mit dem Test-Runner.

Schlüssel Antwort Beschreibung
package <Java_package_name> Der voll qualifizierte Java-Paketname für eines der Pakete in der Testanwendung. Jede Testlaufklasse, die diesen Paketnamen verwendet, wird ausgeführt. Beachte, dass dies kein Android-Paketname ist. Ein Testpaket hat einen einzelnen Android-Paketnamen, kann jedoch mehrere Java-Pakete enthalten.
class <class_name> Der voll qualifizierte Java-Klassenname für eine der Testlaufklassen. Nur diese Testlaufklasse wird ausgeführt.
<class_name>#method name Ein voll qualifizierter Testlaufklassenname und eine seiner Methoden. Nur diese Methode wird ausgeführt. Notieren Sie sich das Rautezeichen (#) zwischen dem Klassennamen und dem Methodennamen.
func true Führt alle Testklassen aus, die InstrumentationTestCase erweitern.
unit true Führt alle Testklassen aus, die nicht entweder InstrumentationTestCase oder PerformanceTestCase erweitern.
size [small | medium | large] Führt eine Testmethode aus, die nach Größe annotiert ist. Die Annotationen sind @SmallTest, @MediumTest und @LargeTest.
perf true Führt alle Testklassen aus, die PerformanceTestCase implementieren. Wenn Sie diese Option verwenden, geben Sie das Flag -r für am instrument an, damit die Ausgabe im Rohformat gespeichert und nicht als Testergebnisse neu formatiert wird.
debug true Führt Tests im Debug-Modus aus.
log true Lädt alle angegebenen Tests und protokolliert sie, führt sie aber nicht aus. Die Testinformationen werden in STDOUT angezeigt. Hiermit kannst du Kombinationen aus anderen Filtern und Testspezifikationen überprüfen.
emma true Führt eine EMMA-Codeabdeckungsanalyse durch und schreibt die Ausgabe in /data/<app_package>/coverage.ec auf dem Gerät. Wenn Sie den Dateispeicherort überschreiben möchten, verwenden Sie den Schlüssel coverageFile, der im folgenden Eintrag beschrieben wird.

Hinweis:Für diese Option ist ein EMMA-instrumentierter Build der Testanwendung erforderlich, den Sie mit dem Ziel coverage generieren können.

coverageFile <filename> Überschreibt den Standardspeicherort der EMMA-Abdeckungsdatei auf dem Gerät. Geben Sie diesen Wert als Pfad und Dateinamen im UNIX-Format an. Der Standarddateiname wird im Eintrag für den Schlüssel emma beschrieben.

Beachten Sie bei der Verwendung des Flags -e Folgendes:

  • am instrument ruft onCreate(Bundle) mit einer Bundle auf, die die Schlüssel/Wert-Paare enthält.
  • Der Schlüssel package hat Vorrang vor dem Schlüssel class. Wenn du ein Paket und dann separat eine Klasse innerhalb dieses Pakets angibst, führt Android alle Tests im Paket aus und ignoriert den Klassenschlüssel.
  • Der Schlüssel func und der Schlüssel unit schließen sich gegenseitig aus.

Beispiele für die Verwendung

Die folgenden Abschnitte enthalten Beispiele für die Verwendung von am instrument zum Ausführen von Tests. Sie basieren auf der folgenden Struktur:

  • Das Testpaket hat den Android-Paketnamen com.android.demo.app.tests.
  • Zwei instrumentierte Testklassen:
    • TestClass1, die die Testmethode testMethod1 enthält.
    • TestClass2, die die Testmethoden testMethod2 und testMethod3 enthält.
  • Der Test-Runner ist AndroidJUnitRunner.

Gesamtes Testpaket ausführen

Um alle Testklassen im Testpaket auszuführen, gib Folgendes ein:

adb shell am instrument -w com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Alle Tests in einer Testlaufklasse ausführen

Um alle Tests in der Klasse TestClass1 auszuführen, geben Sie Folgendes ein:

adb shell am instrument -w  \
> -e class com.android.demo.app.tests.TestClass1 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Eine Untergruppe von Tests auswählen

Geben Sie Folgendes ein, um alle Tests in der Klasse TestClass1 und der Methode testMethod3 in TestClass2 auszuführen:

adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1,com.android.demo.app.tests.TestClass2#testMethod3 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Weitere Anwendungsfälle finden Sie in der API-Referenz AndroidJUnitRunner.