Skip to content
Tutorials Center
My learning

Topics

Lesson 45 of 66 ยท Testing

Code Coverage with JaCoCo

Measure test coverage in a Spring Boot project with JaCoCo: Maven and Gradle setup, line versus branch coverage, reading the report, thresholds, exclusions and a CI gate.

Tests tell you that something works. Code coverage tells you which code your tests never ran. That is a narrower statement than it sounds, and understanding the difference is what makes coverage numbers useful instead of misleading. JaCoCo (Java Code Coverage) is the standard tool for it: it measures what the JVM executes while your tests run and produces an HTML report, an XML file for CI tools and a CSV summary.

This lesson shows how to add JaCoCo to a Maven or Gradle Spring Boot project, how to read line and branch coverage, how to set a threshold that fails the build, how to exclude code that should not count, and how to avoid the traps of chasing a number. The build snippets are read-only (no build tool runs on this site); the two runnable examples are plain Java stand-ins that rebuild the counting logic.

How JaCoCo works

JaCoCo attaches a Java agent to the JVM that runs your tests. The agent instruments classes as they load, inserting tiny probes. When a test executes a line or takes a branch, a probe is set. At the end, JaCoCo writes an execution file (jacoco.exec) and a report step combines it with your compiled classes to compute coverage.

You need no changes to your code or your tests. You only add the plugin to the build.

Maven setup

XML
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>${jacoco.version}</version>   <!-- use a release that supports your Java version -->
    <executions>
        <execution>
            <id>prepare-agent</id>
            <goals><goal>prepare-agent</goal></goals>
        </execution>
        <execution>
            <id>report</id>
            <phase>verify</phase>
            <goals><goal>report</goal></goals>
        </execution>
    </executions>
</plugin>

prepare-agent sets the JVM argument for the test run (Surefire picks it up). report runs in the verify phase and writes target/site/jacoco/index.html. Run it with:

Terminal
./mvnw verify

Integration tests run by Failsafe need a second prepare-agent-integration goal if you want them counted.

Gradle setup

GROOVY
plugins {
    id 'java'
    id 'jacoco'
}

jacoco {
    toolVersion = "0.8.14"      // pick a version that supports your Java release
}

test {
    finalizedBy jacocoTestReport          // always produce a report after the tests
}

jacocoTestReport {
    dependsOn test
    reports {
        html.required = true
        xml.required  = true              // CI tools such as SonarQube read the XML
    }
}

Run ./gradlew test jacocoTestReport; the HTML lands in build/reports/jacoco/test/html.

Reading the report

The HTML report lists packages, classes and methods with coverage bars. Open a class and you see its source with colors: green lines were executed, red lines never ran, and yellow lines are partly covered (some branches taken, some not). JaCoCo tracks several counters:

Counter What it counts
Instruction Bytecode instructions executed; the most precise measure
Line Source lines with at least one executed instruction
Branch The outcomes of if, switch and loops (each decision has at least two)
Method / Class Methods and classes entered at least once
Cyclomatic complexity A guide to how many tests a method needs

The two you will quote most are line and branch coverage, and they can disagree sharply.

Line coverage versus branch coverage

A line counts as covered when it runs at all. A branch counts as covered only when each outcome of the decision ran. The following stand-in makes that visible: it instruments a small method by hand (the probes that JaCoCo inserts for you) and reports both numbers. One test runs only the "no discount" path, then a second test adds the other outcomes.

Java 100% line coverage, 50% branch coverage

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

After the first test every line has run, so line coverage is 100%, yet only half of the decisions were ever exercised: the code never saw a bulk order or a member. A bug inside either if would be invisible. This is why branch coverage is the more honest number, and why a green line-coverage badge alone proves little.

Enforcing a threshold

You can make the build fail when coverage drops. In Maven, add a check execution with rules:

XML
<execution>
    <id>check</id>
    <phase>verify</phase>
    <goals><goal>check</goal></goals>
    <configuration>
        <rules>
            <rule>
                <element>BUNDLE</element>
                <limits>
                    <limit>
                        <counter>LINE</counter>
                        <value>COVEREDRATIO</value>
                        <minimum>0.80</minimum>
                    </limit>
                    <limit>
                        <counter>BRANCH</counter>
                        <value>COVEREDRATIO</value>
                        <minimum>0.70</minimum>
                    </limit>
                </limits>
            </rule>
        </rules>
    </configuration>
</execution>

BUNDLE means the whole module; other elements are PACKAGE, CLASS and METHOD. In Gradle the equivalent is a verification task:

GROOVY
jacocoTestCoverageVerification {
    violationRules {
        rule {
            limit { counter = 'LINE';   minimum = 0.80 }
            limit { counter = 'BRANCH'; minimum = 0.70 }
        }
    }
}
check.dependsOn jacocoTestCoverageVerification

Excluding what should not count

Some code adds noise to the number without adding value: the main class, configuration classes that only declare beans, generated code (MapStruct implementations, Lombok output) and plain DTOs. Exclude them by class pattern:

XML
<configuration>
    <excludes>
        <exclude>**/*Application.class</exclude>
        <exclude>**/config/**</exclude>
        <exclude>**/dto/**</exclude>
        <exclude>**/*MapperImpl.class</exclude>
    </excludes>
</configuration>
GROOVY
jacocoTestReport {
    afterEvaluate {
        classDirectories.setFrom(files(classDirectories.files.collect {
            fileTree(dir: it, exclude: ['**/*Application.class', '**/config/**', '**/dto/**'])
        }))
    }
}

Lombok can also be told to mark generated code with lombok.addLombokGeneratedAnnotation = true in lombok.config; JaCoCo then ignores it automatically. Keep exclusions short and justified. A long exclusion list is a sign someone is gaming the number.

A CI gate in miniature

The report step also writes a CSV (jacoco.csv) with one row per class. The stand-in below reads such a file, applies exclusions and a threshold, and exits with a failure like the check goal does. The CSV columns are the real ones; the "build" is simulated.

Java A coverage gate over a JaCoCo-style CSV

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice what changed the outcome: BookController is weakly tested and pulls the average down. Without the exclusions, the untested configuration and generated mapper would have dragged it far lower for reasons nobody should fix.

Using coverage well

  • Coverage finds untested code; it does not prove tested code is correct. A test with no assertions gives full coverage and zero safety. Pair the number with good assertions (Testing Fundamentals).
  • Treat a threshold as a floor, not a goal. 70% to 85% is a common, healthy range. Chasing 100% leads to tests of getters and constructors that find no bugs.
  • Look at branches and at the red lines, especially in services with business rules and in error handling.
  • Aim at the right layer. Fast unit tests and test slices give most of the coverage cheaply; Testcontainers tests cover wiring and queries.
  • Watch the trend on pull requests. "This change lowered coverage of a file by 20 points" is a useful review signal. Tools such as SonarQube or Codecov read the JaCoCo XML for that.
  • Mutation testing (for example PIT) goes a step further by changing your code and checking that a test fails, which measures test quality rather than just execution.

For running the gate on every push, see the pipeline sketch in Deploying Spring Boot: the verify step is where jacoco:check belongs.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does JaCoCo measure?

    It records execution with a Java agent. It says nothing about whether the executed code was checked properly.
  2. 2. A method has one if statement. A test runs only the case where the condition is true. Which is true?

    Every line may run while only one of the two outcomes of the decision was exercised.
  3. 3. Which Maven goal makes the build fail when coverage is too low?

    The check goal evaluates the configured rules, such as a minimum covered ratio for LINE or BRANCH, and fails the build on a violation.
  4. 4. Which code is a reasonable candidate for exclusion?

    Generated code and trivial bootstrap classes add noise. Keep the exclusion list short and justified.
  5. 5. Why is a 100% coverage target a poor goal?

    Coverage is a diagnostic. Using it as the goal rewards executing code, not verifying behavior.

Summary

  • JaCoCo attaches an agent to the test JVM and reports which lines, branches and methods ran; add it as a Maven or Gradle plugin, with no code changes.
  • Branch coverage is stricter than line coverage: a line can run while half of its decisions never did.
  • Enforce a minimum with the Maven check goal or Gradle jacocoTestCoverageVerification, and make it part of the CI build.
  • Exclude generated code, configuration and the application class, and keep the list short.
  • Coverage shows what is untested, not what is correct; use it as a floor and combine it with real assertions.

Next: Actuator: Health, Metrics and Info.