Test dalla riga di comando

Questo documento descrive come eseguire 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 la pagina Testare le app su Android.

Quando crei la tua app utilizzando il sistema di build Gradle, il plug-in Android Gradle ti consente di eseguire 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). Questo può essere utile durante l'esecuzione di test in un ambiente di integrazione continua.

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

Esegui test con Gradle

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

La tabella seguente riassume come eseguire i test con Gradle:

Tabella 1. I diversi modi di eseguire i test con Gradle

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

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

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

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

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

File dei risultati del test XML:
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 il seguente comando:

./gradlew cAT

Puoi anche scegliere di eseguire le attività Gradle check e connectedCheck. Queste attività eseguono i tuoi test locali o instrumentati, rispettivamente, 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. Per eseguire test su un modulo specifico, anteponi all'attività test o connectedAndroidTest il nome del modulo e i due punti (:). Ad esempio, il seguente comando esegue test instrumentati solo per il modulo mylibrary:

./gradlew mylibrary:connectedAndroidTest

Eseguire test su una variante di build

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

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

Eseguire corsi o metodi 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 comando seguente esegue solo i test sampleTestMethod per la variante di build specificata. Per scoprire di più sull'utilizzo del flag --tests, leggi la documentazione di Gradle sull'applicazione di filtri ai test.


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

Esegui test con ADB

Quando esegui test dalla riga di comando con Android Debug Bridge (adb), hai a disposizione 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 opzioni di test. Poiché l'esecuzione del test è controllata interamente dalla riga di comando, puoi personalizzare il test con gli 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 tuo dispositivo o emulatore. All'interno della shell puoi interagire con Gestione attività utilizzando il comando am e usare il sottocomando instrument per eseguire i test.

Come scorciatoia, puoi avviare una shell adb, chiamare am instrument e specificare i flag della riga di comando su un'unica riga di input. La shell si apre sul dispositivo o sull'emulatore, esegue i test, produce un output e quindi 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 dei pacchetti Android principali (file APK) dell'applicazione principale nel tuo emulatore o dispositivo Android corrente.

  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 della tua applicazione di test e <runner_class> è il nome della classe Android Test runner che stai utilizzando. Il nome del pacchetto Android è il valore dell'attributo pacchetto dell'elemento manifest nel file manifest del tuo pacchetto di test (AndroidManifest.xml).

    La classe dell'esecutore del test Android è in genere AndroidJUnitRunner:

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

I risultati del test vengono mostrati in STDOUT.

bandiere degli strumenti am

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

Tabella 2. Flag am instrument importanti

Segnala Valore Descrizione
-w (nessuno) Forza am instrument ad attendere la chiusura della strumentazione prima di arrestarsi autonomamente. In questo modo la shell rimane aperta fino al termine dei test. Questo flag è necessario per vedere i risultati dei test.
-r (nessuno) Restituisce i risultati in formato non elaborato. Utilizza questo flag quando vuoi raccogliere misurazioni delle prestazioni in modo che non vengano formattate come risultati del test. Questo flag è progettato per essere utilizzato con il flag -e perf true (documentato nelle opzioni degli strumenti per l'assistenza clienti).
-e <test_options> Fornisce opzioni di test come coppie chiave-valore. Lo strumento am instrument le passa alla classe di strumentazione specificata utilizzando il suo metodo onCreate(). Puoi specificare più occorrenze di -e <test_options>. Le chiavi e i valori sono descritti nella sezione delle opzioni dello strumento AM. Puoi utilizzare queste coppie chiave-valore solo con AndroidJUnitRunner o con InstrumentationTestRunner e le relative sottoclassi. Usarli con altri corsi non ha alcun effetto.
--no-hidden-api-checks (nessuno) Disabilita le limitazioni sull'uso delle API nascoste. Per saperne di più su cosa sono le API nascoste e su come questo può influire sulla tua app, consulta Restrizioni sulle interfacce non SDK.

opzioni instrument am

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. Occorre specificare 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

Nella tabella seguente sono elencate le coppie chiave-valore che puoi utilizzare con il runner del test:

Tabella 3. le coppie chiave-valore con flag -e da usare con l'esecutore del test

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 dello scenario di test che utilizza questo nome pacchetto. Tieni presente che questo non è un nome di pacchetto Android; un pacchetto di test ha un singolo nome di pacchetto Android, ma potrebbe contenere diversi pacchetti Java.
class <class_name> Il nome completo della classe Java per una delle classi dello scenario di test. Viene eseguita solo questa classe dello scenario di test.
<class_name>#method name Un nome completo della classe dello scenario di test e uno dei relativi metodi. Viene eseguito solo questo metodo. Nota il marcatore hash (#) tra il nome della classe e quello 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 per dimensione. 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 del test vengono visualizzate in STDOUT. Utilizzalo per verificare le combinazioni di altri filtri e le specifiche dei test.
emma true Esegue un'analisi della copertura del codice EMMA e scrive l'output in /data/<app_package>/coverage.ec sul dispositivo. Per eseguire l'override della posizione del file, utilizza la chiave coverageFile descritta nella voce seguente.

Nota: questa opzione richiede una build dell'applicazione di test basata su EMMA, che puoi generare con la destinazione 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 chiama onCreate(Bundle) con una Bundle contenente le coppie chiave-valore.
  • La chiave package ha la precedenza sulla chiave class. Se specifichi un pacchetto e poi specifichi separatamente una classe all'interno del pacchetto, Android esegue tutti i test nel pacchetto e ignora la chiave della classe.
  • La chiave func e la chiave unit si escludono a vicenda.

Esempi di utilizzo

Le sezioni seguenti forniscono esempi di utilizzo di am instrument per l'esecuzione dei test. Questi si basano sulla seguente struttura:

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

Esegui 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

Eseguire tutti i test in una classe dello scenario 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 nel 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 riferimento dell'API AndroidJUnitRunner.