Skip to content

test(examples): hold the published catalogue against a fresh render - #526

Merged
DemchaAV merged 3 commits into
developfrom
test/full-preview-coverage
Aug 9, 2026
Merged

test(examples): hold the published catalogue against a fresh render#526
DemchaAV merged 3 commits into
developfrom
test/full-preview-coverage

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Why

CommittedAssetDriftTest holds a committed preview against a fresh render and fails on the
difference. It is the only thing in the build that notices when the engine starts rendering a
document differently — the showcase site regenerates its own copies at every cut, so nothing
compares those.

A third of the catalogue was outside it. Thirty-five documents sat on the guard's
UNPUBLISHED_PREVIEWS list — the cover-letter presets, most of the CV gallery, the emoji and
clip demos, two decks — rendered on every run with nothing looking at the result. For those,
the whole test suite proved one thing: that they rendered without throwing.

That is not hypothetical. Twice in the last week the guard caught a real change to DOCX
output, and the second time it was two cells of text disappearing from a shipped example. Any
of the same in the thirty-five would have reached the site in silence.

What changed

  • Thirty-two of them are committed, which is what puts them under the guard. A PDF is
    compared by its bytes with only the /ID dropped, so any movement in the content stream
    names the file that moved.
  • The unpublished list drops from thirty-five entries to three, and its Javadoc now says the
    default is published and the list is what has to earn an exception.
  • Three stay out, each with its reason. The emoji gallery on weight — it embeds a glyph
    set and renders to 3.97 MB against 1.4 MB for the thirty-two together, so committing it
    would put another copy of that in history on every re-render. The other two because their
    pixels are rasterised at render time and the runner antialiases them differently; see below.
  • examples/README.md no longer describes the committed set as a curated subset, and explains
    what committing buys.

Committed previews go from 2.24 MB to 3.6 MB.

Verification

./mvnw -B -ntp clean verify -pl :graph-compose-core,…,:graph-compose-coverage -am and
./mvnw -B -ntp test -f examples/pom.xmlBUILD SUCCESS on both, examples 73 tests, 0
failures.

That the files merely exist proves nothing, so the guard was made to bite: flipping one byte
in the middle of cover-letter-nordic-clean-v2.pdf turns the suite red naming that file, and
restoring it turns it green. (The first attempt at this probe was a no-op — a PDF's content
streams are compressed, so patching a literal operator found nothing to patch. The byte flip
is the version that proves anything.)

What the runner found

Two of the thirty-four disagreed on Linux: emoji-svg-vs-png.pdf and engine-deck.pptx.
Both are back on the list, with the reason recorded per file.

The reason is not flakiness. Both carry pixels this repository rasterises at render time, and
the same glyphs come out with different antialiasing on Windows and on the runner. That is
measured, not guessed, and it was already measured here: AssetContent's own note records
that of 104 documents five failed to match across the two machines, and says the ones its
part-level exemptions could not absorb were never committed. These were two of those five —
the information was in the repository before this branch was pushed, and connecting it to the
list would have saved the red build.

They cannot use that part-level exemption: a PDF is compared whole and has no part to name,
and the deck's difference is in content it renders rather than in a part it embeds. Widening
the comparison to absorb them would cost every other document its exactness, so they stay
unguarded and say why.

Thirty-two documents are newly guarded, taking the catalogue from 67 held to 99 of 102.

Lane: test — examples module and committed assets. No production code.

A third of the catalogue rendered on every run with nothing comparing the
result. Thirty-four documents — the cover-letter presets, most of the CV
gallery, a few feature demos — were published to the showcase site fresh at each
cut and never held against anything, so a change to the engine moved them and no
test said so. They are committed as previews now, which is what puts them under
CommittedAssetDriftTest: a PDF is compared by its bytes, and a difference names
the file that moved.

The unpublished list drops from thirty-five entries to one. The emoji gallery
stays out on weight: its embedded glyph set renders to nearly 4 MB against
1.4 MB for the other thirty-four together, and committing it would put another
copy of that in history on every deliberate re-render. Its render is unguarded
as a result, which the note says plainly rather than leaving it to look like an
oversight.

The previews are rendered at the asset version, the one the drift guard compares
at, and the examples README no longer calls the committed set a curated subset.
The runner disagreed with emoji-svg-vs-png.pdf and engine-deck.pptx. Both carry
pixels this repository rasterises at render time, and the same glyphs come out
with different antialiasing on Windows and on Linux — which AssetContent already
records: of 104 documents, five failed to match across the two machines, and the
ones its part-level exemptions could not absorb were simply never committed.
These were two of them.

They cannot use that exemption. A PDF is compared whole and has no part to name,
and the deck's difference is in content it renders rather than in a part it
embeds. Committing them fails the build on the runner for a document nobody
touched, so they go back on the list — with the reason recorded per file, so the
next reader does not repeat the experiment to learn it.

Thirty-two documents remain newly guarded.
The entry and the examples README still said thirty-four documents and one
exception, which was true of the commit before the two machine-rendered ones
went back on the list.
@DemchaAV DemchaAV changed the title test(examples): hold the whole catalogue against a fresh render test(examples): hold the published catalogue against a fresh render Aug 9, 2026
@DemchaAV
DemchaAV merged commit a03b424 into develop Aug 9, 2026
10 checks passed
@DemchaAV
DemchaAV deleted the test/full-preview-coverage branch August 9, 2026 12:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant