Visualizza i report sulla copertura del codice (con l'agente on-device)

Il plug-in Android per Gradle (AGP) può creare report sulla copertura del codice per i tuoi test di instrumentazione con un agente di copertura on-device. Per impostazione predefinita, AGP instrumenta le classi della tua app con JaCoCo quando crea l'app, il che significa che aggiunge codice che registra quali parti della tua app vengono eseguite dai test. Con l'agente di copertura on-device, AGP crea la tua app senza questo codice aggiuntivo e l'agente strumenta le classi della tua app sul dispositivo di test durante l'esecuzione dei test. Questa pagina descrive come attivare la copertura del codice on-device e generare report.

Rispetto alla copertura del codice in fase di build, la copertura del codice on-device offre i seguenti vantaggi:

• Build più veloci: AGP non esegue il passaggio di strumentazione JaCoCo sulle classi dell'app e sulle relative dipendenze, il che può ridurre i tempi di build del 10-20%.
• APK di debug più piccoli: AGP non aggiunge il codice di monitoraggio della copertura alle classi della tua app, il che può ridurre le dimensioni dell'APK di debug del 20-25%.
• Nessuna classe generata inutilizzata nei report: le classi generate che i test non utilizzano non riducono i numeri di copertura.

I miglioramenti effettivi dei tempi di build e delle dimensioni dell'APK dipendono dal progetto.

Prerequisiti

Per utilizzare la copertura del codice on-device, assicurati che il progetto e i dispositivi di test soddisfino i seguenti requisiti:

• AGP 9.6.0-alpha01 o versioni successive.
• Un dispositivo o un emulatore con Android 9 (livello API 28) o versioni successive.
• Un tipo di build abilitato al debug per la variante che testi, ad esempio il tipo di build debug predefinito. L'agente può essere collegato solo ad app abilitate al debug.
• Test strumentati eseguiti con AndroidJUnitRunner o un esecutore di test personalizzato che lo estende.

Attiva la copertura del codice on-device

La copertura del codice on-device utilizza la stessa proprietà enableAndroidTestCoverage della copertura del codice in fase di build. Imposta enableAndroidTestCoverage su true nei file di build a livello di modulo per ogni variante per cui vuoi ottenere report sulla copertura:

Kotlin

android {
    // ...
    buildTypes {
        debug {
            // Enable coverage for instrumentation tests
            enableAndroidTestCoverage = true
        }
    }
}

Alla moda

android {
    // ...
    buildTypes {
        debug {
            // Enable coverage for instrumentation tests
            enableAndroidTestCoverage true
        }
    }
}

Quindi, attiva l'agente di copertura on-device e l'aggregazione dei report nel file gradle.properties del progetto:

android.experimental.androidTest.coverage.useOnDeviceAgent=true
android.experimental.reportAggregationSupport=true

La copertura del codice on-device genera il report HTML con lo stesso renderer dei report sulla copertura del codice unificata, pertanto richiede entrambe le proprietà.

Genera report sulla copertura del codice on-device

Per eseguire i test di instrumentazione e generare report sulla copertura, connetti un dispositivo o avvia un emulatore, quindi esegui la seguente attività:

Ambito di copertura	Comando	Posizione segnalazione
Una variante	./gradlew :module-name:createVariantNameAndroidTestCoverageReport	path-to-your-project/module-name/build/reports/coverage/androidTest/variant/connected/index.html

Differenze rispetto alla copertura del codice in fase di build

I report sulla copertura on-device e in fase di build possono mostrare risultati diversi per gli stessi test. Tieni presente le seguenti differenze quando confronti i due report o quando sposti le soglie di copertura da uno all'altro:

Area	Copertura del codice in fase di build	Copertura del codice on-device
Quando le classi vengono instrumentate	Quando AGP crea la tua app, utilizzando JaCoCo	Sul dispositivo di test durante l'esecuzione dei test, utilizzando l'agente di copertura
Classi nel report	Tutti i corsi del tuo modulo	Solo le classi nello spazio dei nomi del modulo che vengono caricate durante l'esecuzione dei test, in modo che le percentuali di copertura possano essere più elevate
Instruction counts	Istruzioni bytecode Java	Istruzioni di bytecode DEX
Conteggi dei rami	Branch nel bytecode Java	Branch nel bytecode DEX. D8 può compilare le condizioni in rami diversi e ogni strumento tralascia rami diversi generati dal compilatore, pertanto i conteggi possono variare.
Contatori	Istruzioni, rami, righe, complessità, metodi e classi	Istruzioni, rami, righe, metodi e classi. I contatori di complessità non sono ancora supportati.
Dispositivi di test	Tutti i livelli API supportati dalla tua app	Android 9 (livello API 28) e versioni successive
Dati di copertura non elaborati	.ec file	coverage_metadata.pb e coverage_hits.pb file

Per tornare alla copertura del codice in fase di build, imposta android.experimental.androidTest.coverage.useOnDeviceAgent=false o rimuovi la proprietà. Non è necessario modificare i file di build o le attività che esegui.

Problemi noti

La copertura del codice on-device presenta i seguenti problemi noti:

• Classi che non vengono caricate:le classi che non vengono mai caricate durante l'esecuzione dei test non vengono visualizzate nel report. I report sulla copertura del codice in fase di build li elencano con una copertura dello 0%.
• Report aggregati: se il tuo progetto raccoglie anche la copertura dai test host, ad esempio i test delle unità, il report sulla copertura aggregata creato dalle attività testAllSuites e testAllSuitesWithDependencies combina i conteggi del bytecode Java di questi test con i conteggi del bytecode DEX dell'agente. A causa delle differenze tra i due, i numeri aggregati di istruzioni e rami possono differire da quelli dei report sulla copertura del codice in fase di build.

Segnala eventuali altri feedback e problemi tramite l'Issue Tracker.