All jobs

Add JaCoCo Code Coverage to a Maven Project

Yes. An agent adds jacoco-maven-plugin to your pom.xml with prepare-agent, report and a coverage check, runs ./mvnw verify, and opens a PR with the measured numbers.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the build before adding a plugin to it. In a project like the complete module of spring-guides/gs-rest-service, pom.xml inherits from spring-boot-starter-parent 4.0.8 with java.version 17, depends on spring-boot-starter-webmvc and spring-boot-starter-webmvc-test, and declares only spring-boot-maven-plugin. The Maven wrapper in .mvn/wrapper/maven-wrapper.properties pins Maven 3.9.16. The one test class, GreetingControllerTests, is a @SpringBootTest with RestTestClient and two test methods against /greeting. The same directory also carries build.gradle, which the agent leaves alone, and .github/workflows/continuous-integration-build.yml runs ./mvnw --batch-mode clean package on Temurin 17 with the Maven cache. .gitignore already lists target.

The plugin goes into <build><plugins> as org.jacoco:jacoco-maven-plugin at 0.8.16, the current release, which supports Java 27 class files and so has room above the project's 17. Three executions do the work: prepare-agent, which sets the argLine property that Surefire passes to the forked JVM; report, bound to the test phase so target/site/jacoco/ with index.html, jacoco.xml and jacoco.csv appears on every test run; and check, bound to verify, with one BUNDLE rule on LINE COVEREDRATIO. Because the Spring Boot parent does not manage JaCoCo's version, the agent pins it explicitly, and because the parent sets no argLine of its own, no @{argLine} merge is needed; if a project's pom.xml does set one, the agent rewrites it to include the placeholder so the agent is not silently dropped.

The threshold is measured, not guessed. The agent runs ./mvnw --batch-mode verify once with the rule off, reads the ratio from jacoco.csv, and sets the minimum just under it so the check passes today and fails on the next pull request that lowers coverage. The pull request shows the per-class lines from the CSV so a reviewer sees where the uncovered code is: in this project, RestServiceApplication.main is the line the two tests never reach, which is a candidate for an <exclude> rather than a reason to lower the bar.

The workflow needs one real change: it runs ./mvnw --batch-mode clean package, and package comes before verify in Maven's lifecycle, so the check goal would never run there. The agent changes that step to clean verify for the module and adds actions/upload-artifact with target/site/jacoco/ after it, so the HTML report is downloadable from each run. It runs ./mvnw --batch-mode verify a second time with the rule on to confirm the build is green, and leaves the Gradle build, initial/ and the Kotlin modules untouched.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add JaCoCo code coverage to this Maven project. Read pom.xml, .mvn/wrapper/maven-wrapper.properties, every class under src/test, .github/workflows and .gitignore first. Add org.jacoco:jacoco-maven-plugin at its current release under build plugins with three executions: prepare-agent, report bound to the test phase, and check bound to verify with one BUNDLE rule on LINE COVEREDRATIO. If pom.xml already sets argLine for Surefire, include the @{argLine} placeholder so the agent is kept. Run ./mvnw --batch-mode verify with the rule disabled, read target/site/jacoco/jacoco.csv, set the minimum just under the measured ratio, run verify again with the rule on, and confirm it passes. In the existing workflow change the module's Maven step from package to verify so the check runs in CI, and add an upload-artifact step for target/site/jacoco. Do not change the Gradle build. Open a pull request that lists the plugin version, the executions, the measured ratio, the per-class lines from the CSV and the threshold you set.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that changes pom.xml and the CI workflow and nothing else. The description names the JaCoCo version and the three executions, pastes the bundle ratio and the per-class rows from jacoco.csv as the run produced them, states the threshold the check now enforces, and lists the classes with uncovered lines so the next decision, exclude or test, is in front of the reviewer.

The run's record keeps both ./mvnw --batch-mode verify runs, the first that measured and the second that enforced, so a reviewer can see the Surefire output with the agent attached and the check goal passing.

Before merging, a reviewer decides whether the application's main method should be excluded from the bundle, whether the threshold should ratchet up over time, and whether the HTML artifact should be posted to pull requests as a comment, which is a follow-up with a third-party action.

Run it on every new repository

A platform team that wants coverage on every Maven service can run this once per repository from its own server: one POST /o/{org}/sessions per repository, each with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second pull request.

After that, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "run ./mvnw --batch-mode verify; if the JaCoCo check fails, list the classes whose coverage dropped in a comment on this pull request and do not change the threshold" turns the check into a review note. The trigger puts the pull request after the prompt; only pushes by an owner, member or collaborator fire it, never a fork's.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The two ways this change goes wrong are a coverage threshold picked from the air and an argLine that silently drops the agent so every class reports zero. The agent runs the build twice in a sandbox with an empty local repository, once to measure and once to enforce, and reads the CSV rather than the console summary, so the threshold in the pull request is the one the project meets today.

Both Maven runs stay with the record, so the pull request can show the Surefire lines with the agent attached and the check goal passing instead of asking a reviewer to run verify and open the HTML report themselves.

Frequently asked questions

Why pin the JaCoCo version?

Because spring-boot-starter-parent manages many plugin versions but not JaCoCo's. Without a version Maven warns and picks whatever resolves, and class-file support depends on the release: 0.8.16 supports up to Java 27, so a project on 17 has headroom.

Will the check break the build straight away?

No. The threshold is set just under the ratio the agent measured on the branch, so the first verify passes. It fails only when a later change lowers line coverage below that figure, which is the point.

Does this touch the Gradle build in the same directory?

No. The guide repository carries both builds, and the prompt limits the agent to Maven. Adding the jacoco Gradle plugin is a separate, smaller change the pull request mentions.

Where does the report end up?

Under target/site/jacoco/ after every test run: index.html to browse, jacoco.xml for tools that read it, jacoco.csv for the numbers. target is already ignored by git, and the workflow uploads the directory as a run artifact.

More Maven jobs

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading