Java Code Coverage Tools: How to Measure Test Coverage
- Total lines of code
- 1000 lines
- You entered
- Lines covered by tests
- 750 lines
- You entered
To measure test coverage in Java, you use a code coverage tool that instruments your compiled classes, runs your test suite, and reports which lines, branches, and methods were executed. You typically integrate the tool with your build (Maven or Gradle), run your tests, and then view an HTML or XML report showing coverage percentages per package, class, and method.
Formula
Line coverage is the simplest and most commonly reported metric. It is calculated as:
Line Coverage (%) = (Number of Lines Executed / Total Number of Executable Lines) × 100
- Lines executed – the number of source lines that were run at least once during the test suite.
- Total executable lines – the number of lines containing actual code (excluding comments, blank lines, and often declarations).
For example, if your project has 1,000 executable lines and your tests execute 750 of them, the line coverage is 75%. This is the number most tools display prominently, but it is only one of several coverage criteria.
Worked Example
Using the default values from the calculator above (1,000 total lines, 750 covered):
- Identify the total executable lines: 1,000
- Identify the lines covered by tests: 750
- Divide covered by total: 750 ÷ 1,000 = 0.75
- Multiply by 100 to get a percentage: 0.75 × 100 = 75%
The calculator returns 75.0%, which is the line coverage percentage you would report.
How Java Coverage Tools Work
Java coverage tools use one of two instrumentation approaches:
- Source instrumentation – the tool modifies your source code before compilation, inserting counters at each line or branch. This approach is less common now because it requires a separate source copy and can be slow.
- Bytecode instrumentation – the tool modifies the compiled .class files, either at build time (offline) or when the JVM loads them (on-the-fly). JaCoCo, the most popular Java coverage tool, uses on-the-fly instrumentation via a Java agent, so no source changes are needed.
When you run your tests with the agent attached, the instrumented classes record which lines, branches, and methods are executed. After the test run, the tool merges the data and generates a report. The report typically shows a percentage for each metric and allows you to drill down to individual classes and methods to see exactly which lines were missed.
Types of Coverage Metrics
Coverage tools report several different metrics, and it is important to understand what each one means:
- Line coverage – the percentage of executable lines that were run. This is the most intuitive but can be misleading because a single line may contain multiple branches or conditions.
- Branch coverage – the percentage of branches (e.g., if/else, switch cases) that were taken. If an if statement has no else, the tool counts both the true and false paths. 100% line coverage does not imply 100% branch coverage.
- Method coverage – the percentage of methods that were called at least once. Useful for spotting entirely untested classes.
- Instruction coverage – the percentage of JVM bytecode instructions executed. This is the lowest-level metric and is what JaCoCo uses as its base for line coverage.
- Condition coverage – measures whether each boolean sub-expression in a condition has been evaluated to both true and false. This is more granular than branch coverage.
Most teams focus on line and branch coverage because they are easy to understand and correlate with test effectiveness, but no single metric guarantees that your tests are good – coverage only tells you what was executed, not that the assertions were correct.
Choosing a Tool: JaCoCo, Cobertura, and OpenClover
The main Java coverage tools are JaCoCo, Cobertura, and OpenClover. JaCoCo is the de facto standard today because it is actively maintained, supports modern Java versions, integrates well with Maven and Gradle, and has a clean API. Cobertura is older and less maintained, but still appears in legacy projects. OpenClover is a commercial tool (with a free community edition) that offers more detailed metrics and per-test coverage, but its development has slowed.
For most new projects, JaCoCo is the recommended choice. It works with both Maven and Gradle, produces HTML reports that are easy to read, and can fail the build if coverage drops below a threshold. To use it with Maven, you add the JaCoCo plugin to your pom.xml and run mvn test – the report is generated in target/site/jacoco. With Gradle, you apply the JaCoCo plugin and run gradle test jacocoTestReport.
Setting Up JaCoCo with Maven and Gradle
Here is a minimal setup for each build tool:
Maven (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>
</execution>
</executions>
</plugin>
Gradle (build.gradle):
plugins {
id 'java'
id 'jacoco'
}
jacocoTestReport {
reports {
xml.required = true
html.required = true
}
}
After running gradle test jacocoTestReport, the HTML report is in build/reports/jacoco/test/html. You can also set a coverage rule to fail the build if coverage is below a threshold, for example 80% line coverage.
Common Mistakes and Misconceptions
- Confusing line coverage with branch coverage – a single line like
if (a && b)has multiple branches and conditions. High line coverage can still miss half the possible outcomes. - Ignoring the report details – a green 90% overall number can hide a critical class with 0% coverage. Always drill down to see which classes are untested.
- Testing only happy paths – coverage tools show you which lines were not executed, but they cannot tell you if your assertions are meaningful. A test that calls a method and checks nothing still counts as coverage.
- Not excluding generated code – Lombok-generated methods, DTOs, and other boilerplate can inflate or deflate coverage. Configure the tool to exclude them for a more accurate picture.
How to Interpret Coverage Reports
The HTML report from JaCoCo colors each line green (covered), yellow (partially covered – e.g., a branch not taken), or red (not covered). The summary shows percentages for instruction, branch, line, method, and class coverage. A common target is 80% line and branch coverage, but the right number depends on your project’s risk tolerance. Critical business logic deserves higher coverage, while simple getters and setters may not need any.
Use coverage reports to find untested code, not as a score to chase. If you see a red block, write a test that exercises it. If you see a yellow branch, add a test for the missing condition. After adding tests, re-run the report to confirm the coverage improved.
Frequently Asked Questions
What is the difference between JaCoCo and Cobertura?
JaCoCo is actively maintained, supports modern Java (up to Java 21), and uses bytecode instrumentation with an agent. Cobertura is older, supports up to Java 8, and has not seen significant updates in years. For new projects, JaCoCo is the safer choice.
Can I measure coverage without a build tool?
Yes. You can run JaCoCo as a Java agent manually: java -javaagent:jacocoagent.jar=destfile=jacoco.exec -jar myapp.jar, then run your tests and use the JaCoCo CLI to generate a report. However, integrating with Maven or Gradle is much easier.
Does 100% line coverage mean my code is bug-free?
No. Coverage only tells you which lines were executed, not whether the assertions verified the correct behavior. You could have 100% line coverage but still miss edge cases, concurrency issues, or incorrect logic that only appears under specific conditions.
How can I enforce a minimum coverage threshold?
In Maven, use the check goal with rules, e.g., <rules><rule><element>BUNDLE</element><limits><limit><counter>LINE</counter><value>COVEREDRATIO</value><minimum>0.80</minimum></limit></limits></rule></rules>. In Gradle, use jacocoTestCoverageVerification with a similar rule. The build will fail if coverage drops below the threshold.
How do I exclude generated code from coverage?
In JaCoCo, you can use the excludes option in the agent configuration or the report plugin, specifying patterns like com/example/generated/*. In Maven, add <excludes><exclude>**/generated/**</exclude></excludes> to the plugin configuration.
Is there a difference between unit test coverage and integration test coverage?
Yes. Unit tests typically execute a single class in isolation, while integration tests may start the full application. Coverage tools can merge data from both, but you should look at them separately to see which parts of the code are only covered by integration tests. JaCoCo can generate separate reports for different test tasks.
Related
Formula used
in t | Total lines of code | lines | 1000 | 0 in d | Lines covered by tests | lines | 750 | 0 out coverage | Line coverage | % | (d / t) * 100 | 1
Each line is one input (in, sel, list) or one result (out: label, unit, formula, decimals). How the calculators work
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.