JaCoCo Server

Table of contents:

• What is JaCoCo?
• Why JaCoCo Server?
• Requirements
• Usage

What is JaCoCo?

JaCoCo is a free Java code coverage library. It is the de-facto standard for code coverage in Java. It provides tools to measure and report code coverage, which help developers verify that their tests are exercising the code as expected.

Why JaCoCo Server?

Integration tests are much better than unit tests for ensuring that the system works as a whole, but they normally produce no code coverage.

JaCoCo Server allows collecting code coverage emitted by Java processes while they are being tested by integration tests. The code coverage data can be used to produce code coverage reports.

Code coverage reports can be used to verify that a change has been tested, and to find gaps in testing.

Typical use cases for JaCoCo server include:

• Failures in production resulting from gaps in integration test coverage.
• Duplication of coverage by unit tests, and integration tests.
• A requirement to maintain high code coverage, which results in lots of unit tests tightly coupled to the implementation, making refactoring the implementation much more difficult.

Requirements

• The JaCoCo agent jar file (any version would do), must be bundled with the processes under test, and the command line of Java process changed to enable the JaCoCo agent.
• JaCoCo server running. Processes under test can connect to it using TCP, and users can download code coverage data.

Usage

Configuring the JaCoCo agent

Each process under test must be started with the JaCoCo agent enabled and configured to emit code coverage data to the JaCoCo server:

java -javaagent:[yourpath/]jacocoagent.jar=output=tcpclient,address=[yourhostname],sessionid=[yoursessionid] ...

Where:

• yourpath is the path to the jacoco agent jar file.
• yourhostname is the hostname for JaCoCo server.
• yoursessionid is the session id to use, must be the same for all the java processes. For example, the build ID or a random UUID generated at the start of the build.

It should only be configured when running integration tests. It can be conditionally be configured using helm, Jinga, etc.

An example pod running a process under test myapp.jar, where jacocoagent.jar is included in the container image, and the JaCoCo server running behind the hostname jacoco-server.default.svc.cluster.local:

apiVersion: v1
kind: Pod
metadata:
  name: my-java-app
spec:
  containers:
    - name: java-app
      image: my-java-app:latest
      command: ["java"]
      args:
        - "-javaagent:/app/jacocoagent.jar=output=tcpclient,address=jacoco-server.default.svc.cluster.local,sessionid=my-build-id-123"
        - "-jar"
        - "/app/myapp.jar"

Obtaining the execution data

The endpoint to obtain execution data is /session/{id} where the id is the afformentioned sessionid configured in each JaCoCo agent. It will produce a file in JaCocO exec format.

See also: How to extract readable format report from jacoco.exec?