Table of Contents
The JaCoCo plugin is currently incubating. Please be aware that the DSL and other configuration may change in later Gradle versions.
The JaCoCo plugin provides code coverage metrics for Java code via integration with JaCoCo.
To get started, apply the JaCoCo plugin to the project you want to calculate code coverage for.
If the Java plugin is also applied to your project, a new task named jacocoTestReport
is created that depends on the test
task. The report is available at $buildDir/reports/jacoco/test
. By default, a HTML report is generated.
The JaCoCo plugin adds a project extension named jacoco
of type JacocoPluginExtension
, which allows configuring defaults for JaCoCo usage in your build.
Example 64.2. Configuring JaCoCo plugin settings
build.gradle
jacoco { toolVersion = "0.7.6.201602180812" reportsDir = file("$buildDir/customJacocoReportDir") }
Table 64.1. Gradle defaults for JaCoCo properties
Property | Gradle default |
reportsDir |
|
The JacocoReport
task can be used to generate code coverage reports in different formats. It implements the standard Gradle type Reporting
and exposes a report container of type JacocoReportsContainer
.
Example 64.3. Configuring test task
build.gradle
jacocoTestReport {
reports {
xml.enabled false
csv.enabled false
html.destination file("${buildDir}/jacocoHtml")
}
}
This feature requires the use of JaCoCo version 0.6.3 or higher.
The JacocoCoverageVerification
task can be used to verify if code coverage metrics are met based on configured rules. Its API exposes the method JacocoCoverageVerification.violationRules(org.gradle.api.Action)
which is used as main entry point for configuring rules. Invoking any of those methods returns an instance of JacocoViolationRulesContainer
providing extensive configuration options. The build fails if any of the configured rules are not met. JaCoCo only reports the first violated rule.
Code coverage requirements can be specified for a project as a whole, for individual files, and for particular JaCoCo-specific types of coverage, e.g., lines covered or branches covered. The following example describes the syntax.
Example 64.4. Configuring violation rules
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 } } } }
Note: The code for this example can be found at samples/testing/jacoco/quickstart
in the ‘-all’ distribution of Gradle.
The JacocoCoverageVerification
task is not a task dependency of the check
task provided by the Java plugin. There is a good reason for it. The task is currently not incremental as it doesn’t declare any outputs. Any violation of the declared rules would automatically result in a failed build when executing the check
task. This behavior might not be desirable for all users. Future versions of Gradle might change the behavior.
The JaCoCo plugin adds a JacocoTaskExtension
extension to all tasks of type Test
. This extension allows the configuration of the JaCoCo specific properties of the test task.
Example 64.5. Configuring test task
build.gradle
test { jacoco { append = false destinationFile = file("$buildDir/jacoco/jacocoTest.exec") classDumpDir = file("$buildDir/jacoco/classpathdumps") } }
Table 64.2. Default values of the JaCoCo Task extension
Property | Gradle default |
enabled |
true |
destPath |
|
append |
true |
includes |
[] |
excludes |
[] |
excludeClassLoaders |
[] |
includeNoLocationClasses |
false |
sessionId |
|
dumpOnExit |
|
output |
|
address |
|
port |
|
classDumpPath |
|
jmx |
|
While all tasks of type Test
are automatically enhanced to provide coverage information when the java
plugin has been applied, any task that implements JavaForkOptions
can be enhanced by the JaCoCo plugin. That is, any task that forks Java processes can be used to generate coverage information.
For example you can configure your build to generate code coverage using the application
plugin.
Example 64.6. Using application plugin to generate code coverage data
build.gradle
apply plugin: "application" apply plugin: "jacoco" mainClassName = "org.gradle.MyMain" jacoco { applyTo run } task applicationCodeCoverageReport(type:JacocoReport){ executionData run sourceSets sourceSets.main }
Note: The code for this example can be found at samples/testing/jacoco/application
in the ‘-all’ distribution of Gradle.
Example 64.7. Coverage reports generated by applicationCodeCoverageReport
Build layout
application/ build/ jacoco/ run.exec reports/jacoco/applicationCodeCoverageReport/html/ index.html
For projects that also apply the Java Plugin, The JaCoCo plugin automatically adds the following tasks:
Table 64.3. JaCoCo plugin - tasks
Task name | Depends on | Type | Description |
|
- |
Generates code coverage report for the test task. |
|
|
- |
Verifies code coverage metrics based on specified rules for the test task. |
The JaCoCo plugin adds the following dependency configurations:
Table 64.4. JaCoCo plugin - dependency configurations
Name | Meaning |
|
The JaCoCo Ant library used for running the |
|
The JaCoCo agent library used for instrumenting the code under test. |