Skip to content
Skills Library
Programming · Testing

jacoco-analysis

/jacoco-analysis

Configures JaCoCo for JVM projects (Java / Kotlin / Scala / Groovy) - wires the runtime agent via `jacoco-maven-plugin` `prepare-agent`, generates per-build reports (HTML / XML / CSV) via the `report` goal, gates the build via the `check` goal with element / limit / minimum rules, parses the six native counters (instructions, branches, lines, methods, classes, cyclomatic complexity), and converts JaCoCo XML to LCOV / Cobertura when downstream tools need a different format. Use when the JVM build is Maven / Gradle and the team wants the canonical JVM coverage tool - or to convert JaCoCo output

Repository
qa ↗
Licence
MIT
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Configures JaCoCo for JVM projects (Java / Kotlin / Scala / Groovy) - wires the runtime agent via `jacoco-maven-plugin` `prepare-agent`, generates per-build reports (HTML / XML / CSV) via the `report` goal, gates the build via the `check` goal with element / limit / minimum rules, parses the six native counters (instructions, branches, lines, methods, classes, cyclomatic complexity), and converts JaCoCo XML to LCOV / Cobertura when downstream tools need a different format. Use when the JVM build is Maven / Gradle and the team wants the canonical JVM coverage tool - or to convert JaCoCo output

Original author description

Configures JaCoCo for JVM projects (Java / Kotlin / Scala / Groovy) - wires the runtime agent via `jacoco-maven-plugin` `prepare-agent`, generates per-build reports (HTML / XML / CSV) via the `report` goal, gates the build via the `check` goal with element / limit / minimum rules, parses the six native counters (instructions, branches, lines, methods, classes, cyclomatic complexity), and converts JaCoCo XML to LCOV / Cobertura when downstream tools need a different format. Use when the JVM build is Maven / Gradle and the team wants the canonical JVM coverage tool - or to convert JaCoCo output

How it works

  1. Overview
  2. When to use
  3. How to use
  4. Wire the Maven plugin
  5. Report formats
  6. Gating with the check goal
  7. Worked example
  8. Operating in CI
  9. Anti-patterns
  10. Limitations
Original SKILL.md headings · 273 lines, 1,307 words
SKILL.md preview
---
name: jacoco-analysis
description: "Configures JaCoCo for JVM projects (Java / Kotlin / Scala / Groovy) - wires the runtime agent via `jacoco-maven-plugin` `prepare-agent`, generates per-build reports (HTML / XML / CSV) via the `report` goal, gates the build via the `check` goal with element / limit / minimum rules, parses the six native counters (instructions, branches, lines, methods, classes, cyclomatic complexity), and converts JaCoCo XML to LCOV / Cobertura when downstream tools need a different format. Use when the JVM build is Maven / Gradle and the team wants the canonical JVM coverage tool - or to convert JaCoCo output for cross-language coverage aggregation."
---

# jacoco-analysis

## Overview

JaCoCo (the canonical JVM coverage tool) instruments Java bytecode
at runtime via a Java agent, then aggregates execution data into
per-class / per-method / per-line reports.

Per [jacoco-counters][counters], JaCoCo measures **six counters**:

[counters]: https://www.jacoco.org/jacoco/trunk/doc/counters.html

| Counter            | Definition                                                                                            |
|--------------------|--------------------------------------------------------------------------------------------------------|
| **Instructions** (C0) | "The smallest unit JaCoCo counts are single Java byte code instructions." |
| **Branches** (C1)     | Coverage "for all `if` and `switch` statements." |
| **Lines**             | "A source line is considered executed when at least one instruction that is assigned to this line has been executed." |
| **Methods**           | "A method is considered as executed when at least one instruction has been executed." |
| **Classes**           | "A class is considered as executed when at least one of its methods has been executed." |
| **Cyclomatic Complexity** | "v(G) = B - D + 1 (branches minus decision points plus one)" - minimum number of paths needed to cover all paths through a method. |

This skill covers Maven (the primary deployment), with the
bytecode-only key insight: **"All counters work at bytecode level,
making them available regardless of debug information presence"**
([jacoco-counters][counters]). Gradle, the XML parser, and the
cross-language conversions live in the reference file.

## When to use

- A JVM project (Java / Kotlin / Scala / Groovy) needs coverage and
  the team is on Maven or Gradle.
- A Cobertura-based pipeline is migrating to JaCoCo (typical:
  Cobertura is unmaintained for JDK 11+; JaCoCo handles modern
  bytecode).
- Cross-language aggregation needs JaCoCo XML converted to LCOV /
  Cobertura.

## How to use

1. Confirm the JVM build is Maven / Gradle (see When to use).
2. Wire the `jacoco-maven-plugin` with the three primary goals -
   `prepare-agent`, `report`, `check` (below); Gradle's equivalent
   is in [references/gradle-parsing-and-ci.md](references/gradle-parsing-and-ci.md).
3. Run `mvn verify`; read the `check` verdict and the HTML at
   `target/site/jacoco/index.html`.
4. Gate on INSTRUCTION + BRANCH ratios, then parse `jacoco.xml` for
   PR comments and convert to LCOV / Cobertura for cross-language
   aggregation - the parser, the counter-aware gating table, the
   format conversions, and the full Maven `verify` CI job are in
   [references/gradle-parsing-and-ci.md](references/gradle-parsing-and-ci.md).

## Wire the Maven plugin

Per [jacoco-maven][jmvn], the plugin defines several goals; the
three primary ones are **`prepare-agent`**, **`report`**, and
**`check`** ([jacoco-maven][jmvn]):

[jmvn]: https://www.jacoco.org/jacoco/trunk/doc/maven.html

```xml
<plugin>
  <groupId>org.jacoco</groupId>
  <artifactId>jacoco-maven-plugin</artifactId>
  <version>0.8.13</version>
  <executions>
    <execution>
      <id>prepare-agent</id>
      <goals>
        <goal>prepare-agent</goal>
      </goals>
    </execution>
    <execution>
      <id>report</id>
      <phase>verify</phase>
      <goals>
        <goal>report</goal>
      </goals>
    </execution>
    <execution>
      <id>check</id>
      <phase>verify</phase>
      <goals>
        <goal>check</goal>
      </goals>
      <configuration>
        <rules>
          <rule>
            <element>BUNDLE</element>
            <limits>
              <limit>
                <counter>INSTRUCTION</counter>
                <value>COVEREDRATIO</value>
                <minimum>0.80</minimum>
              </limit>
              <limit>
                <counter>BRANCH</counter>
                <value>COVEREDRATIO</value>
                <minimum>0.70</minimum>
              </limit>
            </limits>
          </rule>
        </rules>
      </configuration>
    </execution>
  </executions>
</plugin>
```

`prepare-agent` configures the JaCoCo runtime agent for the
forked test JVM; `report` generates HTML / XML / CSV from
`target/jacoco.exec`; `check` enforces thresholds.

Per [jacoco-maven][jmvn]: "Maven 3.0 or higher and Java 1.8 or
higher for the Maven runtime, Java 1.5 or higher for the test
executor."

## Report formats

The `report` goal emits three artifacts under `target/site/jacoco/`:

| File                | Format               | Use                                                       |
|---------------------|----------------------|-----------------------------------------------------------|
| `index.html` + assets | HTML drill-down     | Human review.                                              |
| `jacoco.xml`        | XML (with DTD)       | CI parsing; Cobertura-shape conversion.                    |
| `jacoco.csv`        | CSV per-class        | Spreadsheets; quick scripting.                              |

For Maven multi-module projects, the per-module reports go under
each module's `target/site/jacoco/`. For an aggregated report, use
the `report-aggregate` goal in a parent module.

## Gating with the `check` goal

The `check` goal accepts a list of rules; each rule scopes by
**element** (BUNDLE / PACKAGE / CLASS / SOURCEFILE / METHOD) and
constrains via **limits** with **counter / value / minimum or
maximum**:

```xml
<rules>
  <rule>
    <element>BUNDLE</element>
    <limits>
      <limit>
        <counter>INSTRUCTION</counter>
        <value>COVEREDRATIO</value>
        <minimum>0.80</minimum>
      </limit>
    </limits>
  </rule>
  <rule>
    <element>CLASS</element>
    <excludes>
      <exclude>*Test</exclude>
      <exclude>*IT</exclude>
    </excludes>
    <limits>
      <limit>
        <counter>METHOD</counter>
        <value>MISSEDCOUNT</value>
        <maximum>0</maximum>
      </limit>
    </limits>
  </rule>
</rules>
```

The two-rule pattern: a `BUNDLE` (whole-project) floor + a per-`CLASS`
strict rule for production code (excluding tests).

`value` options (per the JaCoCo Maven plugin's check-mojo docs):

| `value`             | Meaning                                |
|---------------------|----------------------------------------|
| `COVEREDRATIO`      | Hit / total (0.0 to 1.0).              |
| `MISSEDRATIO`       | Missed / total (0.0 to 1.0).           |
| `COVEREDCOUNT`      | Absolute number hit.                   |
| `MISSEDCOUNT`       | Absolute number missed.                |
| `TOTALCOUNT`        | Absolute total.                        |

`minimum` floors the value; `maximum` caps it. Counter options are
`INSTRUCTION` / `BRANCH` / `LINE` / `METHOD` / `CLASS` / `COMPLEXITY`
(per [jacoco-counters][counters]). Gate on INSTRUCTION for the
whole-repo floor and BRANCH separately, with a bounded METHOD miss:

```xml
<limit><counter>INSTRUCTION</counter><value>COVEREDRATIO</value><minimum>0.80</minimum></limit>
<limit><counter>BRANCH</counter><value>COVEREDRATIO</value><minimum>0.70</minimum></limit>
<limit><counter>METHOD</counter><value>MISSEDCOUNT</value><maximum>5</maximum></limit>
```

Whole-bundle 80% instruction; 70% branch; allow up to 5 untested
methods. The per-counter "when to gate on which" table is in
[references/gradle-parsing-and-ci.md](references/gradle-parsing-and-ci.md).

## Worked example

A Maven service wiring JaCoCo for the first time:

1. Add the plugin block above to `pom.xml` (all three executions:
   `prepare-agent`, `report`, `check`).
2. Run the build:

```bash
./mvnw -B verify
```

`prepare-agent` instruments the forked test JVM; the tests write
`target/jacoco.exec`; `report` renders `target/site/jacoco/index.html`;
`check` evaluates the rules.

If instruction coverage lands at 82% but branch coverage is 66%, the
build fails on the BRANCH rule (minimum 0.70), naming the bundle and
the missed limit. Open `target/site/jacoco/index.html`, drill into
the red (missed) branches, add the tests that exercise them, and
re-run `./mvnw -B verify` until `check` passes.

## Operating in CI

Run `./mvnw -B verify` so `check` gates the build, then upload
`target/site/jacoco/` with `if: always()` (coverage matters most on
runs that failed the gate). For a coverage SaaS or cross-language
aggregation, convert `jacoco.xml` to LCOV in the same job and upload
that. The full GitHub Actions workflow (verify, artifact upload,
`xml2lcov` conversion, SaaS upload) is in
[references/gradle-parsing-and-ci.md](references/gradle-parsing-and-ci.md).

## Anti-patterns

| Anti-pattern                                                       | Why it fails                                                              | Fix |
|--------------------------------------------------------------------|---------------------------------------------------------------------------|-----|
| Skipping `prepare-agent`                                            | Tests run without instrumentation; coverage data empty.                  | Always include `prepare-agent` (see Wire the Maven plugin). |
| Whole-project rule with `INSTRUCTION` only                          | Branch regressions invisible - line% looks fine while branch% drops.     | Separate INSTRUCTION + BRANCH rules (see Gating with the check goal). |
| `<element>BUNDLE</element>` on every rule                           | Per-class violations bury inside an aggregate that passes.               | Add a per-CLASS rule with `excludes` for tests (see Gating with the check goal). |
| Using JaCoCo report HTML as PR-comment input                        | HTML is for humans; PR comments need machine-readable.                   | Parse `jacoco.xml` (see references); generate the comment from there. |
| Running JaCoCo on test code                                          | "Coverage" of tests is meaningless and inflates aggregate.               | `excludes` for `*Test`, `*IT`, `*Spec` (see Gating with the check goal). |
| Aggregating LINE coverage when methods are short                    | Inflated; the coarse-grained measure looks fine.                          | Pair LINE with BRANCH always (see the counter-aware table in references). |
| Failing the build on COMPLEXITY without a tested floor              | Forces refactors of legitimately complex code (algorithms).               | Use COMPLEXITY as informational; gate on INSTRUCTION + BRANCH. |

## Limitations

- **Bytecode-level only.** Per [jacoco-counters][counters], all
  counters work at bytecode level - useful for source-format
  independence but means kotlinc / scalac inlining can produce
  surprising line-coverage shapes.
- **Per-method `desc=` is JVM signature.** Cross-source-language
  reports (Kotlin generates JVM methods) need the source file as
  the pivot, not the method descriptor.
- **`prepare-agent` only instruments forked test JVMs.** Surefire's
  `forkCount=0` (run-in-Maven-JVM mode) bypasses the agent; coverage
  data is empty. Use the default fork mode.
- **No PR-context awareness.** Pair with
  `coverage-diff-reporter` for
  the diff vs main.

## References

- [jacoco-counters][counters] - six counters (instructions, branches,
  lines, methods, classes, cyclomatic complexity), bytecode-level
  measurement, formula for cyclomatic complexity.
- [jacoco-maven][jmvn] - `prepare-agent` / `report` / `check`
  goals; Maven + JVM version requirements; HTML report output path.
- [references/gradle-parsing-and-ci.md](references/gradle-parsing-and-ci.md) -
  the Gradle plugin config, the `jacoco.xml` parser, the counter-aware
  gating table, JaCoCo-to-Cobertura / LCOV conversion, and the Maven
  `verify` CI job.
- `lcov-analysis` (references/cobertura.md) - sister
  parser; JaCoCo XML can convert to Cobertura XML for sibling tooling.
- `lcov-analysis` - sister parser; JaCoCo
  can convert to LCOV for cross-language aggregation.
- `coverage-diff-reporter`,
  `test-coverage-targeter` - downstream skills consuming the parsed JaCoCo output.
Files in this package (3)
  • SKILL.md 12 KB
  • .tessl-plugin/plugin.json 1 KB
  • references/gradle-parsing-and-ci.md 4 KB

Versions

The database has no other skills named jacoco-analysis.

Database snapshot: 13.11.2026 · package version 217827826223 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100jacoco
    JaCoCo Java code coverage tool USE WHEN: user mentions "JaCoCo", "Java coverage", "code coverage", asks about "coverage threshold", "jacoco-maven-plugin", "coverage report", "LINE coverage", "BRANCH coverage" DO NOT USE FOR: JavaScript/TypeScript coverage - use Vitest skill,…
  • 100lcov-analysis
    Parses both mainstream coverage interchange formats: LCOV `.info` text files (produced by gcov, llvm-cov, Coverage.py via `py2lcov`, JaCoCo via `xml2lcov`, Devel::Cover, Jest via `lcov` reporter, NYC, and most others) and Cobertura XML (coverage-04.dtd - emitted by JaCoCo,…
  • 100jvm-unit-tests
    Use whenever the task is to write, add, fix or review JVM unit tests in Java, Kotlin, Scala or Groovy: JUnit 6 (Jupiter) by default and JUnit 5 upgrades, plus Kotest, Spock, ScalaTest and TestNG. Covers parameterized tests, lifecycle hooks, Mockito, AssertJ, JaCoCo coverage and Maven or Gradle CI.
  • 100jvm-unit-tests
    JVM unit testing (Java / Kotlin / Scala / Groovy) with JUnit 5 (Jupiter) as the primary framework - annotations (`@Test` / `@ParameterizedTest` / source providers), lifecycle hooks (`@BeforeAll` / `@BeforeEach`), extension model (`@ExtendWith` + Mockito/Spring), display names,…
  • 100build-and-test
    Mapping a multi-module Gradle project before guessing a task name, building a variant, running JVM vs on-device tests, and turning a JaCoCo coverage report into the specific lines that need a test. Use when building, testing, or checking coverage for an Android/Gradle project.
  • 84audit-coverage
    Read coverage artifacts a build already wrote (lcov, Cobertura, coverage.py JSON, a Go cover profile) and report line coverage per file and function, plus CRAP per function, for a change, a path, or the tree. Runs no tests, never gates. Use when: 'coverage of this change',…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.