Tests über Befehlszeile durchführen

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

Die auf dieser Seite beschriebenen Befehlszeilentools und Gradle-Aufgaben sind unabhängig vom UI-Toolkit. Wenn Sie UI-Tests für Compose schreiben möchten, lesen Sie den Hilfeartikel Compose-Layout testen. Nachdem Sie Ihre Tests geschrieben haben, können Sie sie mit dieser Anleitung über das Terminal oder die Remote-Umgebung für die Continuous Integration ausführen.

Wenn Sie Ihre App mit dem Gradle-Buildsystem erstellen, können Sie mit dem Android Gradle Plug-in Tests über die Befehlszeile in Ihrem Gradle Projekt ausführen. Für eine detailliertere Steuerung können Sie Ihre Tests über eine Android Debug Bridge (adb) Shell ausführen. Das kann nützlich sein, wenn Sie Tests in einer CI-Umgebung ausführen.

Informationen zum Ausführen automatisierter Instrumentierungstests über die Befehlszeile mit virtuellen Geräten, die von Gradle verwaltet werden, finden Sie unter Tests mit von Gradle verwalteten Geräten skalieren.

Tests mit Gradle ausführen

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

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

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

Art des Unittests	Ausführungsbefehl	Speicherort der Testergebnisse
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 Unittest	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 beispielsweise die Aufgabe connectedAndroidTest starten, indem Sie den folgenden Befehl eingeben:

./gradlew cAT

Sie können auch die Gradle-Aufgaben check und connectedCheck ausführen. Mit diesen Aufgaben werden Ihre lokalen oder Instrumentierungstests ausgeführt, aber auch andere Prüfungen, die von anderen Gradle-Plug-ins hinzugefügt wurden.

Tests für ein Modul ausführen

Mit den Aufgaben test und connectedAndroidTest werden Tests für jedes Modul in Ihrem Projekt ausgeführt. 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 Instrumentierungstests 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. Sie können eine bestimmte Build-Variante mit der folgenden Syntax auswählen:

• Für lokale Unittests:

  ./gradlew testVariantNameUnitTest

• Für Instrumentierungstests:

  ./gradlew connectedVariantNameAndroidTest

Hinweis: Wenn Sie die ausgeführten Tests weiter einschränken möchten, wählen Sie eine bestimmte Build-Variante in einem bestimmten Modul aus. Verwenden Sie beispielsweise ./gradlew mylibrary:connectedVariantNameUnitTest um alle Unittests für die Variante VariantName im Modul mylibrary auszuführen.

Bestimmte Testmethoden oder -klassen ausführen

Beim Ausführen lokaler Unittests können Sie mit Gradle bestimmte Tests mit dem Flag --tests auswählen. Mit dem folgenden Befehl werden beispielsweise nur die sampleTestMethod-Tests für die angegebene Build-Variante ausgeführt. Weitere Informationen zur Verwendung des Flags --tests finden Sie in der Gradle-Dokumentation zum Testfiltern.

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

Hinweis: Wenn Sie bestimmte Testmethoden oder -klassen für Ihre Instrumentierungstests ausführen möchten, führen Sie die Tests mit ADB aus.

Tests mit adb ausführen

Wenn Sie Tests über die Befehlszeile mit Android Debug Bridge (adb) ausführen, haben Sie mehr Möglichkeiten, die auszuführenden Tests auszuwählen, als mit jeder anderen Methode. Sie können einzelne Testmethoden auswählen, Tests nach einer benutzerdefinierten Annotation filtern oder Testoptionen angeben. Da die Testausführung vollständig über die Befehlszeile gesteuert wird, können Sie Ihre Tests mit Shell-Skripten auf verschiedene Weise anpassen.

Führen Sie adb shell aus, um eine Befehlszeilen-Shell auf Ihrem Gerät oder Emulator zu starten. In dieser Shell können Sie mit dem Aktivitätsmanager mit dem am Befehl interagieren und mit dem instrument Unterbefehl Ihre Tests ausführen.

Alternativ 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 Ihre Tests aus, erzeugt eine Ausgabe und kehrt dann zur Befehlszeile auf Ihrem Computer zurück.

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

1. Erstellen oder erstellen Sie Ihre Hauptanwendung und Ihr Testpaket neu.
2. Installieren Sie die Android-Paketdateien (APK-Dateien) Ihres Testpakets und Ihrer Haupt anwendung 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 anwendung und <runner_class> der Name der Android-Testrunner-Klasse, die Sie verwenden. Der Android-Paketname ist der Wert des Paketattributs des Manifestelements in der Manifestdatei (AndroidManifest.xml) Ihres Testpakets.

   Die Android-Testrunner-Klasse ist normalerweise AndroidJUnitRunner:

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

Ihre Testergebnisse werden in STDOUT angezeigt.

am instrument-Flags

Eine Liste aller Flags, die Sie mit dem Befehl am instrument verwenden können, finden Sie unter adb shell am help. Einige wichtige Flags werden in der folgenden Tabelle beschrieben:

Tabelle 2. Wichtige am instrument-Flags

Flag	Wert	Beschreibung
-w	(keine)	Erzwingt, dass am instrument wartet, bis die Instrumentierung beendet ist, bevor es selbst beendet wird. Dadurch bleibt die Shell geöffnet, bis die Tests abgeschlossen sind. Dieses Flag ist erforderlich, um die Ergebnisse Ihrer Tests zu sehen.
-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 für die Verwendung mit dem Flag -e perf true vorgesehen (siehe Abschnitt Optionen für „am instrument“).
-e	<test_options>	Bietet Testoptionen als Schlüssel/Wert-Paare. Das am instrument Tool übergibt diese mit der Methode an die angegebene onCreate() Instrumentierungsklasse. Sie können -e <test_options> mehrmals angeben. Die Schlüssel und Werte werden im Abschnitt Optionen für „am instrument“ beschrieben. Sie können diese Schlüssel/Wert-Paare nur mit AndroidJUnitRunner verwenden. Die Verwendung mit einer anderen Klasse hat keine Auswirkungen.
--no-hidden-api-checks	(keine)	Deaktiviert Einschränkungen für die Verwendung verborgener APIs. Weitere Informationen zu verborgenen APIs und dazu, wie sich dies auf Ihre App auswirken kann, finden Sie unter Einschränkungen für Nicht-SDK-Schnittstellen.

Optionen für „am instrument“

Das Tool am instrument übergibt Testoptionen in Form von Schlüssel/Wert-Paaren mit dem Flag -e an AndroidJUnitRunner oder InstrumentationTestRunner. Die Syntax sieht so aus:

-e <key> <value>

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

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 Ihrem Testrunner verwenden können:

Tabelle 3. Schlüssel/Wert-Paare für das Flag „-e“, die mit dem Testrunner verwendet werden können

Schlüssel	Wert	Beschreibung
package	<Java_package_name>	Der voll qualifizierte Java-Paketname für eines der Pakete in der Testanwendung. Alle Testlaufklassen, die diesen Paketnamen verwenden, werden ausgeführt. Beachten Sie, dass dies kein Android-Paketname ist. Ein Testpaket hat einen einzigen Android-Paketnamen, kann aber mehrere Java-Pakete enthalten.
class	<class_name>	Der voll qualifizierte Java-Klassenname für eine der Testfall klassen. Nur diese Testfallklasse wird ausgeführt.
	<class_name>#method name	Ein voll qualifizierter Testlaufklassenname und eine seiner Methoden. Nur diese Methode wird ausgeführt. Beachten Sie das Hash-Zeichen (#) zwischen dem Klassen namen und dem Methodennamen.
size	[small | medium | large]	Führt eine Testmethode aus, die nach Größe annotiert ist. Die Annotationen sind @SmallTest, @MediumTest und @LargeTest.
debug	true	Führt Tests im Debug-Modus aus.
log	true	Lädt und protokolliert alle angegebenen Tests, führt sie aber nicht aus. Die Test Informationen werden in STDOUT angezeigt. Verwenden Sie diese Option, um Kombinationen anderer Filter und Testspezifikationen zu überprüfen.
emma	true	Führt eine EMMA-Codeabdeckungsanalyse aus und schreibt die Ausgabe auf dem Gerät in /data/<app_package>/coverage.ec. Wenn Sie den Speicherort der Datei überschreiben möchten, verwenden Sie den coverageFile Schlüssel der im folgenden Eintrag beschrieben wird. Hinweis: Für diese Option ist ein EMMA-instrumentierter Build der Testanwendung erforderlich, den Sie mit dem coverage Ziel 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 emma Schlüssel beschrieben.

Beachten Sie bei der Verwendung des Flags -e Folgendes:

• am instrument ruft onCreate(Bundle) mit einem Bundle auf, das die Schlüssel/Wert Paare enthält.
• Der Schlüssel package hat Vorrang vor dem Schlüssel class. Wenn Sie ein Paket und dann separat eine Klasse in diesem Paket angeben, führt Android alle Tests im Paket aus und ignoriert den Klassenschlüssel.
• Die Schlüssel func und unit schließen sich gegenseitig aus.

Hinweis: Wenn Sie Leistungs- und Benchmarktests über die Befehlszeile ausführen möchten, verwenden Sie nicht das Legacy- Flag -e perf true. Moderne Benchmarks verwenden eigene spezielle Instrumentierungsargumente. Weitere Informationen finden Sie unter Instrumentierungsargumente für Makrobenchmarks, Instrumentierungsargumente für Mikrobenchmarks, und Benchmark in Continuous Integration.

Anwendungsbeispiele

In den folgenden Abschnitten finden Sie 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 mit der Testmethode testMethod1.
  • TestClass2 mit den Testmethoden testMethod2 und testMethod3.
• Der Testrunner ist AndroidJUnitRunner.

Gesamtes Testpaket ausführen

Geben Sie Folgendes ein, um alle Testklassen im Testpaket auszuführen:

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

Alle Tests in einer Testlaufklasse ausführen

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

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

Teilmenge von Tests auswählen

Geben Sie Folgendes ein, um alle Tests in der Klasse TestClass1 und die 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 AndroidJUnitRunner API-Referenz.

Einheitliche Testberichte ansehen

Das Android-Gradle-Plug-in bietet einheitliche Testaufgaben, mit denen HTML-Dashboards generiert werden, in denen die zusammengeführten Ergebnisse von Unittests und Instrumentierungstests zusammengeführt werden.

Experimentell: Dies ist eine experimentelle Funktion. Wenn Sie diese Funktion aktivieren möchten, legen Sie in der Datei gradle.properties die Option android.experimental.reportAggregationSupport=true fest.

Voraussetzungen

• Android-Gradle-Plug-in 9.5.0-alpha05 oder höher.

Führen Sie eine der folgenden Aufgaben aus, um alle Test-Suites zu testen:

Berichtsumfang	Befehl	Beschreibung	Speicherort des Berichts
Aktuelles Modul	./gradlew :module_name:testAllSuites --continue	Generiert einen einheitlichen Testbericht für das aktuelle Modul, in dem die Ergebnisse von Unittests und Instrumentierungstests zusammengeführt werden.	path_to_your_project/module_name/build/reports/testAllSuites/test-report/
Aktuelles Modul und Abhängigkeiten	./gradlew :module_name:testAllSuitesWithDependencies --continue	Generiert einen einheitlichen Testbericht für das aktuelle Modul und seine Bibliotheksabhängigkeiten, in dem die Ergebnisse von Unittests und Instrumentierungstests zusammengeführt werden.	path_to_your_project/module_name/build/reports/testAllSuitesWithDependencies/test-report/

**Hinweis**: Wenn Sie die Abdeckungsunterstützung in einem Ihrer Module aktiviert haben, wird auch der einheitliche Codeabdeckungsbericht generiert.