JaCoCo Multi-Module Maven: Aggregate Coverage Across Sub-Projects

JaCoCo Multi-Module Maven: Aggregate Coverage Across Sub-Projects

In a Maven multi-module project, each module generates its own JaCoCo .exec file. To get a combined coverage report, create a dedicated coverage-report module that aggregates all exec files into a single XML/HTML report.

Key Takeaways

Each module generates a separate .exec file. JaCoCo writes target/jacoco.exec per module when the prepare-agent goal runs.

The aggregate report module depends on all other modules. Add all modules as dependencies so it has access to their class files.

jacoco:report-aggregate combines exec files from dependencies. Run it in the coverage-report module after all tests finish.

Source code directories must be configured. The aggregate goal needs to find the source files to map coverage data to lines.

SonarQube and Codecov each need the aggregate XML. Point them at the combined report file from the aggregate module.

Project Structure

my-project/
  pom.xml                        ← parent POM
  core/
    pom.xml
    src/main/java/...
    src/test/java/...
  api/
    pom.xml  
    src/main/java/...
  service/
    pom.xml
    src/main/java/...
  coverage-report/               ← new aggregate module
    pom.xml

Parent POM Configuration

<!-- parent pom.xml -->
<build>
  <plugins>
    <plugin>
      <groupId>org.jacoco</groupId>
      <artifactId>jacoco-maven-plugin</artifactId>
      <version>0.8.12</version>
      <executions>
        <!-- Instrument all modules for coverage tracking -->
        <execution>
          <id>prepare-agent</id>
          <goals>
            <goal>prepare-agent</goal>
          </goals>
        </execution>
        <!-- Generate per-module reports -->
        <execution>
          <id>report</id>
          <phase>verify</phase>
          <goals>
            <goal>report</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Coverage Aggregate Module POM

<!-- coverage-report/pom.xml -->
<project>
  <parent>
    <groupId>com.example</groupId>
    <artifactId>my-project</artifactId>
    <version>1.0.0</version>
  </parent>

  <artifactId>coverage-report</artifactId>
  <packaging>pom</packaging>
  <name>Coverage Report Aggregator</name>

  <!-- Depend on all modules to access their .exec files and class files -->
  <dependencies>
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>core</artifactId>
      <version>${project.version}</version>
    </dependency>
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>api</artifactId>
      <version>${project.version}</version>
    </dependency>
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>service</artifactId>
      <version>${project.version}</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.jacoco</groupId>
        <artifactId>jacoco-maven-plugin</artifactId>
        <version>0.8.12</version>
        <executions>
          <execution>
            <id>report-aggregate</id>
            <phase>verify</phase>
            <goals>
              <goal>report-aggregate</goal>
            </goals>
            <configuration>
              <title>Combined Coverage Report</title>
              <outputDirectory>${project.basedir}/../target/site/jacoco-aggregate</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Add coverage-report to the parent POM's modules last (after all source modules):

<!-- parent pom.xml -->
<modules>
  <module>core</module>
  <module>api</module>
  <module>service</module>
  <module>coverage-report</module>  <!-- last so it runs after others -->
</modules>

Running the Aggregate Report

# Run tests in all modules and generate the aggregate report
mvn verify

# The combined report is at:
# target/site/jacoco-aggregate/jacoco.xml (XML for CI tools)
# target/site/jacoco-aggregate/index.html (HTML for humans)

Coverage Enforcement on the Aggregate

To fail the build if combined coverage drops below a threshold:

<!-- coverage-report/pom.xml -->
<execution>
  <id>check-aggregate</id>
  <phase>verify</phase>
  <goals>
    <goal>check</goal>
  </goals>
  <configuration>
    <dataFile>${project.basedir}/../target/jacoco-aggregate.exec</dataFile>
    <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.75</minimum>
          </limit>
        </limits>
      </rule>
    </rules>
  </configuration>
</execution>

Note: The aggregate exec file must exist. Run report-aggregate before check.

Uploading to Codecov

# GitHub Actions
- name: Upload to Codecov
  uses: codecov/codecov-action@v4
  with:
    files: target/site/jacoco-aggregate/jacoco.xml
    flags: integration
    fail_ci_if_error: true

Configuring SonarQube for Multi-Module

Point SonarQube at the aggregate XML:

mvn sonar:sonar \
  -Dsonar.coverage.jacoco.xmlReportPaths=$(find . -name "jacoco.xml" -path "*/jacoco-aggregate/*")

Or in sonar-project.properties:

sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco-aggregate/jacoco.xml,\
  core/target/site/jacoco/jacoco.xml,\
  api/target/site/jacoco/jacoco.xml,\
  service/target/site/jacoco/jacoco.xml

SonarQube merges multiple report files automatically.

Excluding Generated Code from Aggregate

Exclude protobuf generated classes, Lombok, and other generated code:

<!-- coverage-report/pom.xml -->
<configuration>
  <excludes>
    <exclude>**/generated/**/*.class</exclude>
    <exclude>**/*_pb.class</exclude>
    <exclude>**/*$Builder.class</exclude>
  </excludes>
</configuration>

Verifying the Aggregate

Check the aggregate report structure:

# Verify exec file was created
ls -la target/jacoco-aggregate.exec

# View aggregate HTML report
open target/site/jacoco-aggregate/index.html

# Check XML for CI integration
grep -o 'missed="[0-9]*" covered="[0-9]*"' target/site/jacoco-aggregate/jacoco.xml | head -5

The aggregate report should show coverage for classes from all source modules combined, giving you a true project-wide coverage number rather than per-module fragments.

Start now free