| name | java-coverage |
| description | Generate a JaCoCo code coverage report via `mvn clean jacoco:prepare-agent test jacoco:report`, scoped to the test selector given (same selector syntax as the `java-test` skill), then read the generated `target/site/jacoco/jacoco.csv` to report the exact line-coverage percentage for the specific class(es) touched — falling back to the per-class `target/site/jacoco/**/<ClassName>.html` report to show which lines/branches are still uncovered. Invoke as `/java-coverage <selector> [TargetClass1,TargetClass2,...]`, or `/java-coverage` with no argument to run the full suite and report whole-project coverage. Use whenever the user wants to check, or verify a coverage bar (e.g. "at least 80% line coverage") for a class or set of classes, instead of eyeballing Surefire output. |
Java Coverage
Run JaCoCo against a scoped (or full) test run and report the exact, measured coverage percentage for the
class(es) the user cares about. This skill only measures and reports coverage — it does not add tests or modify
source/test code unless asked to as a follow-up.
Step 1 — Determine the test scope
If the user gave a selector, it uses the exact same syntax as the java-test skill's Step 1 table (class,
class+method, comma list, wildcard, package pattern, tag expression). If no selector was given, run the whole
suite.
Important: JaCoCo only records coverage for code actually exercised by the tests that ran in this invocation. If
a class under test is covered by tests spread across multiple test classes, the selector must include all of
them (comma-separated) — scoping to just one of them will undercount that class's real coverage. When in doubt
about whether a selector covers everything relevant to the target class, prefer a broader selector (e.g. the
whole package, or the full suite) over a narrow one.
Step 2 — Determine the target class(es) to report on
- If the user (or the calling skill) explicitly named target class(es), use those.
- Otherwise, infer them from the test selector by convention: a test class
FooTest targets Foo,
FooTest#methodName still targets Foo. For a comma list of test classes, infer one target class per test
class.
- If the selector is a wildcard, package pattern, or tag expression, target classes can't be inferred by name —
report on every class touched by that run (Step 4 already surfaces all of them), or ask the user which class(es)
they care about if the run touches many unrelated ones.
Step 3 — Run the coverage build
mvn clean jacoco:prepare-agent test jacoco:report -Dtest=<selector>
Omit -Dtest=<selector> entirely to run the full suite. Do not add profile flags —
they only affect the package-phase source/javadoc jar attachment, which this command never reaches, so they
have no effect on the test run or the coverage report and just add noise.
This regenerates target/site/jacoco/ from scratch each time (the clean goal wipes the previous jacoco.exec
and report), so there's no risk of reading a stale report from an earlier run.
If the build fails (compilation error or test failure), report that failure — don't attempt to read a coverage
report that wasn't (re)generated.
Step 4 — Read the exact coverage from jacoco.csv
Read target/site/jacoco/jacoco.csv. Its header is:
GROUP,PACKAGE,CLASS,INSTRUCTION_MISSED,INSTRUCTION_COVERED,BRANCH_MISSED,BRANCH_COVERED,LINE_MISSED,LINE_COVERED,COMPLEXITY_MISSED,COMPLEXITY_COVERED,METHOD_MISSED,METHOD_COVERED
For each target class from Step 2, find its row (match the CLASS column exactly — nested/inner classes appear
as separate rows, e.g. Outer$Inner) and compute:
line coverage % = LINE_COVERED / (LINE_COVERED + LINE_MISSED) * 100
branch coverage % = BRANCH_COVERED / (BRANCH_COVERED + BRANCH_MISSED) * 100 (n/a if both are 0, e.g. enums/records with no branches)
instruction coverage % = INSTRUCTION_COVERED / (INSTRUCTION_COVERED + INSTRUCTION_MISSED) * 100
Use the CSV, not the HTML index.html tables, as the source of truth for the percentage — the HTML package-level
table's "Cov." columns are instruction and branch coverage only; it never prints a line-coverage percentage
directly, only raw missed/total line counts, so computing from the CSV is more direct and less error-prone than
parsing HTML.
If a target class doesn't appear in the CSV at all, it means no code in that class executed during this run
(either it's dead/unreachable from the tests that ran, or the selector didn't include tests that exercise it) —
report 0%, not an error.
Step 5 — Report results
State, per target class, the line coverage percentage (and branch coverage if relevant to the discussion), computed
from actual CSV numbers — never estimate or guess. If the user's bar is "at least N%": say clearly whether each
class meets it.
For classes under the bar, point to the per-class HTML report for line-level detail on exactly what's uncovered:
target/site/jacoco/<package-with-dots>/<ClassName>.html (e.g.
target/site/jacoco/com.example.myapp/Foo.html). Read its companion .java.html file
(same name, e.g. Foo.java.html) for the actual highlighted source: each line is a
<span class="nc" id="L<n>"> (not covered), <span class="pc" id="L<n>"> (partially covered branch), or
<span class="fc" id="L<n>"> (fully covered) — grep -o 'class="nc" id="L[0-9]*"' <file> gives the exact
uncovered line numbers when the user wants to know precisely which lines/branches to target with new tests,
rather than just the aggregate percentage.
Do not add tests, modify source/test code, or re-run anything to try to raise coverage — that's a follow-up the
user (or another skill, e.g. code) drives explicitly.
