Software bugs cost time and money. One of the best ways to catch them early is by testing your code. But how do you know if your unit tests actually test everything?
That is where JaCoCo comes in.
In this tutorial, you will learn exactly how to set up JaCoCo in a Java project, generate visual coverage reports, and enforce strict quality rules to keep your code clean.
Table of Contents
What is JaCoCo?
JaCoCo stands for Java Coverse Coverage. It is a free, open-source library that measures how much of your Java code is executed when your unit tests run.
Using a java code coverage tool like JaCoCo calculates critical metrics like:
- Line Coverage: Did your tests run every line of code?
- Branch Coverage: Did your tests check both the
trueandfalseoutcomes of yourif/elsestatements? - Complexity: Which parts of your code are too complex and need more tests?
Step 1: Add JaCoCo to Your Maven Project
To get started with jacoco java test coverage, you need to add the jacoco-maven-plugin to your pom.xml file. This tells Maven to track your tests and build a report.
Open your pom.xml file and insert this jacoco maven plugin example configuration inside the <plugins> section:
<build>
<plugins>
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.11</version>
<executions>
<!-- Prepares the property pointing to the JaCoCo runtime agent -->
<execution>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
<!-- Generates the coverage report after tests run -->
<execution>
<id>report</id>
<phase>test</phase>
<goals>
<goal>report</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Step 2: Run Tests and Generate the Report
Once the plugin is configured, learning how to use jacoco in java to generate your report takes just one command. Open your terminal, navigate to your project folder, and run:
mvn clean testWhere to Find the JaCoCo Report Maven Output:
After the build finishes successfully, JaCoCo creates an HTML report. Go to your project folder and follow this path to find your maven code coverage report:
target/site/jacoco/index.html
Double-click the index.html file to open it in any web browser.
Step 3: Understanding Your JaCoCo Report
When you view the report in your browser, JaCoCo uses a simple color-coding system to show you exactly what needs attention:
- 🟢 Green (Fully Covered): Your unit tests successfully executed these lines of code.
- 🟡 Yellow (Partially Covered): These lines were executed, but not all paths were tested (e.g., an
ifstatement was triggered, but theelsebranch was skipped). - 🔴 Red (Uncovered Code): Your unit tests completely missed these lines. You need to write new tests for them.
Step 4: Enforce a Minimum Code Coverage (Quality Gates)
As projects grow, developers sometimes forget to write tests for new features. You can configure JaCoCo to fail the build automatically if code coverage drops below a specific percentage.
Add this <execution> block inside your JaCoCo plugin in pom.xml to enforce an 80% coverage rule:
<execution>
<id>check</id>
<goals>
<goal>check</goal>
</goals>
<configuration>
<rules>
<rule>
<element>BUNDLE</element>
<limits>
<limit>
<counter>LINE</counter>
<value>COVEREDRATIO</value>
<minimum>0.80</minimum> <!-- 80% minimum coverage -->
</limit>
</limits>
</rule>
</rules>
</configuration>
</execution>
Now, if someone tries to build the project with less than 80% line coverage, Maven will stop the build and show an error.
Step 5: How to Exclude Specific Classes (Like DTOs)
Data Transfer Objects (DTOs), boilerplate getters/setters, configuration files, and auto-generated code do not contain business logic. Including them in your jacoco java test coverage metrics artificially lowers your coverage score.
You can easily use the <configuration> block to tell the plugin to ignore these files.
Update Your pom.xml to Exclude Classes
To set up a jacoco exclude classes maven rule, add an <excludes> list to your report and check executions in your pom.xml:
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.11</version>
<executions>
<execution>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
<execution>
<id>report</id>
<phase>test</phase>
<goals>
<goal>report</goal>
</goals>
<!-- Add exclusions for the generated HTML report -->
<configuration>
<excludes>
<exclude>**/dto/**</exclude>
<exclude>**/*Dto.*</exclude>
<exclude>**/config/**</exclude>
</excludes>
</configuration>
</execution>
<execution>
<id>check</id>
<goals>
<goal>check</goal>
</goals>
<!-- Add identical exclusions for the quality gate rule check -->
<configuration>
<excludes>
<exclude>**/dto/**</exclude>
<exclude>**/*Dto.*</exclude>
<exclude>**/config/**</exclude>
</excludes>
<rules>
<rule>
<element>BUNDLE</element>
<limits>
<limit>
<counter>LINE</counter>
<value>COVEREDRATIO</value>
<minimum>0.80</minimum>
</limit>
</limits>
</rule>
</rules>
</configuration>
</execution>
</executions>
</plugin>
Breakdown of Exclusion Wildcards:
**/dto/**: Excludes every single class inside any folder nameddto.**/*Dto.*: Excludes any class whose filename ends withDto(e.g.,UserDto.class).**/config/**: Excludes your framework configuration files.
By filtering out these non-essential files, your final maven code coverage report will reflect the true health of your actual core business logic.
Conclusion
Setting up jacoco java test coverage ensures your Java applications remain stable, well-tested, and reliable. By tracking line coverage and setting up automated quality gates, you stop bugs before they ever reach production.