Testowanie z poziomu wiersza poleceń

Z tego dokumentu dowiesz się, jak uruchamiać testy bezpośrednio z wiersza poleceń. Zakładamy, że wiesz już, jak utworzyć aplikację na Androida i napisać testy dla tej aplikacji. Więcej informacji o tworzeniu testów aplikacji znajdziesz w artykule Testowanie aplikacji na Androida.

Narzędzia wiersza poleceń i zadania Gradle opisane na tej stronie są niezależne od zestawu narzędzi interfejsu. Jeśli chcesz napisać testy interfejsu dla Compose, przeczytaj artykuł Testowanie układu Compose. Po napisaniu testów postępuj zgodnie z tym przewodnikiem, aby uruchomić je w terminalu lub zdalnym środowisku trybu ciągłej integracji.

Gdy tworzysz aplikację za pomocą systemu kompilacji Gradle, wtyczka Androida do obsługi Gradle umożliwia uruchamianie testów z projektu Gradle za pomocą wiersza poleceń. Aby uzyskać większą kontrolę, możesz uruchamiać testy za pomocą powłoki Android Debug Bridge (adb). Może to być przydatne podczas uruchamiania testów w trybie ciągłej integracji.

Aby dowiedzieć się, jak uruchamiać zautomatyzowane testy z instrumentacją z wiersza poleceń za pomocą urządzeń wirtualnych zarządzanych przez Gradle, przeczytaj artykuł Skalowanie testów za pomocą urządzeń zarządzanych przez Gradle.

Uruchamianie testów za pomocą Gradle

Wtyczka Androida do obsługi Gradle umożliwia uruchamianie testów z projektu Gradle za pomocą wiersza poleceń.

W tabeli poniżej znajdziesz podsumowanie sposobów uruchamiania testów za pomocą Gradle:

Tabela 1. Różne sposoby uruchamiania testów za pomocą Gradle

Typ testu jednostkowego Polecenie do uruchomienia Lokalizacja wyników testu
Lokalny test jednostkowy Uruchom zadanie test: 

./gradlew test
Pliki wyników testu w formacie HTML:
path_to_your_project/module_name/build/reports/tests/ katalog.

Pliki wyników testu w formacie XML:
path_to_your_project/module_name/build/test-results/ katalog.

Instrumentowany test jednostkowy Uruchom zadanie connectedAndroidTest: 

./gradlew connectedAndroidTest
Pliki wyników testu w formacie HTML:
path_to_your_project/module_name/build/reports/androidTests/connected/ katalog.

Pliki wyników testu w formacie XML:
path_to_your_project/module_name/build/outputs/androidTest-results/connected/ katalog.

Gradle obsługuje skróty nazw zadań. Na przykład możesz uruchomić zadanie connectedAndroidTest, wpisując to polecenie:

./gradlew cAT

Możesz też uruchomić zadania Gradle check i connectedCheck. Te zadania uruchamiają odpowiednio testy lokalne lub testy z instrumentacją, ale obejmują też inne kontrole dodane przez inne wtyczki Gradle.

Uruchamianie testów w module

Zadania test i connectedAndroidTest uruchamiają testy w każdym module projektu. Aby uruchomić testy w konkretnym module, dodaj przed zadaniem test lub connectedAndroidTest nazwę modułu i dwukropek (:). Na przykład to polecenie uruchamia testy z instrumentacją tylko w module mylibrary:

./gradlew mylibrary:connectedAndroidTest

Uruchamianie testów w wariancie kompilacji

Zadania test i connectedAndroidTest uruchamiają testy w każdym wariancie kompilacji w projekcie. Aby wybrać konkretny wariant kompilacji, użyj tej składni:

  • W przypadku lokalnych testów jednostkowych: 
    ./gradlew testVariantNameUnitTest
  • W przypadku testów z instrumentacją: 
    ./gradlew connectedVariantNameAndroidTest

Uruchamianie konkretnych metod lub klas testowych

Podczas uruchamiania lokalnych testów jednostkowych Gradle umożliwia wybieranie konkretnych testów za pomocą flagi --tests. Na przykład to polecenie uruchamia tylko testy sampleTestMethod dla określonego wariantu kompilacji. Więcej informacji o używaniu flagi --tests znajdziesz w dokumentacji Gradle na temat filtrowania testów.


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

Uruchamianie testów za pomocą adb

Gdy uruchamiasz testy z wiersza poleceń za pomocą Android Debug Bridge (adb), masz więcej opcji wyboru testów do uruchomienia niż w przypadku innych metod. Możesz wybrać poszczególne metody testowe, filtrować testy według niestandardowej adnotacji lub określić opcje testowania. Ponieważ przebieg testu jest w całości kontrolowany z wiersza poleceń, możesz dostosować testowanie na różne sposoby za pomocą skryptów powłoki.

Aby uruchomić test z wiersza poleceń, uruchom polecenie adb shell, aby otworzyć powłokę wiersza poleceń na urządzeniu lub emulatorze. W tej powłoce możesz wchodzić w interakcję z menedżerem aktywności za pomocą polecenia am i używać jego podpolecenia instrument do uruchamiania testów.

Możesz też uruchomić powłokę adb, wywołać polecenie am instrument i określić flagi wiersza poleceń w jednym wierszu. Powłoka otworzy się na urządzeniu lub emulatorze, uruchomi testy, wygeneruje dane wyjściowe, a następnie wróci do wiersza poleceń na komputerze.

Aby uruchomić test za pomocą polecenia am instrument:

  1. Skompiluj lub ponownie skompiluj główną aplikację i pakiet testowy.
  2. Zainstaluj pakiet testowy i główne pliki pakietu aplikacji na Androida (pliki APK) na bieżącym urządzeniu z Androidem lub emulatorze.

  3. W wierszu poleceń wpisz:

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

    gdzie <test_package_name> to nazwa pakietu Androida aplikacji testowej, a <runner_class> to nazwa używanej klasy narzędzia do uruchamiania testów na Androida. Nazwa pakietu na Androida to wartość atrybutu package elementu manifest w pliku manifestu pakietu testowego (AndroidManifest.xml).

    Klasa narzędzia do uruchamiania testów na Androida to zwykle AndroidJUnitRunner:

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

Wyniki testu pojawią się w STDOUT.

Flagi polecenia am instrument

Aby wyświetlić listę wszystkich flag, których można używać z poleceniem am instrument, uruchom polecenie adb shell am help. Niektóre ważne flagi są opisane w tabeli poniżej:

Tabela 2. Ważne flagi polecenia am instrument

Flaga Wartość Opis
-w (brak) Wymusza na poleceniu am instrument czekanie na zakończenie instrumentacji przed zakończeniem działania. Dzięki temu powłoka pozostaje otwarta do czasu zakończenia testów. Ta flaga jest wymagana, aby zobaczyć wyniki testów.
-r (brak) Wyświetla wyniki w formacie nieprzetworzonym. Użyj tej flagi, gdy chcesz zbierać pomiary wydajności, aby nie były one formatowane jako wyniki testów. Ta flaga jest przeznaczona do użycia z flagą -e perf true (opisaną w sekcji Opcje polecenia am instrument).
-e <test_options> Udostępnia opcje testowania jako pary klucz-wartość. Narzędzie am instrument przekazuje je do określonej klasy instrumentacji za pomocą metody onCreate(). Możesz określić wiele wystąpień -e <test_options>. Klucze i wartości są opisane w sekcji Opcje polecenia am instrument. Tych par klucz-wartość można używać tylko z AndroidJUnitRunner. Używanie ich z dowolną inną klasą nie ma żadnego efektu.
--no-hidden-api-checks (brak) Wyłącza ograniczenia dotyczące używania ukrytych interfejsów API. Więcej informacji o tym, czym są ukryte interfejsy API i jak mogą wpływać na aplikację, znajdziesz w artykule Ograniczenia dotyczące interfejsów spoza pakietu SDK.

Opcje polecenia am instrument

Narzędzie am instrument przekazuje opcje testowania do AndroidJUnitRunner lub InstrumentationTestRunner w postaci par klucz-wartość za pomocą flagi -e z tą składnią:

-e <key> <value>

Niektóre klucze akceptują wiele wartości. Wiele wartości określa się na liście rozdzielonej przecinkami. Na przykład to wywołanie AndroidJUnitRunner zawiera wiele wartości klucza package:

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

W tabeli poniżej znajdziesz pary klucz-wartość, których możesz używać z narzędziem do uruchamiania testów:

Tabela 3. Pary klucz-wartość flagi -e do użycia z narzędziem do uruchamiania testów

Klucz Wartość Opis
package <Java_package_name> Pełna nazwa pakietu Java jednego z pakietów w aplikacji testowej. Wykonywany jest każdy element testowania, który używa tej nazwy pakietu. Pamiętaj, że nie jest to nazwa pakietu Androida. Pakiet testowy ma jedną nazwę pakietu na Androida, ale może zawierać kilka pakietów Java.
class <class_name> Pełna nazwa klasy Java jednej z klas elementów testowania. Wykonywany jest tylko ten element testowania.
<class_name>#method name Pełna nazwa klasy elementu testowania i jedna z jej metod. Wykonywana jest tylko ta metoda. Zwróć uwagę na znak hash (#) między nazwą klasy a nazwą metody.
size [small | medium | large] Uruchamia metodę testową oznaczoną rozmiarem. Adnotacje to @SmallTest, @MediumTest i @LargeTest.
debug true Uruchamia testy w trybie debugowania.
log true Wczytuje i rejestruje wszystkie określone testy, ale ich nie uruchamia. Informacje o teście pojawiają się w STDOUT. Użyj tej opcji, aby sprawdzić kombinacje innych filtrów i specyfikacji testów.
emma true Uruchamia analizę pokrycia kodu EMMA i zapisuje dane wyjściowe w pliku /data/<app_package>/coverage.ec na urządzeniu. Aby zastąpić lokalizację pliku, użyj klucza coverageFile opisanego w następnym wpisie.

Uwaga: ta opcja wymaga kompilacji aplikacji testowej z instrumentacją EMMA, którą można wygenerować za pomocą celu coverage.

coverageFile <filename> Zastępuje domyślną lokalizację pliku pokrycia EMMA na urządzeniu. Określ tę wartość jako ścieżkę i nazwę pliku w formacie UNIX. Domyślna nazwa pliku jest opisana we wpisie dotyczącym klucza emma.

Podczas używania flagi -e pamiętaj o tych kwestiach:

  • am instrument wywołuje onCreate(Bundle) z Bundle zawierającym pary klucz-wartość.
  • Klucz package ma pierwszeństwo przed kluczem class. Jeśli określisz pakiet, a potem osobno określisz klasę w tym pakiecie, Android uruchomi wszystkie testy w pakiecie i zignoruje klucz klasy.
  • Klucze func i unit wykluczają się nawzajem.

Przykłady użycia

W sekcjach poniżej znajdziesz przykłady użycia polecenia am instrument do uruchamiania testów. Opierają się one na tej strukturze:

  • Pakiet testowy ma nazwę pakietu na Androida com.android.demo.app.tests.
  • Dwie klasy testów z instrumentacją:
    • TestClass1, która zawiera metodę testową testMethod1.
    • TestClass2, która zawiera metody testowe testMethod2 i testMethod3.
  • Narzędzie do uruchamiania testów to AndroidJUnitRunner.

Uruchamianie całego pakietu testowego

Aby uruchomić wszystkie klasy testowe w pakiecie testowym, wpisz:

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

Uruchamianie wszystkich elementów testowania w klasie testowej

Aby uruchomić wszystkie testy w klasie TestClass1, wpisz:

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

Wybieranie podzbioru testów

Aby uruchomić wszystkie testy w klasie TestClass1 i metodę testMethod3 w klasie TestClass2, wpisz:

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

Więcej przypadków użycia znajdziesz w AndroidJUnitRunner dokumentacji API.

Wyświetlanie ujednoliconych raportów z testów

Wtyczka Androida do obsługi Gradle udostępnia ujednolicone zadania testowe, które generują pulpity nawigacyjne HTML łączące wyniki testów jednostkowych i instrumentowanych.

Wymagania wstępne

  • Wtyczka Androida do obsługi Gradle w wersji 9.5.0-alpha05 lub nowszej.

Aby przetestować wszystkie zestawy testów, uruchom jedno z tych zadań:

Zakres raportu Polecenie Opis Lokalizacja raportu
Bieżący moduł ./gradlew :module_name:testAllSuites --continue Generuje ujednolicony raport z testów dla bieżącego modułu, łącząc wyniki testów jednostkowych i testów z instrumentacją. path_to_your_project/module_name/build/reports/testAllSuites/test-report/
Bieżący moduł i zależności ./gradlew :module_name:testAllSuitesWithDependencies --continue Generuje ujednolicony raport z testów dla bieżącego modułu i jego zależności bibliotecznych, łącząc wyniki testów jednostkowych i testów z instrumentacją. path_to_your_project/module_name/build/reports/testAllSuitesWithDependencies/test-report/