JaCoCo 插件通过与 JaCoCo 集成,为 Java 代码提供代码覆盖率指标。
入门
首先,将 JaCoCo 插件应用到您要计算代码覆盖率的项目中。
plugins {
jacoco
}
plugins {
id 'jacoco'
}
如果 Java 插件也应用于您的项目,则会创建一个名为 jacocoTestReport
的新任务。默认情况下,HTML 报告在 layout.buildDirectory.dir("reports/jacoco/test")
生成。
虽然应在生成报告之前执行测试,但 jacocoTestReport 任务不依赖于 test 任务。 |
根据您的用例,您可能希望始终生成 jacocoTestReport
,或者在明确生成报告之前运行 test
任务。
tasks.test {
finalizedBy(tasks.jacocoTestReport) // report is always generated after tests run
}
tasks.jacocoTestReport {
dependsOn(tasks.test) // tests are required to run before generating the report
}
test {
finalizedBy jacocoTestReport // report is always generated after tests run
}
jacocoTestReport {
dependsOn test // tests are required to run before generating the report
}
配置 JaCoCo 插件
JaCoCo 插件添加了一个名为 jacoco
的项目扩展,类型为 JacocoPluginExtension,允许配置构建中 JaCoCo 用法的默认值。
jacoco {
toolVersion = "0.8.13"
reportsDirectory = layout.buildDirectory.dir("customJacocoReportDir")
}
jacoco {
toolVersion = "0.8.13"
reportsDirectory = layout.buildDirectory.dir('customJacocoReportDir')
}
属性 | Gradle 默认值 |
---|---|
reportsDirectory |
|
JaCoCo 报告配置
JacocoReport 任务可用于生成不同格式的代码覆盖率报告。它实现了标准 Gradle 类型 Reporting 并暴露了类型为 JacocoReportsContainer 的报告容器。
tasks.jacocoTestReport {
reports {
xml.required = false
csv.required = false
html.outputLocation = layout.buildDirectory.dir("jacocoHtml")
}
}
jacocoTestReport {
reports {
xml.required = false
csv.required = false
html.outputLocation = layout.buildDirectory.dir('jacocoHtml')
}
}

强制执行代码覆盖率指标
此功能需要使用 JaCoCo 0.6.3 或更高版本。 |
JacocoCoverageVerification 任务可用于根据配置的规则验证代码覆盖率指标是否满足。其 API 暴露了 JacocoCoverageVerification.violationRules(org.gradle.api.Action) 方法,该方法用作配置规则的主要入口点。调用这些方法中的任何一个都将返回 JacocoViolationRulesContainer 实例,提供广泛的配置选项。如果任何配置的规则未满足,则构建失败。JaCoCo 只报告第一个违规规则。
可以为整个项目、单个文件和特定 JaCoCo 特定类型的覆盖率(例如,覆盖行或覆盖分支)指定代码覆盖率要求。以下示例描述了语法。
tasks.jacocoTestCoverageVerification {
violationRules {
rule {
limit {
minimum = "0.5".toBigDecimal()
}
}
rule {
isEnabled = false
element = "CLASS"
includes = listOf("org.gradle.*")
limit {
counter = "LINE"
value = "TOTALCOUNT"
maximum = "0.3".toBigDecimal()
}
}
}
}
jacocoTestCoverageVerification {
violationRules {
rule {
limit {
minimum = 0.5
}
}
rule {
enabled = false
element = 'CLASS'
includes = ['org.gradle.*']
limit {
counter = 'LINE'
value = 'TOTALCOUNT'
maximum = 0.3
}
}
}
}
JacocoCoverageVerification 任务不是 Java 插件提供的 check
任务的任务依赖项。这样做有充分的理由。该任务目前不是增量的,因为它不声明任何输出。执行 check
任务时,任何已声明规则的违规都会自动导致构建失败。此行为可能不适用于所有用户。Gradle 的未来版本可能会更改此行为。
JaCoCo 特定任务配置
JaCoCo 插件向所有 Test 类型的任务添加 JacocoTaskExtension 扩展。此扩展允许配置测试任务的 JaCoCo 特定属性。
tasks.test {
extensions.configure(JacocoTaskExtension::class) {
destinationFile = layout.buildDirectory.file("jacoco/jacocoTest.exec").get().asFile
classDumpDir = layout.buildDirectory.dir("jacoco/classpathdumps").get().asFile
}
}
test {
jacoco {
destinationFile = layout.buildDirectory.file('jacoco/jacocoTest.exec').get().asFile
classDumpDir = layout.buildDirectory.dir('jacoco/classpathdumps').get().asFile
}
}
配置为使用 JaCoCo 代理运行的任务在任务开始执行时会删除执行数据的目标文件。这确保执行数据中不存在过时的覆盖率数据。 |
JaCoCo 任务扩展的默认值
tasks.test {
configure<JacocoTaskExtension> {
isEnabled = true
destinationFile = layout.buildDirectory.file("jacoco/${name}.exec").get().asFile
includes = emptyList()
excludes = emptyList()
excludeClassLoaders = emptyList()
isIncludeNoLocationClasses = false
sessionId = "<auto-generated value>"
isDumpOnExit = true
classDumpDir = null
output = JacocoTaskExtension.Output.FILE
address = "localhost"
port = 6300
isJmx = false
}
}
test {
jacoco {
enabled = true
destinationFile = layout.buildDirectory.file("jacoco/${name}.exec").get().asFile
includes = []
excludes = []
excludeClassLoaders = []
includeNoLocationClasses = false
sessionId = "<auto-generated value>"
dumpOnExit = true
classDumpDir = null
output = JacocoTaskExtension.Output.FILE
address = "localhost"
port = 6300
jmx = false
}
}
虽然所有 Test 类型的任务在应用 java
插件时都会自动增强以提供覆盖率信息,但任何实现 JavaForkOptions 的任务都可以通过 JaCoCo 插件进行增强。也就是说,任何分叉 Java 进程的任务都可以用于生成覆盖率信息。
例如,您可以配置构建以使用 application
插件生成代码覆盖率。
plugins {
application
jacoco
}
application {
mainClass = "org.gradle.MyMain"
}
jacoco {
applyTo(tasks.run.get())
}
tasks.register<JacocoReport>("applicationCodeCoverageReport") {
executionData(tasks.run.get())
sourceSets(sourceSets.main.get())
}
plugins {
id 'application'
id 'jacoco'
}
application {
mainClass = 'org.gradle.MyMain'
}
jacoco {
applyTo run
}
tasks.register('applicationCodeCoverageReport', JacocoReport) {
executionData run
sourceSets sourceSets.main
}
. └── build ├── jacoco │ └── run.exec └── reports └── jacoco └── applicationCodeCoverageReport └── html └── index.html
任务
对于同时应用 Java 插件的项目,JaCoCo 插件会自动添加以下任务
jacocoTestReport
— JacocoReport-
为测试任务生成代码覆盖率报告。
jacocoTestCoverageVerification
— JacocoCoverageVerification-
根据测试任务的指定规则验证代码覆盖率指标。
依赖管理
JaCoCo 插件添加了以下依赖配置
名称 | 含义 |
---|---|
|
用于运行 |
|
用于检测被测代码的 JaCoCo 代理库。 |
输出变体
当一个生成 JaCoCo 覆盖率数据的项目与 JVM 测试套件插件 一起应用时,将创建额外的输出变体。这些变体旨在供 JaCoCo 报告聚合插件 消费。
属性将类似于以下内容。用户可配置的属性在示例下方突出显示。
--------------------------------------------------
Variant coverageDataElementsForTest (i)
--------------------------------------------------
Binary results containing Jacoco test coverage for all targets in the 'test' Test Suite.
Capabilities
- org.gradle.sample:application:1.0.2 (default capability)
Attributes
- org.gradle.category = verification
- org.gradle.testsuite.name = test (1)
- org.gradle.verificationtype = jacoco-coverage
Artifacts
- build/jacoco/test.exec (artifactType = binary)
1 | TestSuiteName 属性;值派生自 TestSuite#getName()。 |