The repository commits a preview of part of the example catalogue, and README and the + * showcase site read those files rather than rendering anything. Nothing regenerated them, so + * they drifted quietly: a change to an example, a theme or the engine moved the render while the + * committed file stayed where it was, and the first time anybody noticed was when a release + * published it. At the point this guard was written, 23 of the 67 committed previews were behind + * the code — and the way that surfaced was a deck losing its bold weights for two releases + * without a single test going red.
+ * + *The comparison is {@link AssetContent}: exact, with the handful of differences a machine + * rather than an author writes named and dropped. So a failure here means the render moved, and + * the fix is to re-render the named files or to revert what moved them — never to widen the + * comparison.
+ * + *A committed preview is rendered at the released version while a working tree is + * already on the next one, so this compares like with like only because the examples module runs + * its tests with {@code graphcompose.examples.displayVersion} pinned to + * {@code graphcompose.examples.assetVersion} — the version the committed files were rendered at, + * recorded in {@code examples/pom.xml}. Without that the coordinate pill alone would differ and + * this would fail on every preview that carries one.
+ * + *Nothing moves that property yet, and this guard cannot notice: it compares both sides at + * whatever the property says, so a release that re-renders the showcase site at a new version + * while leaving the previews behind passes here. Closing that is the release step's job, and it + * is the reason to land it alongside rather than long after.
+ */ +class CommittedAssetDriftTest { + + private static final Path ASSETS = Path.of("..", "assets", "readme"); + private static final Path PREVIEWS = ASSETS.resolve("examples"); + + /** What counts as a document: the catalogue also writes a preview image and a data file. */ + private static final SetPublishing a preview is a decision, and this is the half of it worth writing down: the + * other half is the folder itself, and the two together have to account for the catalogue + * exactly. Without that, comparing only the files that happen to be there means deleting one + * removes it from its own guard — README would lose a figure and every test would stay + * green.
+ * + *Listing what is not published rather than what is keeps the shorter list, and + * puts the decision where it is actually made: a new example ships unpublished unless somebody + * says otherwise, and saying so is adding a file to the folder and a name off this list.
+ */ + private static final SetEverything under {@link #PREVIEWS} is a document, and two machines write one document the + * same way once the reduction is applied. These are not: each is a page rasterised to a PNG for + * README, and rasterising text is where two machines disagree — the same measurement that put + * the showcase watermark in {@link AssetContent#UNSTABLE_PARTS}, over a whole page rather than + * one band of it. Comparing them would mean a pixel budget, and a budget is a number nobody can + * defend a year later.
+ * + *So they are written down instead. The list is what this guard can say about them: a + * figure arriving here that is not on it is a file nothing checks, and it should arrive as a + * decision rather than as a commit nobody read. The same holds for a folder — {@code v1.5} is + * the figures of a released line, where re-rendering would itself be the bug, and a second + * folder wants that said out loud rather than assumed.
+ */ + private static final SetThis is what makes a deletion visible. The comparison above only reads the files that + * are there, so removing one takes it out of its own guard: README loses a figure and nothing + * goes red. Pinning the whole catalogue against the folder plus the list catches that, and + * catches its opposites too — a new example nobody decided to publish, a preview added + * without a source, a rename that lands as one of each.
+ */ + @Test + void theCatalogueIsExactlyThePublishedPreviewsPlusTheUnpublishedOnes() throws Exception { + SetListing it and keeping the regular files would step over a folder in silence, and a + * preview one level down would be in none of the sets these tests compare: not held to the + * catalogue, not published, not unpublished, not named as something that cannot be compared. + * The site reads this folder flat, so a folder inside it is a mistake worth naming rather + * than passing over.
+ */ + private static SetTwo rendered documents sharing a name would leave one standing in for the other, and + * whichever the walk reached first would decide what a committed file is compared against.
+ */ + private static MapA deck cannot be compared byte for byte. Every entry in the package carries the zip - * timestamp of the run that wrote it, so two renders of an unchanged document differ. The - * engine can pin those — both fixed backends take a {@code deterministic(...)} instant — - * but {@code buildPptx(Path)} routes through the convenience path, which resolves the - * backend from the provider and gives a caller no way to configure it. Until that seam - * exists, a gate comparing bytes would either fail forever or drop the decks.
- * - *Nor can it be compared part for part: three things about a package are decided by the - * machine rather than by the document, and all three were measured on these decks rather - * than assumed. See {@link #canonicalise(String, String, byte[])}. So the comparison is - * defined here as the sorted package parts reduced to what the document decides — every - * shape, relationship and run of text, with each freeform's path read where it lands on the - * slide and every image read pixel for pixel bar the one part {@link #UNSTABLE_RASTERS} - * names.
- * - *What this class does not do is hold a committed asset against a fresh render. A - * committed asset is rendered at the released version while a working tree renders the - * next one, so the two are different documents by construction; and a committed asset is - * not otherwise guaranteed to be level with the code that produces it. Comparing them - * needs the display version as an input and a way to refresh whatever has drifted — one - * job, belonging to the asset gate rather than to a unit test. The comparator is proven - * here so that the gate arrives with it already working.
- */ -class PptxCanonicalContentTest { - - private static final Path COMMITTED = Path.of("..", "assets", "readme", "examples"); - - @BeforeAll - static void generateEveryExample() throws Exception { - GeneratedCatalogue.generateOnce(); - } - - /** - * The decks whose preview the repository commits. - * - *Which decks those are is a decision, and this list plus {@link #UNPUBLISHED_DECKS} - * exist so that no deck can arrive without somebody making it. A subset alone is not - * enough: asserting that the curated decks are among the generated ones lets a new - * example ship a deck nobody has decided about, which is the same silence the pairing - * this replaced used to keep. Together the two lists cover the catalogue exactly, so a - * deck added, removed or renamed lands here first.
- */ - private static final SetOnly the equality is asserted. Whether the two files also differ in bytes depends - * on the clock — zip entry timestamps have two-second granularity, so two renders in - * quick succession can land on the same stamp and produce identical files, while two - * a moment apart do not. That is the reason the gate cannot hash the file, and it is - * also the reason it cannot be asserted: the property is real but intermittent, and a - * test that pins it fails on whichever machine happens to be fast.
- */ - @Test - void theSameDeckRenderedTwiceIsOneDocument() throws Exception { - Path deck = GeneratedCatalogue.ROOT.resolve("flagships").resolve("maven-banner.pptx"); - assertThat(deck).exists(); - - String firstDigest = canonicalDigest(deck); - MavenBannerPptxExample.generate(); - - assertThat(canonicalDigest(deck)) - .describedAs("the same document rendered twice must be one document") - .isEqualTo(firstDigest); - } - - /** - * The same path drawn in a different box is one shape; a path that moves is not. - * - *Dropping the box is the load-bearing half of the comparison, so it is checked in - * both directions: the three shapes below are the same freeform normalised the two ways - * two machines normalised it, and then genuinely moved. Absorbing the third as well - * would leave the guard reporting success on a deck whose artwork had shifted.
- */ - @Test - void theBoxIsAbsorbedButAMoveIsNot() { - String box = freeform("{@link #theBoxIsAbsorbedButAMoveIsNot} works on markup written here, so it would - * still pass if POI reordered an attribute and the rewrite quietly stopped matching — - * leaving a comparison that absorbs nothing and a red gate nobody can read. A deck the - * repository commits has to come out changed.
- */ - @Test - void theRewriteReachesRealMarkup() throws Exception { - String slide = part(COMMITTED.resolve("twin-output.pptx"), "ppt/slides/slide1.xml"); - - assertThat(freeformsInSlideSpace(slide)) - .describedAs("no freeform in a deck full of them was rewritten — the markup no " - + "longer looks the way the patterns expect") - .isNotEqualTo(slide); - } - - /** - * An image of the same size is not the same image. - * - *Reading a raster part by its dimensions would let a logo be swapped, a screenshot - * be replaced or a watermark be retyped without the comparison noticing, which is a - * quiet way for a gate to report that nothing changed. Only the one part measured as - * machine-dependent is read that way; the fixtures below are the same watermark from - * two machines, so they are the closest two images this repository has, and even they - * must come out different when compared as images.
- */ - @Test - void sameDimensionsButDifferentPixelsAreNotEqual() throws Exception { - BufferedImage windows = decode(WATERMARK_WINDOWS); - BufferedImage linux = decode(WATERMARK_LINUX); - assertThat(windows.getWidth()).isEqualTo(linux.getWidth()); - assertThat(windows.getHeight()).isEqualTo(linux.getHeight()); - - assertThat(canonicalise("business-report.pptx", WATERMARK_PART, fixture(WATERMARK_WINDOWS))) - .describedAs("two images of one size are not one image — and the deck this part " - + "sits in is not the one the allowlist names") - .isNotEqualTo(canonicalise("business-report.pptx", WATERMARK_PART, - fixture(WATERMARK_LINUX))); - } - - /** - * The named part absorbs the difference that was measured, and the fixtures carry it. - * - *The two files are {@code ppt/media/image1.png} of the showcase deck rendered on - * Windows and on the runner: same glyphs in the same places, different coverage along - * their edges. Pinning them here keeps the allowlist honest — if the difference ever - * stops being antialiasing the entry stops being justified, and this is where that - * shows.
- */ - @Test - void theNamedUnstableRasterAbsorbsTheMeasuredDifference() throws Exception { - byte[] windows = fixture(WATERMARK_WINDOWS); - byte[] linux = fixture(WATERMARK_LINUX); - assertThat(windows) - .describedAs("the fixtures have to be two renders, not one file twice") - .isNotEqualTo(linux); - - assertThat(canonicalise(WATERMARK_DECK, WATERMARK_PART, windows)) - .describedAs("the watermark named in the allowlist is the one difference the " - + "comparison is allowed to pass over") - .isEqualTo(canonicalise(WATERMARK_DECK, WATERMARK_PART, linux)); - } - - /** - * A part written with either line ending is one part. - * - *The normalisation this pins is the difference that failed six decks on the runner, - * and it is the one canonicalisation whose absence shows up nowhere else: every test - * here runs on one machine, where both sides carry the same line ending and the bug - * hides.
- */ - @Test - void theSamePartWithEitherLineEndingIsOnePart() throws Exception { - String declaration = ""; - byte[] unix = (declaration + "\nA misspelled deck or part would match nothing, and an entry that matches nothing - * exempts nothing — the comparison would quietly go back to reading the watermark by - * its pixels and fail on a runner for a reason the entry was added to explain.
- */ - @Test - void everyAllowlistedRasterExists() throws Exception { - for (String entry : new TreeSet<>(UNSTABLE_RASTERS)) { - String[] split = entry.split("!", 2); - assertThat(split).describedAs("%s is not deck!part", entry).hasSize(2); - for (Path deck : List.of(COMMITTED.resolve(split[0]), generatedDeck(split[0]))) { - assertThat(deck).describedAs("allowlisted deck %s is missing", split[0]).exists(); - assertThat(partNames(deck)) - .describedAs("allowlisted part %s is not in %s", split[1], deck) - .contains(split[1]); - } - } - } - - private static Path generatedDeck(String name) throws IOException { - try (var decks = Files.walk(GeneratedCatalogue.ROOT)) { - return decks.filter(path -> path.getFileName().toString().equals(name)) - .findFirst() - .orElseThrow(() -> new IllegalStateException( - "the catalogue no longer renders " + name)); - } - } - - private static SetThree differences were measured between decks written on Windows and the same - * decks written on the Linux runner, none of them a change to the document:
- * - *Naming it costs a line and buys the difference between a comparison that tolerates - * one measured artefact and one that stops reading images altogether. Anything added - * here stops being compared by content, so it wants the same measurement behind it that - * put this entry here.
- */ - private static final Set{@code getRGB} converts whatever the decoder produced into sRGB, so a part is - * compared by what it looks like rather than by how it was stored. A part that decodes - * to nothing is vector, and its bytes are its content.
- */ - private static byte[] image(byte[] content, boolean sizeOnly) throws IOException { - BufferedImage image = ImageIO.read(new ByteArrayInputStream(content)); - if (image == null) { - return content; - } - int width = image.getWidth(); - int height = image.getHeight(); - if (sizeOnly) { - return "%dx%d antialiasing not compared".formatted(width, height) - .getBytes(StandardCharsets.UTF_8); - } - ByteBuffer pixels = ByteBuffer.allocate(8 + 4 * width * height); - pixels.putInt(width).putInt(height); - for (int argb : image.getRGB(0, 0, width, height, null, 0, width)) { - pixels.putInt(argb); - } - return pixels.array(); - } - - private static final Pattern SHAPE = Pattern.compile("Two renders of an unchanged document are not the same file. A PDF carries a clock-seeded + * {@code /ID}; an OOXML package carries a zip timestamp on every entry and a creation stamp in + * its properties; POI ends each XML declaration with the platform's line separator. None of + * that is the document, and a comparison that reads it reports a change on every run.
+ * + *Everything this drops was measured on this repository's own catalogue rather than assumed, + * by rendering it on Windows and on the Linux runner at the same version: of 104 documents, 99 + * came out byte-identical under the reduction below. The five that did not are accounted for by + * {@link #UNSTABLE_PARTS} and {@link #UNSTABLE_SHAPES} or are decks the repository does not + * commit. So the comparison stays exact: no tolerance, no sampling, and every exemption names the + * one thing it covers and the two renders it covers it between — never a rule applied to + * everything of that kind.
+ */ +public final class AssetContent { + + private AssetContent() { + } + + /** + * The parts a machine is allowed to disagree about, and the renders it may disagree between. + * + *One entry, and it earns itself: the showcase deck embeds an image of a text watermark, + * and the same glyphs in the same places came out with different antialiasing coverage along + * their edges on the two machines. Averaging it away is not available — 4-pixel blocks still + * differ by 138 of 255.
+ * + *What is exempted is not the part but the pair of renders. Each value is the pixel digest + * of one machine's version of that part; those two collapse to one token, and anything else — + * a different watermark, a swapped logo, an empty image of the same size — keeps its own + * digest and fails the comparison. Adding a key here without its digests would exempt the + * part itself, which is the hole this shape exists to close.
+ */ + public static final MapTwo, and both in one deck: the box a freeform declares, and the origin its points are + * measured from, came out differently on the two machines — one icon with every point shifted + * by a constant 272 EMU across and 489 down and its extent smaller by exactly as much, so the + * path landed on the same place on the slide to the unit. Comparing all six committed decks + * shape by shape found these two and nothing else.
+ * + *Like {@link #UNSTABLE_PARTS}, the value is the digest of each machine's version, so the + * exemption is for the pair of renders rather than for the shape: change either one and it + * stops being absorbed. Every other shape in every deck is compared as it was written, + * including the box — which is not decoration, but the centre a {@code rot} turns a shape + * around and the axis a {@code flipH} mirrors it in.
+ */ + public static final MapNamed rather than matched by shape: a pattern for "any ISO instant under + * {@code docProps}" would also drop a date somebody meant, and a document whose custom + * property is a date has every right to be compared by it.
+ */ + private static final Pattern CREATION_STAMP = + Pattern.compile("(Two documents with the same digest are the same document; two with different digests + * differ in something an author wrote. The name matters — it selects the reduction, and for + * a package it also selects any {@link #UNSTABLE_PARTS} entry — so pass the name the file is + * committed under, not a temporary one.
+ * + * @param document the file to read + * @return a hex SHA-256 over the document's content + * @throws IOException if the file cannot be read + */ + public static String digestOf(Path document) throws IOException { + String name = document.getFileName().toString(); + byte[] bytes = Files.readAllBytes(document); + if (PACKAGES.stream().anyMatch(name::endsWith)) { + return digest(packageParts(name, bytes)); + } + if (name.endsWith(".pdf")) { + return digest(Map.of(name, withoutPdfId(bytes))); + } + return digest(Map.of(name, bytes)); + } + + /** The zip's parts, each reduced, with the entry order and timestamps dropped. */ + private static MapThree differences were measured between a package written on Windows and the same + * package written on the runner, none of them a change to the document: the platform's line + * separator after each XML declaration, the creation stamp in {@code docProps}, and two + * freeform shapes in one deck. The first two are dropped wherever they appear; the third is + * dropped only for those two shapes — see {@link #UNSTABLE_SHAPES}.
+ */ + static byte[] part(String document, String name, byte[] content) throws IOException { + if (name.startsWith("ppt/media/") || name.startsWith("word/media/")) { + return raster(document + "!" + name, content); + } + if (!name.endsWith(".xml") && !name.endsWith(".rels")) { + return content; + } + String text = new String(content, StandardCharsets.UTF_8).replace("\r\n", "\n"); + if (name.equals("docProps/core.xml")) { + text = CREATION_STAMP.matcher(text).replaceAll("$1$2"); + } + return knownShapesCollapsed(document + "!" + name, text) + .getBytes(StandardCharsets.UTF_8); + } + + /** + * A raster part read by its pixels, unless it is one of a pair a machine writes differently. + * + *An exempted part is not waved through: its pixels still decide, and only the two renders + * written down in {@link #UNSTABLE_PARTS} collapse onto one token. Anything else keeps the + * digest of what it actually is, so an image swapped for another of the same size differs + * from both the token and the other machine's render.
+ */ + private static byte[] raster(String key, byte[] content) throws IOException { + String pixels = pixelDigest(content); + if (pixels == null) { + return content; + } + if (UNSTABLE_PARTS.getOrDefault(key, Set.of()).contains(pixels)) { + return ("a known render of " + key).getBytes(StandardCharsets.UTF_8); + } + return pixels.getBytes(StandardCharsets.UTF_8); + } + + /** A PDF with the one thing in it that the clock writes taken out. */ + static byte[] withoutPdfId(byte[] content) { + String text = new String(content, StandardCharsets.ISO_8859_1); + return PDF_ID.matcher(text).replaceAll("/ID []").getBytes(StandardCharsets.ISO_8859_1); + } + + /** + * A digest of an image's size and pixels in one colour model, or {@code null} if it is vector. + * + *{@code getRGB} converts whatever the decoder produced into sRGB, so an image is compared + * by what it looks like rather than by how it was stored. The pixels are read a row at a time + * and folded into the digest rather than buffered: an embedded screenshot runs to megapixels, + * and holding two of those as byte arrays to compare them is a waste of a test's heap.
+ * + * @param content the bytes of the part + * @return a hex SHA-256 over the image, or {@code null} when nothing decodes it + * @throws IOException if the bytes cannot be read + */ + public static String pixelDigest(byte[] content) throws IOException { + BufferedImage image = ImageIO.read(new ByteArrayInputStream(content)); + if (image == null) { + return null; + } + int width = image.getWidth(); + int height = image.getHeight(); + ByteBuffer row = ByteBuffer.allocate(4 * width); + MessageDigest digest = sha256(); + digest.update("%dx%d".formatted(width, height).getBytes(StandardCharsets.UTF_8)); + int[] pixels = new int[width]; + for (int y = 0; y < height; y++) { + image.getRGB(0, y, width, 1, pixels, 0, width); + row.clear(); + for (int argb : pixels) { + row.putInt(argb); + } + digest.update(row.array()); + } + return HexFormat.of().formatHex(digest.digest()); + } + + private static final Pattern SHAPE = Pattern.compile("What was actually measured is two shapes in one deck, so two shapes in one deck are what + * is exempted — by the digest of each machine's version of them, the way an unstable image + * is. Every other shape is compared as it was written.
+ */ + static String knownShapesCollapsed(String part, String xml) { + if (UNSTABLE_SHAPES.keySet().stream().noneMatch(key -> key.startsWith(part + "!"))) { + return xml; + } + Matcher shapes = SHAPE.matcher(xml); + StringBuilder out = new StringBuilder(); + while (shapes.find()) { + shapes.appendReplacement(out, Matcher.quoteReplacement(collapse(part, shapes.group()))); + } + shapes.appendTail(out); + return out.toString(); + } + + private static String collapse(String part, String shape) { + Matcher name = SHAPE_NAME.matcher(shape); + if (!name.find()) { + return shape; + } + String key = part + "!" + name.group(1); + String digest = HexFormat.of().formatHex( + sha256().digest(shape.getBytes(StandardCharsets.UTF_8))); + return UNSTABLE_SHAPES.getOrDefault(key, Set.of()).contains(digest) + ? "" + : shape; + } + + private static MessageDigest sha256() { + try { + return MessageDigest.getInstance("SHA-256"); + } catch (NoSuchAlgorithmException impossible) { + throw new IllegalStateException("SHA-256 is required of every JVM", impossible); + } + } + + private static String digest(Map{@link AssetContent} is what the asset gate reads a document through, so each reduction it + * makes is checked in both directions: the difference it is meant to absorb comes out equal, and + * the change it must never absorb comes out different. A reduction that quietly stops matching — + * a reordered attribute, a mistyped part name — would leave a gate that compares nothing and + * passes everything, so the ones driven by patterns are also run against markup POI really + * wrote.
+ */ +class AssetContentTest { + + private static final Path COMMITTED = Path.of("..", "assets", "readme", "examples"); + private static final String WATERMARK_WINDOWS = "watermark-windows.png"; + private static final String WATERMARK_LINUX = "watermark-linux.png"; + private static final String WATERMARK_DECK = "master-showcase.pptx"; + private static final String WATERMARK_PART = "ppt/media/image1.png"; + private static final String TWIN_SLIDE = "twin-output.pptx!ppt/slides/slide1.xml"; + + @BeforeAll + static void generateEveryExample() throws Exception { + GeneratedCatalogue.generateOnce(); + } + + /** + * Rendering the same deck twice produces one document under this comparison. + * + *Only the equality is asserted. Whether the two files also differ in bytes depends on the + * clock — zip entry timestamps have two-second granularity, so two renders in quick + * succession can land on the same stamp and produce identical files, while two a moment apart + * do not. That is the reason the gate cannot hash the file, and it is also the reason it + * cannot be asserted: the property is real but intermittent, and a test that pins it fails on + * whichever machine happens to be fast.
+ */ + @Test + void theSameDeckRenderedTwiceIsOneDocument() throws Exception { + Path deck = GeneratedCatalogue.ROOT.resolve("flagships").resolve("maven-banner.pptx"); + assertThat(deck).exists(); + + String first = AssetContent.digestOf(deck); + MavenBannerPptxExample.generate(); + + assertThat(AssetContent.digestOf(deck)) + .describedAs("the same document rendered twice must be one document") + .isEqualTo(first); + } + + /** A PDF that differs only in the identifier the clock seeds is one document. */ + @Test + void aPdfCarryingADifferentIdentifierIsTheSameDocument() throws Exception { + Path pdf = GeneratedCatalogue.ROOT.resolve("flagships").resolve("maven-banner.pdf"); + assertThat(pdf).exists(); + byte[] rendered = Files.readAllBytes(pdf); + byte[] reseeded = new String(rendered, StandardCharsets.ISO_8859_1) + .replaceFirst("/ID \\[<[0-9A-Fa-f]+> <[0-9A-Fa-f]+>\\]", + "/ID [<" + "A".repeat(64) + "> <" + "A".repeat(64) + ">]") + .getBytes(StandardCharsets.ISO_8859_1); + + assertThat(reseeded) + .describedAs("the fixture must actually carry an /ID for this to prove anything") + .isNotEqualTo(rendered); + assertThat(AssetContent.withoutPdfId(reseeded)) + .describedAs("a fresh /ID is the clock writing, not the document") + .isEqualTo(AssetContent.withoutPdfId(rendered)); + } + + /** + * Two shapes drawn around different centres are two shapes. + * + *An earlier comparison read every freeform's path in slide coordinates and dropped the box + * those coordinates were measured against. The paths below land in the same place and turn by + * the same angle, and they are still different pictures: {@code rot} turns a shape around the + * centre of its box, so a 100-wide box and a 200-wide one spin the same line about different + * points. Nothing may collapse them.
+ */ + @Test + void rotatedFreeformsWithDifferentPivotsAreNotEqual() { + String narrow = rotatedFreeform("What was measured is two freeforms in one deck, so two freeforms in one deck are what is + * exempted. A shape reaching this with any other name — or either of these two after somebody + * changed it — comes out of the comparison exactly as it went in.
+ */ + @Test + void onlyTheNamedShapesCollapse() throws Exception { + String slide = part(COMMITTED.resolve("twin-output.pptx"), "ppt/slides/slide1.xml"); + String collapsed = AssetContent.knownShapesCollapsed(TWIN_SLIDE, slide); + + assertThat(collapsed) + .describedAs("the two measured shapes have to be recognised in the deck they were " + + "measured in, or the exemption describes nothing") + .contains("Freeform 41/>", "Freeform 51/>"); + assertThat(collapsed) + .describedAs("a shape the allowlist does not name is compared as it was written") + .contains("Reading a raster part by its dimensions would let a logo be swapped, a screenshot be + * replaced or a watermark be retyped without the comparison noticing, which is a quiet way + * for a gate to report that nothing changed. Only the parts named in + * {@link AssetContent#UNSTABLE_PARTS} are read that way; the fixtures are the same watermark + * from two machines, so they are the closest two images this repository has, and even they + * must come out different when compared as images.
+ */ + @Test + void sameDimensionsButDifferentPixelsAreNotEqual() throws Exception { + BufferedImage windows = decode(WATERMARK_WINDOWS); + BufferedImage linux = decode(WATERMARK_LINUX); + assertThat(windows.getWidth()).isEqualTo(linux.getWidth()); + assertThat(windows.getHeight()).isEqualTo(linux.getHeight()); + + assertThat(AssetContent.part("business-report.pptx", WATERMARK_PART, + fixture(WATERMARK_WINDOWS))) + .describedAs("two images of one size are not one image — and the deck this part " + + "sits in is not one the allowlist names") + .isNotEqualTo(AssetContent.part("business-report.pptx", WATERMARK_PART, + fixture(WATERMARK_LINUX))); + } + + /** + * The named part absorbs the difference that was measured, and the fixtures carry it. + * + *The two files are {@code ppt/media/image1.png} of the showcase deck rendered on Windows + * and on the runner: same glyphs in the same places, different coverage along their edges. + * Pinning them here keeps the allowlist honest — if the difference ever stops being + * antialiasing the entry stops being justified, and this is where that shows.
+ */ + @Test + void theNamedUnstablePartAbsorbsTheMeasuredDifference() throws Exception { + byte[] windows = fixture(WATERMARK_WINDOWS); + byte[] linux = fixture(WATERMARK_LINUX); + assertThat(windows) + .describedAs("the fixtures have to be two renders, not one file twice") + .isNotEqualTo(linux); + + assertThat(AssetContent.part(WATERMARK_DECK, WATERMARK_PART, windows)) + .describedAs("the watermark named in the allowlist is the one difference the " + + "comparison is allowed to pass over") + .isEqualTo(AssetContent.part(WATERMARK_DECK, WATERMARK_PART, linux)); + } + + /** + * The exemption is for two known renders, not for whatever occupies that path. + * + *Exempting the part itself would let the watermark be swapped for another image of the + * same size — a different word, a logo, a blank — and the comparison would report a deck + * unchanged. Only the two digests written down collapse; a third image keeps its own.
+ */ + @Test + void anUnknownImageOfTheSameSizeIsNotAbsorbed() throws Exception { + BufferedImage watermark = decode(WATERMARK_WINDOWS); + byte[] blank = blankPng(watermark.getWidth(), watermark.getHeight()); + assertThat(AssetContent.pixelDigest(blank)) + .describedAs("the substitute must decode, or this proves nothing") + .isNotNull(); + + assertThat(AssetContent.part(WATERMARK_DECK, WATERMARK_PART, blank)) + .describedAs("an image the allowlist has never seen is compared by its pixels, " + + "however well it matches the size of the one that is exempt") + .isNotEqualTo(AssetContent.part(WATERMARK_DECK, WATERMARK_PART, + fixture(WATERMARK_WINDOWS))); + } + + /** + * The part the allowlist exempts is still the watermark that was measured. + * + *Naming a path and pinning two digests protects nothing if the deck stopped carrying + * either of them: the entry would silently become an exemption for an image nobody has + * looked at. Both the committed deck and the one the catalogue renders have to hold a + * version the fixtures account for.
+ */ + @Test + void theAllowlistedPartInBothDecksIsAKnownRender() throws Exception { + SetThis is the reduction that failed six decks on the runner, and the one whose absence + * shows up nowhere else: every test here runs on one machine, where both sides carry the same + * line ending and the difference hides.
+ */ + @Test + void theSamePartWithEitherLineEndingIsOnePart() throws Exception { + String declaration = ""; + byte[] unix = (declaration + "\nA misspelled document or part would match nothing, and an entry that matches nothing + * exempts nothing — the comparison would quietly go back to reading the watermark by its + * pixels and fail on a runner for the reason the entry was added to explain.
+ */ + @Test + void everyAllowlistedPartExists() throws Exception { + for (String entry : new TreeSet<>(AssetContent.UNSTABLE_PARTS.keySet())) { + String[] split = entry.split("!", 2); + assertThat(split).describedAs("%s is not document!part", entry).hasSize(2); + for (Path document : List.of(COMMITTED.resolve(split[0]), generated(split[0]))) { + assertThat(document) + .describedAs("allowlisted document %s is missing", split[0]).exists(); + assertThat(partNames(document)) + .describedAs("allowlisted part %s is not in %s", split[1], document) + .contains(split[1]); + } + } + } + + private static Path generated(String name) throws IOException { + try (var files = Files.walk(GeneratedCatalogue.ROOT)) { + return files.filter(path -> path.getFileName().toString().equals(name)) + .findFirst() + .orElseThrow(() -> new IllegalStateException( + "the catalogue no longer renders " + name)); + } + } + + private static Set