:samples-dir: /home/tcagent1/agent/work/64493a816be20d5a/promote-projects/gradle/build/git-checkout/platforms/documentation/docs/build/working/samples/install/jvm-multi-project-with-code-coverage-standalone
:gradle-version: 9.2.0-rc-3

= Aggregating code coverage with JaCoCo using a standalone utility project (Incubating) Sample

[.download]
- link:zips/sample_jvm_multi_project_with_code_coverage_standalone-groovy-dsl.zip[icon:download[] Groovy DSL]
- link:zips/sample_jvm_multi_project_with_code_coverage_standalone-kotlin-dsl.zip[icon:download[] Kotlin DSL]

NOTE: You can open this sample in an link:{userManualPath}/gradle_ides.html#gradle_ides[IDE that supports Gradle].

This sample shows how to aggregate code coverage across multiple Java subprojects using link:https://www.jacoco.org/jacoco/[JaCoCo].  The link:{userManualPath}/jacoco_report_aggregation_plugin.html[jacoco-report-aggregation plugin] provides this ability via a standalone project used to specify _which_ subprojects to include for aggregation.

The project in this example contains three "code" subprojects: `application`, `list` and `utilities`.  All three projects apply the `jacoco` plugin, and `application` consumes both `list` and `utilities` via its implementation configuration.  A fourth subproject `code-coverage-report` is the standalone utility project used to collect the coverage results.

WARNING: The Test Report Aggregation plugin does not currently work with the ``com.android.application`` plugin.

====
include::sample[dir="kotlin",files="code-coverage-report/build.gradle.kts[tag=**]"]
include::sample[dir="groovy",files="code-coverage-report/build.gradle[tag=**]"]
====

The standalone project applies `jacoco-report-aggregation`, but requires additional configuration if the `jvm-test-suite` plugin is not also present.

In this scenario, two additional pieces of setup are necessary:

<1> Declare dependencies using the `jacocoAggregation` configuration
<2> Define a report of type `JacocoCoverageReport` which collects coverage data from unit test suites
<3> Optional: make JaCoCo aggregate report generation part of the 'check' lifecycle phase

The report aggregation logic does not automatically inspect all subprojects for coverage data to aggregate.  Instead, the direct and transitive link:{userManualPath}/declaring_dependencies_basics.html#sec:project-dependencies[project dependencies] of the `jacocoAggregation` configuration are selected for potential aggregation.

The user must also declare one or more reports of type `JacocoCoverageReport`.  Each report instance specifies a `testType` property, used to match the test suite producing the coverage data.  A `JacocoReport` task is synthesized for each user-defined report and performs the aggregation.  Invoking this task will cause tests to be executed in the dependent projects of the `jacocoAggregation` configuration.

Running the tests and generate the report:

[listing.terminal.sample-command]
----
$ ./gradlew testCodeCoverageReport

BUILD SUCCESSFUL
25 actionable tasks: 25 executed
----

XML and HTML reports can now be found under `code-coverage-report/build/reports/jacoco/testCodeCoverageReport`.

For more information, see link:{userManualPath}/java_testing.html[Testing in Java project chapter].
