Forge
Explanation

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.

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.

On this page