Introduction

JaCoCo is an open-source tool that provides code coverage reports for Java programs. These reports are invaluable in software development as they offer insights into which parts of the code are being tested and the extent of the testing. This ensures both code quality and robustness. In the context of a Gradle project, integrating JaCoCo and filtering its coverage reports can enhance the review process by ensuring that only relevant parts of the codebase are included in the coverage analysis.

Understanding JaCoCo

JaCoCo stands for Java Code Coverage. It is a widely used tool because of its efficiency, compatibility, and the granularity of detail it provides. This tool offers the following types of code coverage:

1. Instruction Coverage: Verifies which bytecode instructions were executed.
2. Line Coverage: Checks which lines in the source code were executed.
3. Branch Coverage: Evaluates code execution paths, particularly important for conditional statements.
4. Method Coverage: Indicates which methods were called during tests.
5. Class Coverage: Shows the classes loaded and executed.

Integrating JaCoCo with Gradle

To use JaCoCo with Gradle, you need to apply the JaCoCo plugin in your build.gradle file:

1plugins {
2    id 'java'
3    id 'jacoco'
4}

The JaCoCo plugin automatically hooks into the test task in Gradle, which means it starts collecting coverage data as the tests run.

Configuring JaCoCo

You might want modifications tailored to your project needs, such as filtering unwanted source directories or only targeting specific classes. You can configure JaCoCo in Gradle using the following setup:

1jacoco {
2    toolVersion = "0.8.8" // Specify tool version
3}
4
5jacocoTestReport {
6    reports {
7        xml.required = true 
8        csv.required = false 
9        html.outputLocation = file("$buildDir/reports/jacoco") // Specify HTML report output directory
10    }
11}

Filtering JaCoCo Coverage Reports

Filtering a JaCoCo coverage report helps to focus on what matters by excluding classes, methods, or packages you don't want in your final report, such as generated code, third-party libraries, or utility classes.

Excluding Specific Classes and Packages

To exclude certain classes or packages, you can use the excludes property in your jacocoTestReport configuration:

1jacocoTestReport {
2    reports {
3        xml.required = true
4    }
5    
6    classDirectories.setFrom(files(
7        sourceSets.main.output.asFileTree.matching {
8            exclude '**/SomeExclusionClass*', '**/SomePackage/**'
9        }
10    ))
11}

This configuration excludes any class with the name SomeExclusionClass and any code under the SomePackage directory.

Excluding from Test Task

It's also possible to remove certain classes that are not required during the test execution but are part of your dependencies or auxiliary classes:

test {
    exclude '**/SomeAuxiliaryClass*'
}

Custom Exclusion Patterns

Filtering can also be more sophisticated by utilizing custom patterns. For example, you can exclude all utility classes using a pattern:

exclude '**/utils/**', '**/*Utils.class'

Example: Putting it All Together

Here's a complete example that includes all of the aforementioned configurations:

1plugins {
2    id 'java'
3    id 'jacoco'
4}
5
6jacoco {
7    toolVersion = "0.8.8"
8}
9
10test {
11    exclude '**/SomeAuxiliaryClass*'
12}
13
14jacocoTestReport {
15    dependsOn test // Ensures tests are run before generating the report
16
17    classDirectories.setFrom(files(
18        sourceSets.main.output.asFileTree.matching {
19            exclude '**/SomeExclusionClass*', '**/SomePackage/**'
20        }
21    ))
22
23    reports {
24        xml.required = true
25        html.outputLocation = file("$buildDir/reports/jacoco")
26    }
27}

Conclusion

Managing and filtering JaCoCo coverage reports strategically will help in concentrating on the code that holds substantial value and is integral to the application's functionality. While JaCoCo provides an out-of-the-box solution to code coverage, customizing your reports in the Gradle build can lead to clearer and more actionable insights.

Key Points Summary

The table below summarizes the key configurations when filtering JaCoCo coverage reports with Gradle:

By harnessing these configurations, developers can accurately scrutinize relevant parts of their code with JaCoCo, leading to better code coverage insights and improved overall project health.