Esegui test (Atest)

Atest è uno strumento a riga di comando che consente agli utenti di creare, installare ed eseguire test Android in locale, accelerando notevolmente le ripetizioni dei test senza richiedere la conoscenza delle opzioni della riga di comando del framework di test Trade Federation. Questa pagina spiega come utilizzare Atest per eseguire test Android.

Per informazioni generali sulla scrittura di test per Android, vedi Test della piattaforma Android.

Per informazioni sulla struttura generale di Atest, consulta la Guida per gli sviluppatori di Atest.

Per informazioni sull'esecuzione dei test nei file TEST_MAPPING tramite Atest, vedi Eseguire i test nei file TEST_MAPPING.

Per aggiungere una funzionalità ad Atest, segui il flusso di lavoro per gli sviluppatori di Atest.

Configura l'ambiente

Per configurare l'ambiente Atest, segui le istruzioni riportate in Configurare l' ambiente, Scegliere un target e Creare il codice.

Utilizzo di base

I comandi Atest hanno il seguente formato:

atest test-to-run [optional-arguments]

Argomenti facoltativi

La tabella seguente elenca gli argomenti di uso comune. Un elenco completo è disponibile tramite atest --help.

Opzione Opzione lunga Descrizione
-b --build Crea i target di test. (valore predefinito)
-i --install Installa gli artefatti di test (APK) sul dispositivo. (valore predefinito)
-t --test Esegue i test. (valore predefinito)
-s --serial Esegue i test sul dispositivo specificato. È possibile testare un dispositivo alla volta.
-d --disable-teardown Disattiva la rimozione e la pulizia dei test.
--dry-run Esegue Atest in modalità dry run senza creare, installare o eseguire effettivamente i test.
-m --rebuild-module-info Forza la ricreazione del file module-info.json.
-w --wait-for-debugger Attende il completamento del debugger prima dell'esecuzione.
-v --verbose Visualizza la registrazione a livello DEBUG.
--iterations Esegue i test in loop fino al raggiungimento dell'iterazione massima. (10 per impostazione predefinita)
--rerun-until-failure [COUNT=10] Esegue di nuovo tutti i test finché non si verifica un errore o non viene raggiunta l'iterazione massima. (10 per impostazione predefinita)
--retry-any-failure [COUNT=10] Esegue di nuovo i test non riusciti finché non vengono superati o non viene raggiunta l'iterazione massima. (10 per impostazione predefinita)
--start-avd Crea automaticamente un AVD ed esegue i test sul dispositivo virtuale.
--acloud-create Crea un AVD utilizzando il comando acloud.
--[CUSTOM_ARGS] Specifica gli argomenti personalizzati per i runner di test.
-a --all-abi Esegue i test per tutte le architetture di dispositivi disponibili.
--host Esegue il test completamente sull'host senza un dispositivo.
Nota: l'esecuzione di un test host che richiede un dispositivo con --host non andrà a buon fine.
--history Mostra i risultati dei test in ordine cronologico.
--latest-result Stampa l'ultimo risultato del test.

Per ulteriori informazioni su -b, -i e -t, vedi la sezione Specificare i passaggi: creazione, installazione o esecuzione.

Specifica i test

Per eseguire i test, specifica uno o più test utilizzando uno dei seguenti identificatori:

  • Nome modulo
  • Modulo:Classe
  • Nome corso
  • Test di integrazione Tradefed
  • Percorso file
  • Nome pacchetto

Separa i riferimenti a più test con spazi, come indicato di seguito:

atest test-identifier-1 test-identifier-2

Nome modulo

Per eseguire un intero modulo di test, utilizza il nome del modulo. Inserisci il nome così come appare nelle variabili LOCAL_MODULE o LOCAL_PACKAGE_NAME nel file Android.mk o Android.bp del test.

Esempi:

atest FrameworksServicesTests
atest CtsVideoTestCases

Modulo:Classe

Per eseguire una singola classe all'interno di un modulo, utilizza Modulo:Classe. Modulo è lo stesso descritto in Nome modulo. Classe è il nome della classe di test nel file .java e può essere il nome della classe completo o il nome di base.

Esempi:

atest CtsVideoTestCases:VideoEncoderDecoderTest
atest FrameworksServicesTests:ScreenDecorWindowTests
atest FrameworksServicesTests:com.android.server.wm.ScreenDecorWindowTests

Nome corso

Per eseguire una singola classe senza specificare esplicitamente un nome modulo, utilizza il nome della classe.

Esempi:

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

Test di integrazione Tradefed

Per eseguire i test integrati direttamente in TradeFed (non modulari), inserisci il nome così come appare nell'output del comando tradefed.sh list configs. Ad esempio:

Per eseguire il reboot.xml test:

atest example/reboot

Per eseguire il test native-benchmark.xml test:

atest native-benchmark

Percorso file

Atest supporta l'esecuzione di test basati su moduli e test basati sull'integrazione inserendo il percorso del file o della directory di test, a seconda dei casi. Supporta anche l'esecuzione di una singola classe specificando il percorso del file Java della classe. Sono supportati sia i percorsi relativi sia quelli assoluti.

Esegui un modulo

Gli esempi seguenti mostrano due modi per eseguire il modulo CtsVideoTestCases utilizzando un percorso file.

Esegui da repo-root di Android:

atest cts/tests/video

Esegui da repo-root/cts/tests/video di Android:

    atest .

Esegui una classe di test

L'esempio seguente mostra come eseguire una classe specifica all'interno del modulo CtsVideoTestCases utilizzando un percorso file.

Da repo-root di Android:

    atest cts/tests/video/src/android/video/cts/VideoEncoderDecoderTest.java

Esegui un test di integrazione

L'esempio seguente mostra come eseguire un test di integrazione utilizzando un percorso file da repo-root di Android:

    atest tools/tradefederation/contrib/res/config/example/reboot.xml

Nome pacchetto

Atest supporta la ricerca di test per nome pacchetto.

Esempi:

    atest com.android.server.wm
    atest com.android.uibench.janktests

Specifica i passaggi: creazione, installazione o esecuzione

Utilizza le opzioni -b, -i e -t per specificare i passaggi da eseguire. Se non specifichi un'opzione, vengono eseguiti tutti i passaggi.

  • Crea solo i target: atest -b test-to-run
  • Esegui solo i test: atest -t test-to-run
  • Installa l'APK ed esegui i test: atest -it test-to-run
  • Crea ed esegui, ma non installare: atest -bt test-to-run

Atest può forzare un test a saltare il passaggio di pulizia o rimozione. Molti test, come CTS, liberano spazio sul dispositivo dopo l'esecuzione del test, quindi se provi a eseguire di nuovo il test con -t l'operazione non andrà a buon fine senza il parametro --disable-teardown. Utilizza -d prima di -t per saltare il passaggio di liberare spazio del test ed eseguire i test in modo iterativo.

atest -d test-to-run
atest -t test-to-run

Esegui metodi specifici

Atest supporta l'esecuzione di metodi specifici all'interno di una classe di test. Sebbene sia necessario creare l'intero modulo, questo riduce il tempo necessario per eseguire i test. Per eseguire metodi specifici, identifica la classe utilizzando uno dei modi supportati per identificare una classe (Modulo:Classe, percorso file e così via) e aggiungi il nome del metodo:

atest reference-to-class#method1

Quando specifichi più metodi, separali con virgole:

atest reference-to-class#method1,method2,method3

Esempi:

atest com.android.server.wm.ScreenDecorWindowTests#testMultipleDecors
atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval

I due esempi seguenti mostrano i modi preferiti per eseguire un singolo metodo, testFlagChange. Questi esempi sono preferibili rispetto all'utilizzo del solo nome della classe perché la specifica del modulo o della posizione del file Java consente ad Atest di trovare il test molto più rapidamente.

Utilizzando Modulo:Classe:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange

Da Android repo-root:

atest frameworks/base/services/tests/wmtests/src/com/android/server/wm/ScreenDecorWindowTests.java#testFlagChange

È possibile eseguire più metodi da classi e moduli diversi:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval ScreenDecorWindowTests#testMultipleDecors

Esegui più classi

Per eseguire più classi, separale con spazi nello stesso modo in cui esegui più test. Atest crea ed esegue le classi in modo efficiente, quindi la specifica di un sottoinsieme di classi in un modulo migliora le prestazioni rispetto all'esecuzione dell'intero modulo.

Per eseguire due classi nello stesso modulo:

atest FrameworksServicesTests:ScreenDecorWindowTests FrameworksServicesTests:DimmerTests

Per eseguire due classi in moduli diversi:

atest FrameworksServicesTests:ScreenDecorWindowTests CtsVideoTestCases:VideoEncoderDecoderTest

Esegui i file binari GTest

Atest può eseguire file binari GTest. Utilizza -a per eseguire questi test per tutte le architetture di dispositivi disponibili, che in questo esempio sono armeabi-v7a (ARM a 32 bit) e arm64-v8a (ARM a 64 bit).

Test di input di esempio:

atest -a libinput_tests inputflinger_tests

Per selezionare un file binario GTest specifico da eseguire, utilizza i due punti (:) per specificare il nome del test e il cancelletto (#) per specificare ulteriormente un singolo metodo.

Ad esempio, per la seguente definizione di test: 

TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)

Esegui quanto segue per specificare l'intero test: 

atest inputflinger_tests:InputDispatcherTest

In alternativa, esegui un singolo test utilizzando quanto segue: 

atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents

Esegui i test in TEST_MAPPING

Atest può eseguire i test nei file TEST_MAPPING.

Esegui i test di pre-invio in modo implicito

Esegui i test di pre-invio nei file TEST_MAPPING nelle directory corrente e principale:

atest

Esegui i test di pre-invio nei file TEST_MAPPING in /path/to/project e nelle relative directory principali:

atest --test-mapping /path/to/project

Esegui un gruppo di test specificato

I gruppi di test disponibili sono: presubmit(valore predefinito), postsubmit, mainline-presubmit e all.

Esegui i test di post-invio nei file TEST_MAPPING nelle directory corrente e principale:

atest :postsubmit

Esegui i test di tutti i gruppi nei file TEST_MAPPING:

atest :all

Esegui i test di post-invio nei file TEST_MAPPING in /path/to/project e nelle relative directory principali:

atest --test-mapping /path/to/project:postsubmit

Esegui i test mainline nei file TEST_MAPPING in /path/to/project e nelle relative directory principali:

atest --test-mapping /path/to/project:mainline-presubmit

Esegui i test nelle sottodirectory

Per impostazione predefinita, Atest cerca i test solo nei file TEST_MAPPING verso l'alto (dalla directory corrente o dalla directory specificata alle relative directory principali). Se vuoi eseguire anche i test nei file TEST_MAPPING nelle sottodirectory, utilizza --include-subdirs per forzare Atest a includere anche questi test:

atest --include-subdirs /path/to/project

Esegui i test in iterazione

Esegui i test in iterazione passando l'argomento --iterations. Indipendentemente dal fatto che il test venga superato o meno, Atest lo ripeterà fino al raggiungimento dell'iterazione massima.

Esempi:

Per impostazione predefinita, Atest esegue 10 iterazioni. Il numero di iterazioni deve essere un intero positivo.

atest test-to-run --iterations
atest test-to-run --iterations 5

I seguenti approcci semplificano il rilevamento dei test instabili:

Approccio 1: esegui tutti i test finché non si verifica un errore o non viene raggiunta l'iterazione massima.

  • Arresta l'esecuzione quando si verifica un errore o l'iterazione raggiunge il decimo round (per impostazione predefinita). 
    atest test-to-run --rerun-until-failure
  • Arresta l'esecuzione quando si verifica un errore o l'iterazione raggiunge il 100° round. 
    atest test-to-run --rerun-until-failure 100

Approccio 2: esegui solo i test non riusciti finché non vengono superati o non viene raggiunta l'iterazione massima.

  • Supponi che test-to-run abbia più scenari di test e che uno dei test non vada a buon fine. Esegui solo il test non riuscito 10 volte (per impostazione predefinita) o finché il test non viene superato. 
    atest test-to-run --retry-any-failure
  • Interrompi l'esecuzione del test non riuscito quando viene superato o raggiunge il 100° round. 
    atest test-to-run --retry-any-failure 100

Esegui i test sugli AVD

Atest è in grado di eseguire i test su un AVD appena creato. Esegui acloud create per creare un AVD e creare artefatti, poi utilizza gli esempi seguenti per eseguire i test.

Avvia un AVD ed esegui i test:

acloud create --local-instance --local-image && atest test-to-run

Avvia un AVD nell'ambito di un'esecuzione di test:

atest test-to-run --acloud-create "--local-instance --local-image"

Per ulteriori informazioni, esegui acloud create --help.

Passa le opzioni al modulo

Atest è in grado di passare le opzioni ai moduli di test. Per aggiungere le opzioni della riga di comando di TradeFed all'esecuzione del test, utilizza la seguente struttura e assicurati che gli argomenti personalizzati seguano il formato delle opzioni della riga di comando di Tradefed.

atest test-to-run -- [CUSTOM_ARGS]

Passa le opzioni del modulo di test ai preparatori di target o ai runner di test definiti nel file di configurazione del test:

atest test-to-run -- --module-arg module-name:option-name:option-value
atest GtsPermissionTestCases -- --module-arg GtsPermissionTestCases:ignore-business-logic-failure:true

Passa le opzioni a un tipo o a una classe di runner:

atest test-to-run -- --test-arg test-class:option-name:option-value
atest CtsVideoTestCases -- --test-arg com.android.tradefed.testtype.JarHosttest:collect-tests-only:true

Per ulteriori informazioni sulle opzioni solo per i test, vedi Passare le opzioni ai moduli.