Test dalla riga di comando

Questo documento descrive come eseguire i test direttamente dalla riga di comando. Questo documento presuppone che tu sappia già come creare un'app per Android e scrivere test per la tua app. Per ulteriori informazioni su come creare test per la tua app, consulta Testare le app su Android.

Quando crei la tua app utilizzando il sistema di compilazione Gradle, il plug-in Android per Gradle ti consente di eseguire i test dal tuo progetto Gradle utilizzando la riga di comando. Per un controllo più granulare, puoi scegliere di eseguire i test tramite una shell Android Debug Bridge (adb). Ciò può essere utile quando si eseguono test in un ambiente di integrazione continua.

Per scoprire come eseguire test strumentati automatizzati dalla riga di comando utilizzando dispositivi virtuali gestiti da Gradle, consulta Scalare i test con i dispositivi gestiti da Gradle.

Eseguire test con Gradle

Il plug-in Android per Gradle ti consente di eseguire test dal progetto Gradle utilizzando la riga di comando.

La tabella seguente riepiloga come eseguire i test con Gradle:

Tabella 1. Diversi modi per eseguire i test con Gradle

Tipo di test delle unità Comando da eseguire Posizione del risultato del test
Test locale delle unità Esegui l'attività test: 

./gradlew test
File dei risultati del test HTML:
path_to_your_project/module_name/build/reports/tests/ directory.

File XML dei risultati del test:
path_to_your_project/module_name/build/test-results/ directory.

Test delle unità strumentato Esegui l'attività connectedAndroidTest: 

./gradlew connectedAndroidTest
File dei risultati del test HTML:
path_to_your_project/module_name/build/reports/androidTests/connected/ directory.

File XML dei risultati del test:
path_to_your_project/module_name/build/outputs/androidTest-results/connected/ directory.

Gradle supporta le abbreviazioni dei nomi delle attività. Ad esempio, puoi avviare l'attività connectedAndroidTest inserendo questo comando:

./gradlew cAT

Puoi anche scegliere di eseguire le attività Gradle check e connectedCheck. Questi task eseguono rispettivamente i test locali o strumentati, ma includono altri controlli aggiunti da altri plug-in Gradle.

Eseguire test su un modulo

Le attività test e connectedAndroidTest eseguono test su ogni modulo del tuo progetto. Puoi eseguire test su un modulo specifico anteponendo il nome del modulo e i due punti (:) all'attività test o connectedAndroidTest. Ad esempio, il seguente comando esegue test strumentati solo per il modulo mylibrary:

./gradlew mylibrary:connectedAndroidTest

Eseguire test su una variante di compilazione

Le attività test e connectedAndroidTest eseguono test su ogni variante di compilazione nel tuo progetto. Puoi scegliere come target una variante di compilazione specifica utilizzando la seguente sintassi:

  • Per i test locali delle unità: 
    ./gradlew testVariantNameUnitTest
  • Per i test strumentati: 
    ./gradlew connectedVariantNameAndroidTest

Eseguire metodi o classi di test specifici

Quando esegui test delle unità locali, Gradle ti consente di scegliere come target test specifici utilizzando il flag --tests. Ad esempio, il seguente comando esegue solo i test sampleTestMethod per la variante di compilazione specificata. Per scoprire di più sull'utilizzo del flag --tests, leggi la documentazione di Gradle sul filtraggio dei test.


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

Eseguire test con adb

Quando esegui i test dalla riga di comando con Android Debug Bridge (adb), hai più opzioni per scegliere i test da eseguire rispetto a qualsiasi altro metodo. Puoi selezionare singoli metodi di test, filtrare i test in base a un'annotazione personalizzata o specificare le opzioni di test. Poiché l'esecuzione di prova è controllata interamente dalla riga di comando, puoi personalizzare i test con script shell in vari modi.

Per eseguire un test dalla riga di comando, esegui adb shell per avviare una shell della riga di comando sul dispositivo o sull'emulatore. All'interno di questa shell puoi interagire con Activity Manager utilizzando il comando am e il relativo comando secondario instrument per eseguire i test.

Come scorciatoia, puoi avviare una shell adb, chiamare am instrument e specificare i flag della riga di comando in un'unica riga di input. La shell si apre sul dispositivo o sull'emulatore, esegue i test, produce l'output e poi torna alla riga di comando sul computer.

Per eseguire un test con am instrument:

  1. Crea o ricrea l'applicazione principale e il pacchetto di test.
  2. Installa il pacchetto di test e i file APK del pacchetto Android dell'applicazione principale sul tuo dispositivo Android o emulatore attuale.

  3. Nella riga di comando, inserisci:

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

    dove <test_package_name> è il nome del pacchetto Android dell'applicazione di test e <runner_class> è il nome della classe di esecuzione dei test Android che stai utilizzando. Il nome del pacchetto Android è il valore dell'attributo package dell'elemento manifest nel file manifest del pacchetto di test (AndroidManifest.xml).

    La classe Android Test Runner è in genere AndroidJUnitRunner:

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

I risultati del test vengono visualizzati in STDOUT.

am instrument flags

Per trovare un elenco di tutti i flag da utilizzare con il comando am instrument, esegui adb shell am help. Alcuni flag importanti sono descritti nella tabella seguente:

Tabella 2. am instrument importanti flag

Segnala Valore Descrizione
-w (nessuno) Forza am instrument ad attendere il termine dell'instrumentation prima di terminare. In questo modo, la shell rimane aperta fino al termine dei test. Questo flag è necessario per visualizzare i risultati dei test.
-r (nessuno) Restituisce i risultati in formato non elaborato. Utilizza questo flag quando vuoi raccogliere misurazioni del rendimento in modo che non vengano formattate come risultati del test. Questo flag è progettato per essere utilizzato con il flag -e perf true (documentato nella sezione Opzioni dello strumento am).
-e <test_options> Fornisce opzioni di test come coppie chiave-valore. Lo strumento am instrument li passa alla classe di strumentazione specificata utilizzando il metodo onCreate(). Puoi specificare più occorrenze di -e <test_options>. Le chiavi e i valori sono descritti nella sezione Opzioni dello strumento am. Puoi utilizzare queste coppie chiave-valore solo con AndroidJUnitRunner o con InstrumentationTestRunner e le relative sottoclassi. L'utilizzo con qualsiasi altra classe non ha effetto.
--no-hidden-api-checks (nessuno) Disattiva le limitazioni all'utilizzo delle API nascoste. Per saperne di più su cosa sono le API nascoste e su come possono influire sulla tua app, leggi Limitazioni relative alle interfacce non SDK.

am instrument options

Lo strumento am instrument passa le opzioni di test a AndroidJUnitRunner o InstrumentationTestRunner sotto forma di coppie chiave-valore, utilizzando il flag -e, con questa sintassi:

-e <key> <value>

Alcune chiavi accettano più valori. Specifica più valori in un elenco separato da virgole. Ad esempio, questa chiamata di AndroidJUnitRunner fornisce più valori per la chiave package:

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

La seguente tabella elenca le coppie chiave-valore che puoi utilizzare con il test runner:

Tabella 3. -e flag key-value pairs to use with your test runner

Chiave Valore Descrizione
package <Java_package_name> Il nome del pacchetto Java completo per uno dei pacchetti nell'applicazione di test. Viene eseguita qualsiasi classe di scenario di test che utilizza questo nome del pacchetto. Tieni presente che non si tratta di un nome di pacchetto Android; un pacchetto di test ha un solo nome di pacchetto Android, ma può contenere diversi pacchetti Java.
class <class_name> Il nome di classe Java completo per una delle classi di test case. Viene eseguita solo questa classe di scenario di test.
<class_name>#method name Un nome di classe dello scenario di test completo e uno dei suoi metodi. Viene eseguito solo questo metodo. Prendi nota del simbolo di cancelletto (#) tra il nome della classe e il nome del metodo.
func true Esegue tutte le classi di test che estendono InstrumentationTestCase.
unit true Esegue tutte le classi di test che non estendono InstrumentationTestCase o PerformanceTestCase.
size [small | medium | large] Esegue un metodo di test annotato in base alle dimensioni. Le annotazioni sono @SmallTest, @MediumTest e @LargeTest.
perf true Esegue tutte le classi di test che implementano PerformanceTestCase. Quando utilizzi questa opzione, specifica il flag -r per am instrument in modo che l'output venga mantenuto in formato non elaborato e non riformattato come risultati del test.
debug true Esegue i test in modalità di debug.
log true Carica e registra tutti i test specificati, ma non li esegue. Le informazioni sul test vengono visualizzate in STDOUT. Utilizzalo per verificare combinazioni di altri filtri e specifiche di test.
emma true Esegue un'analisi della copertura del codice EMMA e scrive l'output in /data/<app_package>/coverage.ec sul dispositivo. Per ignorare la posizione del file, utilizza la chiave coverageFile descritta nella voce seguente.

Nota:questa opzione richiede una build strumentata con EMMA dell'applicazione di test, che puoi generare con il target coverage.

coverageFile <filename> Esegue l'override della posizione predefinita del file di copertura EMMA sul dispositivo. Specifica questo valore come percorso e nome file in formato UNIX. Il nome file predefinito è descritto nella voce relativa alla chiave emma.

Quando utilizzi il flag -e, tieni presente quanto segue:

  • am instrument richiama onCreate(Bundle) con un Bundle contenente le coppie chiave-valore.
  • La chiave package ha la precedenza sulla chiave class. Se specifichi un pacchetto e poi separi una classe all'interno di quel pacchetto, Android esegue tutti i test nel pacchetto e ignora la chiave della classe.
  • Le chiavi func e unit si escludono a vicenda.

Esempi di utilizzo

Le sezioni seguenti forniscono esempi di utilizzo di am instrument per eseguire test. Si basano sulla seguente struttura:

  • Il pacchetto di test ha il nome pacchetto Android com.android.demo.app.tests.
  • Due classi di test strumentati:
    • TestClass1, che contiene il metodo di test testMethod1.
    • TestClass2, che contiene i metodi di test testMethod2 e testMethod3.
  • L'esecutore test è AndroidJUnitRunner.

Eseguire l'intero pacchetto di test

Per eseguire tutte le classi di test nel pacchetto di test, inserisci:

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

Esegui tutti i test in una classe di scenari di test

Per eseguire tutti i test nella classe TestClass1, inserisci:

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

Seleziona un sottoinsieme di test

Per eseguire tutti i test nella classe TestClass1 e il metodo testMethod3 in TestClass2, inserisci:

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

Puoi trovare altri casi d'uso nel AndroidJUnitRunner riferimento dell'API.

Visualizzare i report di test unificati

Il plug-in Android per Gradle fornisce attività di report di test unificate, che generano dashboard HTML che uniscono i risultati dei test delle unità e di instrumentazione.

Prerequisiti

  • Plug-in Android per Gradle 9.2.0-alpha07 o versioni successive.

Per generare report di test unificati, esegui una delle seguenti attività:

Ambito del report Comando Descrizione Posizione report
Modulo attuale ./gradlew :module_name:createTestReport Genera un report di test unificato per il modulo corrente, unendo i risultati dei test delle unità e strumentati. path_to_your_project/module_name/build/reports/tests/test-report/
Modulo corrente e dipendenze ./gradlew :module_name:createAggregatedTestReport Genera un report di test unificato per il modulo dell'app corrente e le relative dipendenze della libreria. path_to_your_project/module_name/build/reports/tests/aggregated-test-report/