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.xmlParent 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: trueConfiguring 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.xmlSonarQube 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 -5The 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.