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. 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. Wenn Sie die Tests genauer steuern möchten, können Sie sie über eine Android Debug Bridge (adb)-Shell ausführen. Das kann hilfreich sein, wenn Sie Tests in einer Continuous Integration-Umgebung 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

Unittesttyp Auszuführender Befehl Speicherort für 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-Testresultatdateien:
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-Testresultatdateien:
path_to_your_project/module_name/build/outputs/androidTest-results/connected/ Verzeichnis.

Gradle unterstützt Abkürzungen für Task-Namen. Sie können beispielsweise den connectedAndroidTest-Vorgang starten, indem Sie den folgenden Befehl eingeben:

./gradlew cAT

Sie können auch die Gradle-Aufgaben check und connectedCheck ausführen. Diese Tasks führen Ihre lokalen oder instrumentierten Tests aus, enthalten 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. Mit der folgenden Syntax können Sie eine bestimmte Build-Variante als Ziel festlegen:

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

Bestimmte Testmethoden oder -klassen ausführen

Wenn Sie lokale Unittests ausführen, können Sie mit dem Flag --tests bestimmte Tests in Gradle als Ziel festlegen. 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 zur Testfilterung.


./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 Optionen zur Auswahl der auszuführenden Tests als bei jeder anderen Methode. Sie können einzelne Testmethoden auswählen, Tests nach einer benutzerdefinierten Anmerkung filtern oder Testoptionen angeben. Da der Testlauf 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 Befehl am mit dem Aktivitätsmanager interagieren und mit dem Unterbefehl instrument Ihre Tests ausführen.

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

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

  1. Erstellen Sie Ihre Hauptanwendung und Ihr Testpaket neu.
  2. Installieren Sie die Android-Paketdateien (APK-Dateien) für Ihr Testpaket und Ihre 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 Testanwendung 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 Ihres Testpakets (AndroidManifest.xml).

    Die Android-Test-Ausführer-Klasse ist in der Regel AndroidJUnitRunner:

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

Ihre Testergebnisse werden in STDOUT angezeigt.

Instrument-Flags

Wenn Sie eine Liste aller Flags aufrufen möchten, die Sie mit dem Befehl am instrument verwenden können, führen Sie adb shell am help aus. Einige wichtige Flags werden in der folgenden Tabelle beschrieben:

Tabelle 2 Wichtige am instrument-Flags

Melden Wert Beschreibung
-w (keine) Erzwingt, dass am instrument wartet, bis die Instrumentierung beendet wird, bevor es selbst beendet wird. Dadurch bleibt die Shell geöffnet, bis die Tests abgeschlossen sind. Diese Kennzeichnung 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, die nicht als Testergebnisse formatiert werden. Dieses Flag ist für die Verwendung mit dem Flag -e perf true (dokumentiert im Abschnitt Instrumentoptionen) vorgesehen.
-e <test_options> Stellt Testoptionen als Schlüssel/Wert-Paare bereit. Das Tool am instrument übergibt diese mithilfe der Methode onCreate() an die angegebene Instrumentierungsklasse. Sie können mehrere Vorkommen von -e <test_options> 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 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 dazu, was verborgene APIs sind und wie sich dies auf Ihre App auswirken kann, finden Sie unter Einschränkungen für Nicht-SDK-Schnittstellen.

Instrumentenoptionen

Das am instrument-Tool übergibt Testoptionen in Form von Schlüssel/Wert-Paaren an AndroidJUnitRunner oder InstrumentationTestRunner. Dazu wird das Flag -e mit folgender Syntax verwendet:

-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 Test-Runner verwenden können:

Tabelle 3 Schlüssel/Wert-Paare für das Flag „-e“, die mit Ihrem Testrunner verwendet werden sollen

Schlüssel Wert Beschreibung
package <Java_package_name> Der vollständig qualifizierte Java-Paketname für eines der Pakete in der Testanwendung. Alle Testlaufklassen, die diesen Paketnamen verwenden, werden ausgeführt. Beachten Sie, dass es sich hierbei nicht um einen Android-Paketnamen handelt. Ein Testpaket hat einen einzelnen Android-Paketnamen, kann aber mehrere Java-Pakete enthalten.
class <class_name> Der vollständig qualifizierte Java-Klassennamen für eine der Testlaufklassen. Nur diese Testfallklasse wird ausgeführt.
<class_name>#method name Ein vollständig qualifizierter Klassenname für Testläufe und eine seiner Methoden. Nur diese Methode wird ausgeführt. Beachten Sie das Nummernzeichen (#) 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 von InstrumentationTestCase oder PerformanceTestCase abgeleitet werden.
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 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 Testinformationen werden in STDOUT angezeigt. Damit können Sie Kombinationen anderer Filter und Testspezifikationen prüfen.
emma true Führt eine EMMA-Codeabdeckungsanalyse aus 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 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.

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, die die Testmethode testMethod1 enthält.
    • TestClass2, das die Testmethoden testMethod2 und testMethod3 enthält.
  • Der Test-Runner ist AndroidJUnitRunner.

Das gesamte 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

Wenn Sie alle Tests in der Klasse TestClass1 ausführen möchten, 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

Untermenge von Tests auswählen

Wenn Sie alle Tests in der Klasse TestClass1 und die Methode testMethod3 in TestClass2 ausführen möchten, geben Sie Folgendes ein:

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 für AndroidJUnitRunner.

Einheitliche Testberichte ansehen

Das Android-Gradle-Plugin bietet einheitliche Aufgaben für Testberichte, mit denen HTML-Dashboards generiert werden, in denen die Ergebnisse von Unittests 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 erstellen:

Berichtsumfang Befehl Beschreibung Ort melden
Aktuelles Modul ./gradlew :module_name:createTestReport Generiert einen einheitlichen Testbericht für das aktuelle Modul, in dem die Ergebnisse von Unittests 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/