JaCoCo

JaCoCo measures which parts of compiled Java code are exercised by a test run. Rather than analyzing source text alone, it instruments class files and inserts probes into their control flow; when execution reaches those probes, JaCoCo records coverage data for the corresponding class and method structures.¹

The usual arrangement uses the JaCoCo Java agent, which attaches to the JVM running tests and instruments classes as they are loaded. After execution, the agent writes an execution-data file, commonly with the .exec extension, that report-generation tools combine with class files and source files. This separation lets tests, compilation, and report production occur in different build phases or environments.²

JaCoCo reports instruction, branch, line, method, and class coverage, giving teams several views of what tests exercise.¹ Instruction coverage is the most granular measure because it counts executed Java bytecode instructions. Branch coverage focuses on decision outcomes, while line and method coverage are easier to read but can conceal untested paths within a line or method.

Build tools automate the lifecycle: a test task starts with the agent enabled, execution data is collected, and a reporting task transforms it into HTML, XML, or CSV. Gradle's JaCoCo plugin supports report generation and verification rules, while Maven projects commonly use the JaCoCo Maven plugin for analogous goals.⁴ Coverage thresholds can fail a build, but thresholds are policy choices rather than proof that software is correct.

Coverage is evidence of execution, not evidence that tests assert the right behavior. A test may execute every line while checking few results, missing boundary conditions, exception paths, concurrency failures, security properties, or interactions with external systems. For that reason, branch coverage and focused review often add information beyond a single overall percentage.

JaCoCo works from compiled bytecode, so compiler transformations and generated constructs can affect what appears in a report. Its reporting process applies filters for some compiler-generated code, but results can still require interpretation for features such as lambdas, records, assertions, and code generated by frameworks or language compilers.³ Exclusions should be narrow and documented: excluding difficult code can improve a metric without improving the test suite.

JaCoCo has an offline-instrumentation mode for cases where a Java agent cannot be used, including some constrained containers or specialized launchers.² Offline instrumentation changes class files before execution and requires the instrumented artifacts and runtime setup to be handled consistently, so the agent-based approach remains simpler for most builds.

Execution data identifies classes through class identifiers derived from their definitions; mismatched class files and data can therefore produce missing or misleading results.³ Multi-module builds also need deliberate aggregation so reports use the correct source and class directories. JaCoCo's core library is maintained as an independent project and is used through integrations rather than being tied to one test framework; the project publishes its source, releases, and issue history openly.⁵

Instruction coverage

The proportion of executed JVM bytecode instructions among the instructions considered by a report.

Branch coverage

The proportion of decision outcomes, such as conditional branches, that tests execute.

Execution data

Runtime probe results written by JaCoCo and later consumed to create coverage reports.

Offline instrumentation

A mode that instruments class files before the application or tests start, instead of transforming them through a Java agent at class-load time.