The Jacoco Gradle plugin integrates code coverage into modern JVM builds by generating detailed reports directly in the Gradle workflow. It hooks into test tasks, captures execution data, and produces HTML and XML outputs that help teams measure test quality and find uncovered logic.
Use this guide to understand core concepts, apply common configurations, and troubleshoot frequent issues when working with Jacoco plugin Gradle in CI and local development.
| Aspect | Description | Default in Gradle | Customization Tips |
|---|---|---|---|
| Report tasks | Tasks like jacocoTestReport aggregate execution data and source files | Generated after tests | Set dependsOn and outputs location for CI artifacts |
| Execution data | Binary files recording which instructions and branches were hit | Saved in build/jacoco | Merge multiple files for multi-project or parallel test runs |
| Source sets | Link compiled classes to corresponding source directories | Auto from Java plugin | Define custom source sets for multi-language or modular projects |
| Rules and limits | Enforce line and branch coverage gates in build logic | None | Apply upper and lower bounds to block merges on degraded coverage |
Applying and Configuring the Jacoco Gradle Plugin
Apply the Jacoco Gradle plugin in the plugins block to enable code coverage instrumentation for your JVM projects. The plugin extends test tasks so they collect execution data without extra manual setup.
Configure reports by customizing report destination, class directories, and source directories inside jacocoTestReport. This ensures generated HTML and XML outputs point at the correct artifacts and source files for review and gate checks.
Use afterEvaluate when your coverage rules must refer to test tasks that are created lazily. This pattern keeps configuration robust across multi-project builds and avoids early task dependency resolution issues.
Understanding Execution Data and Report Generation
Jacoco agent captures execution data while tests run, writing counter-based information into binary exec files. These files are lightweight and fast to produce, making them suitable for frequent local runs and high-volume CI pipelines.
The report generation phase merges exec files from single or multiple test executions, then computes coverage against class and source files. By relying on deterministic task inputs and outputs, you can cache and reuse reports intelligently in Gradle builds.
Integrating Jacoco plugin Gradle with CI pipelines is straightforward when you archive the report artifacts and use deterministic build directories. Teams can enforce coverage thresholds as part of the same build that runs tests, reducing manual review steps.
Multi-Project Builds and Cross-Task Coordination
In multi-project builds, each subproject can generate its own exec data, which you later combine in a root project report task. This approach scales coverage analysis while preserving per-module insights and ownership.
Coordinate coverage rules carefully when subprojects share libraries or common test utilities. Use aggregation strategies and source set mappings so that thresholds reflect meaningful project-level coverage instead of inflated or fragmented numbers.
Leverage Gradle configuration caching compatibility by avoiding dynamic mutation of Jacoco containers during configuration. Stable task graphs keep coverage instrumentation predictable and simplify debugging when builds behave differently across runs.
Advanced Customization and Tooling Integration
Customize class and execution data paths to align with your project layout and artifact naming conventions. Explicit source sets and report locations make it easier to integrate with IDEs, static analysis, and deployment pipelines.
Combine Jacoco plugin Gradle with other reporting plugins by chaining tasks in the lifecycle and sharing dependencies between quality checks. This ensures coverage gates sit alongside lint, dependency checks, and performance tests in a unified quality suite.
When tests run in containers or remote test environments, publish exec data back to the build agent and merge it before generating reports. This strategy preserves coverage accuracy while supporting distributed and ephemeral test infrastructures.
Optimizing Workflows with Jacoco Plugin Gradle
Use these key points to refine how coverage fits into your daily development and release processes.
- Apply the Jacoco Gradle plugin early and verify exec file generation after the first test run.
- Configure deterministic report tasks so CI artifacts remain stable and cacheable across runs.
- Set meaningful coverage rules that reflect product risk and balance enforcement with developer velocity.
- Integrate execution data merging for multi-module, containerized, and distributed test environments.
- Combine with other quality checks to create a cohesive gate that covers correctness, coverage, and maintainability.
FAQ
Reader questions
Why is my JacocoTestReport task missing classes from the main source set?
Ensure that your report task explicitly depends on the test task and references the correct source and class sets. Classes not linked to compiled outputs or matched by include rules will be omitted from coverage analysis.
How do I merge execution data from parallel test executions?
Gradle can combine exec files automatically when you configure Jacoco merges in the root project, treating distributed outputs as additional execution containers and specifying a shared destination for merged data.
Can I enforce coverage thresholds without failing the build on warnings?
Use the violationRules block to define upper and lower bounds that either log warnings or fail the build. Precise metric definitions let you block critical regressions while allowing non-breaking fluctuations during development.
How do I exclude generated or third-party code from coverage reports?
Add custom rules to the report task to filter classes by package or annotation patterns. Excluding boilerplate and generated sources keeps coverage metrics focused on production logic that developers can directly influence.