Enable test coverage reporting via JaCoCo

[ntung]

Summary

The project has no test coverage reporting configured. Adding JaCoCo would enable per-module HTML reports and lay the groundwork for CI coverage tracking.

Current State

• core/pom.xml configures only maven-surefire-plugin (v2.19.1) with no coverage plugin
• Root pom.xml has no coverage plugin in <build><plugins>
• The surefire argLine is hardcoded (-Dfile.encoding=UTF-8 -ea), which prevents JaCoCo from injecting its agent via the ${argLine} property

Proposed Fix

1. Fix surefire's argLine in core/pom.xml to allow late evaluation by JaCoCo:

<!-- before -->
<argLine>-Dfile.encoding=UTF-8 -ea</argLine>

<!-- after -->
<argLine>@{argLine} -Dfile.encoding=UTF-8 -ea</argLine>

The @{argLine} form (vs ${argLine}) is required with JaCoCo ≥ 0.7.5 when both surefire and jacoco participate in the same build — it defers evaluation until after JaCoCo sets the property.

2. Add JaCoCo plugin to the root pom.xml (or core/pom.xml for core-only coverage):

<plugin>
  <groupId>org.jacoco</groupId>
  <artifactId>jacoco-maven-plugin</artifactId>
  <version>0.8.12</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>
  </executions>
</plugin>

Usage After Fix

mvn -f core/pom.xml clean verify
# Report: core/target/site/jacoco/index.html

Notes

• The core test suite runs through a Tests.java JUnit 4 suite class (configured via surefire <includes>). JaCoCo instruments at the bytecode level, so the suite class requires no changes.
• Adding JaCoCo to the root pom.xml would also enable aggregate reports across all submodules (mvn jacoco:report-aggregate).

[ntung]

CI Integration & GitHub Pages Publishing

Once issue #317 (GitHub Actions) is in place, a dedicated coverage job can generate the JaCoCo aggregate report and publish it to GitHub Pages on every push to master.

Additional job for .github/workflows/ci.yml

  coverage:
    runs-on: ubuntu-latest
    needs: build
    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 11
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: temurin
          cache: maven

      - name: Run all tests and generate aggregate coverage report
        run: mvn --batch-mode clean verify jacoco:report-aggregate

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: target/site/jacoco-aggregate

      - name: Deploy to GitHub Pages
        id: deploy
        uses: actions/deploy-pages@v4

What jacoco:report-aggregate requires

For the aggregate report to work, the root pom.xml needs a JaCoCo execution bound to the verify phase in each submodule (as proposed in this issue), plus a report-aggregate execution in the root or a dedicated aggregator module:

<execution>
  <id>report-aggregate</id>
  <phase>verify</phase>
  <goals><goal>report-aggregate</goal></goals>
</execution>

The aggregate report is written to target/site/jacoco-aggregate/index.html at the root level and will be served as the GitHub Pages site for the repository.

One-time repository setup

Enable GitHub Pages in Settings → Pages → Source: GitHub Actions before the first workflow run. No branch or folder selection is needed with the actions/deploy-pages approach.