# Chapter 34. The JaCoCo Plugin

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.

## 34.1. Getting Started

To get started, apply the JaCoCo plugin to the project you want to calculate code coverage for.

Example 34.1. Applying the JaCoCo plugin

`build.gradle`

    apply plugin: "jacoco"

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.

## 34.2. Configuring the JaCoCo Plugin

The JaCoCo plugin adds a project extension named `jacoco` of type `JacocoPluginExtension`, which allows configuring defaults for JaCoCo usage in your build.

Example 34.2. Configuring JaCoCo plugin settings

`build.gradle`

    jacoco {
        toolVersion = "0.6.2.201302030002"
        reportsDir = file("$buildDir/customJacocoReportDir")
    }

Table 34.1. Gradle defaults for JaCoCo properties

Property | Gradle default
reportsDir | "`$buildDir`/reports/jacoco"

## 34.3. JaCoCo Report configuration

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 34.3. Configuring test task

`build.gradle`

    jacocoTestReport {
        reports {
            xml.enabled false
            csv.enabled false
            html.destination "${buildDir}/jacocoHtml"
        }
    }

## 34.4. JaCoCo specific task configuration

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 34.4. Configuring test task

`build.gradle`

    test {
        jacoco {
            append = false
            destinationFile = file("$buildDir/jacoco/jacocoTest.exec")
            classDumpFile = file("$buildDir/jacoco/classpathdumps")
        }
    }

Table 34.2. Default values of the JaCoCo Task extension

Property | Gradle default
enabled | true
destPath | `$buildDir`/jacoco
append | true
includes | []
excludes | []
excludeClassLoaders | []
sessionId | `auto-generated`
dumpOnExit | `true`
output | `Output.FILE`
address | `-`
port | `-`
classDumpPath | `-`
jmx | `false`

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 34.5. 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` which is in both the binary and source distributions of Gradle.

Example 34.6. Coverage reports generated by applicationCodeCoverageReport

Build layout

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

## 34.5. Tasks

For projects that also apply the Java Plugin, The JaCoCo plugin automatically adds the following tasks:

Table 34.3. JaCoCo plugin - tasks

Task name | Depends on | Type | Description
`jacocoTestReport` | - | `JacocoReport` | Generates code coverage report for the test task.

## 34.6. Dependency management

The JaCoCo plugin adds the following dependency configurations:

Table 34.4. JaCoCo plugin - dependency configurations

Name | Meaning
`jacocoAnt` | The JaCoCo Ant library used for running the `JacocoReport` and `JacocoMerge` tasks.
`jacocoAgent` | The JaCoCo agent library used for instrumenting the code under test.