Intro to JaCoCo

In the world of software development, ensuring the quality of your code is of utmost importance. One crucial aspect of code quality is code coverage, which measures the extent to which your source code has been tested. JaCoCo (Java Code Coverage) is a popular open - source code coverage library for Java applications. It provides detailed insights into which parts of your code are being exercised by your tests, helping you identify areas that need more testing. In this blog post, we will explore JaCoCo in detail, including its installation, configuration, and usage.

Table of Contents#

  1. What is JaCoCo?
  2. Why is Code Coverage Important?
  3. Installation and Configuration
    • Maven
    • Gradle
  4. How JaCoCo Works
  5. Example Usage
    • Writing Tests with JaCoCo
    • Generating Reports
  6. Common Practices and Best Practices
  7. Limitations of JaCoCo
  8. Conclusion
  9. References

What is JaCoCo?#

JaCoCo is a free Java code coverage library that can be used to measure the coverage of your Java code by unit tests. It can be integrated with various build tools such as Maven and Gradle, and it can generate detailed reports in different formats like HTML, XML, and CSV. JaCoCo works by instrumenting your Java bytecode during the build process. This means that it adds additional code to your classes to track which lines of code are executed during the test run.

Why is Code Coverage Important?#

Code coverage is an important metric in software development for several reasons:

  • Identifying Untested Code: It helps you find parts of your code that are not being exercised by your tests. This is crucial because untested code is more likely to contain bugs.
  • Measuring Test Effectiveness: A high code coverage percentage indicates that your tests are covering a large portion of your code. However, it's important to note that high code coverage does not necessarily mean that your tests are comprehensive.
  • Quality Assurance: Code coverage can be used as a quality metric to ensure that your codebase is well - tested before it is released.

Installation and Configuration#

Maven#

To use JaCoCo with Maven, you need to add the JaCoCo plugin to your pom.xml file. Here is an example configuration:

<build>
    <plugins>
        <plugin>
            <groupId>org.jacoco</groupId>
            <artifactId>jacoco-maven-plugin</artifactId>
            <version>0.8.7</version>
            <executions>
                <execution>
                    <id>prepare-agent</id>
                    <goals>
                        <goal>prepare-agent</goal>
                    </goals>
                </execution>
                <execution>
                    <id>report</id>
                    <phase>test</phase>
                    <goals>
                        <goal>report</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

In this configuration, the prepare - agent goal instruments the classes for code coverage, and the report goal generates the code coverage report.

Gradle#

For Gradle projects, you can add the JaCoCo plugin to your build.gradle file:

plugins {
    id 'jacoco'
}
 
jacoco {
    toolVersion = "0.8.7"
}
 
test {
    jacoco {
        includeNoLocationClasses = true
    }
}
 
task jacocoTestReport(type: JacocoReport, dependsOn: 'test') {
    reports {
        xml.enabled = true
        html.enabled = true
    }
    sourceDirectories.from(sourceSets.main.allSource.srcDirs)
    classDirectories.from(sourceSets.main.output)
    executionData.setFrom(fileTree(dir: buildDir, includes: [
            'jacoco/test.exec'
    ]))
}

This configuration enables JaCoCo in your Gradle project and generates both XML and HTML reports.

How JaCoCo Works#

JaCoCo works in two main phases: instrumentation and reporting.

  • Instrumentation: During the build process, JaCoCo modifies the Java bytecode of your classes. It adds additional code to track which lines of code are executed. This instrumentation is done before the tests are run.
  • Reporting: After the tests are run, JaCoCo collects the execution data and generates a report. The report shows which lines of code were executed, which were missed, and the overall code coverage percentage.

Example Usage#

Writing Tests with JaCoCo#

Let's assume we have a simple Java class:

public class Calculator {
    public int add(int a, int b) {
        return a + b;
    }
}

And a JUnit test for this class:

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
 
public class CalculatorTest {
    @Test
    public void testAdd() {
        Calculator calculator = new Calculator();
        int result = calculator.add(2, 3);
        assertEquals(5, result);
    }
}

When you run the tests with JaCoCo enabled, it will track which lines of the Calculator class are executed during the test run.

Generating Reports#

Maven#

To generate the JaCoCo report in a Maven project, you can run the following command:

mvn clean test jacoco:report

This will generate an HTML report in the target/site/jacoco directory.

Gradle#

In a Gradle project, you can generate the report by running:

./gradlew jacocoTestReport

The HTML report will be available in the build/reports/jacoco/jacocoTestReport/html directory.

Common Practices and Best Practices#

  • Set Coverage Goals: Decide on a minimum code coverage percentage for your project. For example, you might aim for 80% coverage.
  • Regularly Check Coverage: Make code coverage checks a part of your continuous integration (CI) pipeline. This ensures that new code changes do not decrease the overall code coverage.
  • Use Coverage Reports for Refactoring: Analyze the coverage reports to identify areas of your code that are difficult to test. This can help you refactor your code to make it more testable.

Limitations of JaCoCo#

  • Not a Measure of Test Quality: High code coverage does not necessarily mean that your tests are comprehensive. A test can cover a large portion of the code but still miss important edge cases.
  • Instrumentation Overhead: The instrumentation process can add some overhead to the test execution time, especially for large projects.

Conclusion#

JaCoCo is a powerful tool for measuring code coverage in Java applications. It provides detailed insights into which parts of your code are being tested, helping you improve the quality of your code. By integrating JaCoCo into your build process and following best practices, you can ensure that your codebase is well - tested and more reliable.

References#

2026-07