Глава 64. Плагин JaCoCo.

На данный момент плагин JaCoCo инкубационный. Пожалуйста, знайте, что DSL и другая конфигурация может измениться в последних версиях Gradle.

Плагин JaCoCo предоставляет метрики покрытия кода Java посредством интеграции с JaCoCo.

64.1. Начало работы.

Чтобы начать работать с плагином JaCoCo, примените его к проекту, для которого вы хотите подсчитывать покрытие кода.

Пример 64.1. Применение плагина JaCoCo

build.gradle

apply plugin: "jacoco"
	  

Если к тому же применен плагин Java, то создается новая задача jacocoTestReport, которая зависит от задачи test. Отчет доступен в папке $папкаСборки/reports/jacoco/test. По умолчанию, генерится HTML-отчет.

64.2. Настройка плагина JaCoCo.

Плагин JaCoCo добавляет расширение проекта с именем jacoco и типом JacocoPluginExtension, которое позволяет настроить умолчания JaCoCo, используемые в вашей сборке.

Пример 64.2. Конфигурация умолчаний плагина JaCoCo

build.gradle

jacoco {
    toolVersion = "0.7.6.201602180812"
    reportsDir = file("$buildDir/customJacocoReportDir")
}
	  
Таблица 64.1. Значения по умолчанию в Gradle для свойств JaCoCo
СвойствоЗначение по умолчанию в Gradle
reportsDir“$папкаСборки/reports/jacoco”

64.3. Настройка задачи JacocoReport.

Задача JacocoReport может использовать для генерации отчетов покрытия кода в различных форматах. Она реализует стандартный тип Gradle Reporting и выставляет наружу контейнер отчетов типа JacocoReportsContainer.

Пример 64.3. Настройка задачи test

build.gradle

jacocoTestReport {
    reports {
        xml.enabled false
        csv.enabled false
        html.destination "${buildDir}/jacocoHtml"
    }
}
	  
Отчет JaCoCo

64.4. Принудительное соблюдение метрик покрытия кода.

Задача JacocoCoverageVerification может использовать для проверки удовлетворения метрик покрытия кода настроенным правилам. В ее API есть метод JacocoCoverageVerification.violationRules(org.gradle.api.Action), который используется в качестве основной точки входа для настройки правил. Выполнение любого из этих методов, возвращает экземпляр JacocoViolationRulesContainer, предоставляющий всесторонние опции настройки. Сборка прерывается, если не соблюдается любое из настроенных правил. JaCoCo сообщает только о первом нарушенном правиле.

Требования покрытия кода могут быть указаны для проекта в целом, для индивидуальных правил и для определенных типов, присущих JaCoCo, например, покрытие строк или ветвей. Следующий пример описывает синтакс.

Пример 64.4. Настройка правил

build.gradle

jacocoTestCoverageVerification {
    violationRules {
        rule {
            limit {
                minimum = 0.5
            }
        }

        rule {
            enabled = false
            element = 'CLASS'
            includes = ['org.gradle.*']

            limit {
                counter = 'LINE'
                value = 'TOTALCOUNT'
                maximum = 0.3
            }
        }
    }
}
	  

Примечание: код этого примера можно найти в папке samples/testing/jacoco/quickstart дистрибутива Gradle '-all'.

Задача JacocoCoverageVerification не является зависимостью задачи check, предоставляемой плагином Java. Для этого есть хорошая причина. Сейчас задача не инкрементная, так как она не объявляет никаких выходных данных. Любое нарушение объявленных правил автоматически приведет к падению сборки при выполнении задачи check. Такое поведение может быть нежелательным для всех пользователей. В будущих версиях Gradle поведение может поменяться.

64.5. Особая настройка задачи JaCoCo.

Плагин JaCoCo добавляет расширение JacocoTaskExtension ко всем задачам типа Test. Это расширение позволяет настраивать особые свойства JaCoCo задачи test.

Пример 64.5. Настройка задачи test

build.gradle

test {
    jacoco {
        append = false
        destinationFile = file("$buildDir/jacoco/jacocoTest.exec")
        classDumpDir = file("$buildDir/jacoco/classpathdumps")
    }
}
	  
Таблица 64.2. Значения по умолчанию расширения задачи JaCoCo
СвойствоЗначение по умолчанию в Gradle
enabledtrue
destPath$bпапкаСборки/jacoco
appendtrue
includes[]
excludes[]
excludeClassLoaders[]
includeNoLocationClassesfalse
sessionIdauto-generated
dumpOnExittrue
outputOutput.FILE
address-
port-
classDumpPath-
jmxfalse

В то время как все задачи типа Test автоматически расширяются для преоставления информации о покрытии, когда плагин java применяется, любая задача, которая реализует JavaForkOptions, может быть расширена плагином JaCoCo. То есть, любая задача, которая создает новые процессы Java, может быть использована для генерации информации о покрытии.

Например, вы можете настроить вашу сборку так, чтобы генерировать покрытие кода с использованием плагина application.

Пример 64.6. Использование плагина application для генерации данных о покрытии кода

build.gradle

apply plugin: "application"
apply plugin: "jacoco"

mainClassName = "org.gradle.MyMain"

jacoco {
    applyTo run
}

task applicationCodeCoverageReport(type:JacocoReport){
    executionData run
    sourceSets sourceSets.main
}
	  

Примечание: код этого примера можно найти в папке samples/testing/jacoco/application дистрибутива Gradle '-all'.

Пример 64.7. Отчеты о покрытии, сгенерированные applicationCodeCoverageReport

Разметка сборки

application/
  build/
    jacoco/
      run.exec
    reports/jacoco/applicationCodeCoverageReport/html/
      index.html
	  

64.6. Задачи.

Для проектов, которые также применяют плагин Java, плагин JaCoCo автоматически добавляет следующие задачи:

Таблица 64.3. Плагин JaCoCo - задачи
Имя задачиЗависит отТипОписание
jacocoTestReport-JacocoReportГенерирует отчет о покрытии кода для задачи test
jacocoTestCoverageVerification-JacocoCoverageVerificationПроверяет метрики покрытия кода, основанные на указанных правилах для задачи test.

64.7. Управление зависимостями.

Плагин JaCoCo добавляет следующие конфигурации зависимостей:

Таблица 64.4. Плагин JaCoCo - конфигурации зависимостей
ИмяЗначение
jacocoAntБиблиотека JaCoCo Ant, используемая для запуска задач JacocoReport, JacocoMerge и JacocoCoverageVerification.
jacocoAgentАгентная Библиотека JaCoCo, используемая для управления тестируемым кодом.