Ver relatórios de cobertura de código (com agente no dispositivo)

O Plug-in do Android para Gradle (AGP) pode criar relatórios de cobertura de código para seus testes de instrumentação com um agente de cobertura no dispositivo. Por padrão, o AGP instrumenta as classes do app com o JaCoCo ao criá-lo, o que significa que ele adiciona um código que registra quais partes do app são executadas pelos testes. Com o agente de cobertura no dispositivo, o AGP cria o app sem esse código extra, e o agente instrumenta as classes do app no dispositivo de teste enquanto os testes são executados. Nesta página, descrevemos como ativar a cobertura de código no dispositivo e gerar relatórios.

Em comparação com a cobertura de código no momento do build, a cobertura de código no dispositivo oferece os seguintes benefícios:

  • Builds mais rápidos: o AGP não executa a etapa de instrumentação do JaCoCo nas classes do app e nas dependências delas, o que pode reduzir o tempo de build em 10% a 20%.
  • APKs de depuração menores: o AGP não adiciona código de rastreamento de cobertura às classes do app, o que pode reduzir o tamanho do APK de depuração em 20% a 25%.
  • Nenhuma classe gerada não utilizada nos relatórios: as classes geradas que os testes não usam não reduzem os números de cobertura.

As melhorias reais no tempo de compilação e no tamanho do APK dependem do seu projeto.

Pré-requisitos

Para usar a cobertura de código no dispositivo, verifique se o projeto e os dispositivos de teste atendem aos seguintes requisitos:

  • AGP 9.6.0-alpha01 ou mais recente.
  • Um dispositivo ou emulador com o Android 9 (nível 28 da API) ou mais recente.
  • Um tipo de build depurável para a variante que você está testando, como o tipo de build padrão debug. O agente só pode ser anexado a apps depuráveis.
  • Testes instrumentados executados com AndroidJUnitRunner ou um executor de teste personalizado que o estende.

Ativar a cobertura de código no dispositivo

A cobertura de código no dispositivo usa a mesma propriedade enableAndroidTestCoverage que a cobertura de código no momento do build. Defina enableAndroidTestCoverage como true nos arquivos de build do módulo para cada variante que você quer receber relatórios de cobertura:

Kotlin

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

Groovy

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

Em seguida, ative o agente de cobertura no dispositivo e a agregação de relatórios no arquivo gradle.properties do projeto:

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

A cobertura de código no dispositivo gera o relatório HTML com o mesmo renderizador dos relatórios de cobertura de código unificada. Por isso, ela exige as duas propriedades.

Gerar relatórios de cobertura de código no dispositivo

Para executar os testes de instrumentação e gerar relatórios de cobertura, conecte um dispositivo ou inicie um emulador e execute a seguinte tarefa:

Escopo da cobertura Comando Local do relatório
Uma variante ./gradlew :module-name:createVariantNameAndroidTestCoverageReport path-to-your-project/module-name/build/reports/coverage/androidTest/variant/connected/index.html

Diferenças da cobertura de código no momento do build

Os relatórios de cobertura no dispositivo e no momento da compilação podem mostrar resultados diferentes para os mesmos testes. Lembre-se das seguintes diferenças ao comparar os dois relatórios ou ao mover os limites de cobertura de um para o outro:

Área Cobertura de código no momento da criação Cobertura de código no dispositivo
Quando as classes são instrumentadas Quando o AGP cria o app, usando o JaCoCo, No dispositivo de teste enquanto os testes são executados, usando o agente de cobertura.
Classes no relatório Todas as classes no módulo Somente as classes no namespace do módulo que são carregadas durante a execução dos testes, para que as porcentagens de cobertura sejam maiores.
Contagens de instruções Instruções de bytecode Java Instruções de bytecode DEX
Contagens de ramificações Ramificações no bytecode Java Ramificações no bytecode DEX. O D8 pode compilar condições em ramificações diferentes, e cada ferramenta deixa de fora ramificações diferentes geradas pelo compilador, então as contagens podem ser diferentes.
Contadores Instruções, ramificações, linhas, complexidade, métodos e classes Instruções, ramificações, linhas, métodos e classes. Os contadores de complexidade ainda não são compatíveis.
Dispositivos de teste Todos os níveis da API compatíveis com o app Android 9 (API de nível 28) e versões mais recentes
Dados brutos de cobertura .ec arquivos Arquivos coverage_metadata.pb e coverage_hits.pb

Para voltar à cobertura de código no momento da criação, defina android.experimental.androidTest.coverage.useOnDeviceAgent=false ou remova a propriedade. Não é necessário mudar os arquivos de build ou as tarefas que você executa.

Problemas conhecidos

A cobertura de código no dispositivo tem os seguintes problemas conhecidos:

  • Classes que não são carregadas:as classes que nunca são carregadas durante a execução dos testes não aparecem no relatório. Os relatórios de cobertura de código do tempo de compilação os listam com 0% de cobertura.
  • Relatórios agregados:se o projeto também coletar cobertura de testes de host, como testes de unidade, o relatório de cobertura agregado criado pelas tarefas testAllSuites e testAllSuitesWithDependencies vai combinar as contagens de bytecode Java desses testes com as contagens de bytecode DEX do agente. Devido às diferenças entre os dois, os números agregados de instruções e ramificações podem ser diferentes dos números nos relatórios de cobertura de código do tempo de build.

Envie outros feedbacks e problemas pelo Issue Tracker.