The unified test and coverage report
Why generateReport is a finalizer, what NotRun means, and what report.source discloses.
generateReport gathers what would otherwise be three separate verification artifacts — the Gradle
HTML report for unit tests, an XML file for integration tests, and the JaCoCo coverage report — into
one page, build/reports/forge/report.html, and one machine-readable sibling, report.json, both
under build/reports/forge/. This page explains the choices behind
that task. For what each property key and task edge does, see
Properties and Tasks.
Why the integration runner writes JUnit XML
A single <testsuite> element carrying three counts and no children would name no test, no duration
and no failure message, so a reader who learned that one test failed would have no way to learn which
one.
The runner writes one file per test class instead, in the same legacy JUnit XML shape unit tests
already produce: a <testsuite> per class holding a <testcase> per method, with the failing
case's message, exception type and stack trace attached as a child element. generateReport reads
unit and integration results through the same reader, because the two suites differ only
by directory. The format choice also pays for itself outside the report: GitHub Actions, Jenkins
and GitLab already parse JUnit XML, so an integration failure appears in a CI test reporter with no
configuration on your part. See
Integration testing for why the runner writes to disk incrementally, one
finished case at a time, rather than assembling the file at the end of the run.
Why the report is a finalizer, not a dependency
generateReport is wired as finalizedBy on check, and also on every Test, IntegrationTest
and JacocoReport task Forge or a consumer registers. A single edge from check looks sufficient
until a test fails: Gradle drops a task's finalizers whenever that task itself is skipped because
one of its own dependencies failed, and a failing test or integrationTest skips check along
with it. check.finalizedBy(generateReport) alone would therefore produce no report on exactly the
build a reader most wants to see — the one that failed.
Finalizing each verification task individually closes that gap. Whichever task actually runs and
fails still carries its own finalizer edge, so generateReport fires regardless of what happens to
check.
generateReport never fails the build itself. A missing input — no coverage report, no integration
suite, a test task that never ran — is a rendering state, not an error. The test tasks and the
coverage gate keep their existing authority over whether the build succeeds; the report only
describes what they did.
What NotRun means
Each of the three sections — unit, integration, coverage — resolves independently to one of three
states: Present, when Forge found and parsed the section's XML; Unreadable, when a file exists
but a JVM died mid-write and left it malformed; or NotRun, when the section has nothing to read at
all, such as no jacoco plugin applied or no test tagged @Tag("IntegrationTest") declared.
A section in the NotRun or Unreadable state renders the reason as text, in place of the section.
A coverage figure of zero and a coverage plugin that was never applied are different facts about a
build, and collapsing them into the same zero would hide which one occurred. Naming the reason
instead lets a reader tell "nothing ran" from "everything failed" at a glance.
Why the page is one self-contained file
report.html embeds its CSS, its JavaScript, the Geist and Geist Mono fonts, the firm's mark, and
a copy of the JSON model, all inline. Opening it triggers no network request. The design serves two
readers: an engineer debugging a build wants a page that survives a scp to another machine, and a
client receiving the report as delivery evidence wants a page that survives an email attachment
with no attachments of its own to go missing. A print stylesheet expands the tabbed layout into a
stacked document, so printing or exporting to PDF captures every section rather than only the tab
that was open.
Why the report lands in two places
generateReport writes the report to build/reports/forge/report.html and again to
build/distributions/<resource-archive-name>-report.html. The two paths serve the two readers the
section above names. Gradle prints the build/reports path, IDEs open it, and CI test reporters
scan that tree, so an engineer debugging a build finds the report where every other Gradle report
lives. build/distributions is the release set — the resource zip, the plugin zip, the archives a
project configures, and the report pair describing the build that produced them.
The delivered copy takes the resource archive name rather than the plain report.html the
canonical copy carries, because a client saves it out of the folder it shipped in. A resource named
Acme Profile at version 1.4.0 with classifier 2024x therefore ships
acme-profile-1.4.0-2024x.zip beside acme-profile-1.4.0-2024x-report.html. Both names come from
the same base name, which zipResource also uses, so the archive
and the report describing it cannot drift apart.
report.json is delivered too, as <resource-archive-name>-report.json beside the page. It is the
canonical model, byte for byte, so a machine reader of a past release finds the same data the page
renders, attached to the archives it describes.
The two HTML files differ by one footer row, which is why the delivered file is rendered rather than
copied. That row links the raw Gradle reports — the unit-test HTML, JaCoCo's HTML, and the directory
of integration XML — through paths relative to build/reports/forge, two levels under build. The
delivered file sits one level under it, so the same paths would resolve somewhere else, and its
reader holds no build directory to resolve them against in any case. Three links that cannot work
are worse than no links, so the delivered file drops the row.
Rendering twice costs nothing and risks nothing, because one assembled model feeds both renders. The timestamp a reader compares between the two files is stamped on the model, not on the render, so both describe the same build down to the second.
Publication ignores the delivered copy. Forge builds its publications from
publication-index.json, which names each artifact explicitly, rather than from a scan of the
folder, so an HTML file sitting beside the zips reaches no Maven repository.
Why every disclosure ships open
The page renders three levels of disclosure: a test suite over its cases, and, in the coverage
panel, a package over its classes, a class over its methods, and a class over its embedded source.
report.js collapses them once it runs, so the coverage panel opens as a list of packages rather
than as every method in the project, and an all-passing suite opens as a single header row.
The markup itself ships every body open, and each trigger carries data-default-collapse for the
script to act on. A viewer whose client strips scripts therefore reads the whole report, losing
search, sorting and collapsing but never content. The print stylesheet reveals collapsed bodies for
the same reason: a printed report describes the whole run.
What report.source discloses
com.mbseconsulting.forge.report.source, disabled by default, adds the uncovered source lines
themselves — with surrounding context — to the coverage section. JaCoCo's own XML already carries
package, class, method and uncovered line numbers; only the source text is absent from it, and this
flag is what adds it.
The flag governs what generateReport writes into report.html, never what a viewer sees. With
the flag off, the source directories are not read and no source line reaches the file at all — the
task declares no input from them, rather than collecting the lines and hiding them behind a
collapsed section. Source hidden in the DOM is still source in a file that later gets forwarded,
so the only safe default is to leave it out of the file entirely. With the flag on, the listing
does sit behind a collapsed disclosure under its class, which is a reading convenience and never a
gate: the file already carries the text. The overview band states the mode
as Source: excluded or Source: included, so a reader can tell which variant they hold before
passing it on.
com.mbseconsulting.forge.report.git, enabled by default, adds the branch, short commit SHA and a
dirty marker to the report header. It carries no commit subject: a subject can leak internal
context that a client-facing file has no reason to disclose, and the SHA alone already identifies
the build without describing the work behind it. Absent a .git directory or a git executable —
both ordinary for a build from an exported archive — the block disappears with no warning.
Whose copyright the report carries
The report states the consumer's ownership and never Forge's. It reuses the legal.* properties
that generateLegalFiles already stamps into the LICENSE, NOTICE and ARTIFACT-INFO shipping
inside a resource zip, so one declaration governs both the distribution and the report describing it.
A consumer that declares no legal.* property gets no legal band.
Forge's own header would be wrong here twice over. A report carries the consumer's test names, their
coverage figures and, under report.source, their source, so a notice claiming MBSE Consulting owns
it misstates the facts. Section 4.3 of that licence also grants no right to distribute Licensed
Material beyond a Group Entity or a Programme Participant, so the header would forbid the client
delivery the report exists for.
The font notice below it answers a different obligation. Geist travels inside every report, and the SIL Open Font License requires each copy of the Font Software to carry its copyright notice and licence, whoever owns the surrounding document.