MavenMultiModule

Maven Multi-Module Builds

Support for Maven multi-module build is a long outstanding feature request for JaCoCo. This page tries to collect all information about this feature.

Related Feature Requests

• Issue #18 Multi-report merging
• Issue #69 Multiply repot file merging with multimodule project reports aggregation
• Pull Request #97 Add aggregate-report that reports cross module code coverage for the maven plugin
• Pull Request #217 Allows the report mojo to reference binary/source files in other modules

Current Situation

The current JaCoCo Maven goals work on single modules only: Tests are executed within the module and contribute coverage only to code within the same module. Coverage reports are created for each module separately. There is no built-in support for cross-module coverage or combined reports for multiple modules.

Work-Arounds

• The JaCoCo Ant report task allows to specify arbitrary exec file, class file and source file locations. This task can be embedded with the maven-antrun-plugin.
• Use external tools for report generation like SonarQube.

Use Cases

There is a couple of use cases where code coverage needs to be determined across multiple modules:

• Creation of structured, browseable report for multiple modules.
• A report which shows the overall coverage figures (also check goals for overall coverage)
• Tests are located in a module separate from the code under test (e.g. Eclipse/Tycho). In this case the execution data is created within another module than the code under test.
• Integration tests might contribute code coverage to multiple modules.

More Aspects:

• Separate vs. combined reports for different test test levels (unit, it)
• Transitive coverage (e.g. test for A causes code coverage on B when A depends on B): this might be desirable or not

Implementation

Maven seems to have no concept to define when build artifacts of a module should be processed in a multi-module project. Every maven project passes all lifecycle phases before the next project is built. In multi-module projects this can be a problem if you want to aggregate build artifacts of subprojects after they are created.

Strategy: Aggregator

An aggregator is a Maven project that contains other Maven projects as modules. Using an aggregator module seems to be the natural solution as this directly reflects the project hierarchy. Unfortunately this strategy comes with a number of drawbacks:

• Aggregator goals are executed before its submodules, i.e., the build cannot create a combined coverage report in an aggregator as they have to be built and tested first.
• Aggregator goals cannot be bound to a lifecycle phase, as they are executed before its submodules. They can be specified manually on the command line to create a combined coverage report.
• There is very limited documentation for aggregators, some sources suggest that aggregators are deprecated and should not be used.

Strategy: Module with Dependencies

In a multi-module Maven project a separate module is defined that does not contribute actual content but creates a combined coverage report. It defines a dependency to all modules that should be included in the combined report. This strategy seems to work best with the current Maven architecture. It also has a number of drawbacks:

• This approach requires a separate module to create the coverage report. The mere purpose of that module is to create a combined coverage report. It would have access to the exec files as well as class and source files from the projects it depends on.
• The separate module cannot have any submodules from which it should consume exec or class files.

Strategy: Incremental Reporting

The coverage report is defined in an aggregator project. All its submodules contribute to the combined coverage report while they are built. The report is augmented with coverage information from all submodules “on-the-fly”. This would show correct coverage data even for partial builds, i.e., builds that failed at some point e.g. in a submodule. An incremental strategy for reporting is not easy to implement and would have a number of drawbacks:

• Most importantly, incremental reporting with the current report generation is not thread-safe. An extra mechanism to update existing HTML reports (with structural navigation) would be needed.
• An on-the-fly report generation is also expensive. It would have to manipulate existing files, and most likely increase build times.

Web Links

• Maven Doc: Guide to Working with Multiple Modules
• Maven Doc: Mojo API Spec
• StackOverflow: How do I run a Maven Plugin on all modules?

Other Maven Goals Supporting Multi-Module Reports

TODO