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.

Wenn Sie Ihre App mit dem Gradle-Build-System 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 auch über eine Android Debug Bridge (adb) Shell ausführen. Das kann nützlich sein, wenn Sie Tests in einer Umgebung für die kontinuierliche Integration ausführen.

Informationen zum Ausführen automatisierter instrumentierter Tests ü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 Einheitentests Befehl zum Ausführen Speicherort der Testergebnisse
Lokaler Einheitentest 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 die Aufgabe connectedAndroidTest beispielsweise mit dem folgenden Befehl starten:

./gradlew cAT

Sie können auch die Gradle-Aufgaben check und connectedCheck ausführen. Mit diesen Aufgaben werden Ihre lokalen bzw. instrumentierten Tests ausgeführt. Sie umfassen 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 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. Sie können eine bestimmte Build-Variante mit der folgenden Syntax auswählen:

  • 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 auswählen. Mit dem folgenden Befehl werden beispielsweise nur die Tests sampleTestMethod 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'

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 bei 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.

Wenn Sie einen Test über die Befehlszeile ausführen möchten, starten Sie mit adb shell eine Befehlszeilen-Shell auf Ihrem Gerät oder Emulator. In dieser Shell können Sie mit dem Aktivitätsmanager mit dem Befehl am interagieren und mit dem Unterbefehl instrument 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 Sie Ihr Hauptanwendungs- und Testpaket oder erstellen Sie es neu.
  2. Installieren Sie die Android-Paketdateien (APK-Dateien) Ihres Testpakets und Ihrer Hauptanwendung 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-Testausführungsklasse, die Sie verwenden. Der Android-Paketname ist der Wert des Paketattributs des Manifestelements in der Manifestdatei (AndroidManifest.xml) Ihres Testpakets.

    Die Android-Testausführungsklasse 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 mit 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 oder mit InstrumentationTestRunner und seinen Unterklassen 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 das 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 Ihrer Testausführung verwenden können:

Tabelle 3 Schlüssel/Wert-Paare für das Flag „-e“ für die Verwendung mit Ihrer Testausführung

Schlüssel Wert Beschreibung
package <Java_package_name> Der voll qualifizierte Java-Paketname für eines der Pakete in der Testanwendung. Alle Testfallklassen, die diesen Paketnamen verwenden, werden ausgeführt. Beachten Sie, dass dies kein Android-Paketname ist. Ein Testpaket hat einen einzelnen 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 Testfallklassenname und eine seiner Methoden. Nur diese Methode wird ausgeführt. Beachten Sie das Hash-Zeichen (#) zwischen dem Klassen namen und dem Methodennamen.
func true Führt alle Testklassen aus, die InstrumentationTestCase erweitern.
unit true Führt alle Testklassen aus, die nicht erweitern, weder InstrumentationTestCase noch PerformanceTestCase.
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 -r Flag für am instrument an, damit die Ausgabe im Rohformat bleibt und nicht als Testergebnisse neu formatiert wird.
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 prü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 standardmäßigen Standort 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 angeben 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.

Beispiele für die Verwendung

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.
  • Die Testausführung 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 Testfallklasse 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 Aufgaben für einheitliche Testberichte, mit denen HTML-Dashboards generiert werden, in denen die Ergebnisse von Einheitentests und instrumentierten Tests zusammengeführt werden.

Voraussetzungen

  • Android-Gradle-Plug-in 9.2.0-alpha07 oder höher.

Führen Sie eine der folgenden Aufgaben aus, um einheitliche Testberichte zu generieren:

Berichtsumfang Befehl Beschreibung Speicherort des Berichts
Aktuelles Modul ./gradlew :module_name:createTestReport Generiert einen einheitlichen Testbericht für das aktuelle Modul, in dem die Ergebnisse von Einheitentests und instrumentierten Tests zusammengeführt werden. path_to_your_project/module_name/build/reports/tests/test-report/
Aktuelles Modul und Abhängigkeiten ./gradlew :module_name:createAggregatedTestReport Generiert einen einheitlichen Testbericht für das aktuelle App-Modul und seine Bibliotheksabhängigkeiten. path_to_your_project/module_name/build/reports/tests/aggregated-test-report/