Your tests passed; the document is still broken

Generating a package of Word documents from Markdown — Pandoc, a reference template, a rebrand find-and-replace across seven files — every automated check passed. The build script had verification built in: the old brand name appeared zero times in the rendered XML, tables carried borders, code blocks were set at a width that shouldn't wrap. Green across the board. The documents were still visibly wrong, and the only thing that caught it was turning each page into an image and looking: LibreOffice headless to PDF, pages rasterized to PNGs, every page inspected.

Dense tables are the worst offenders, because their failure modes live below the level a text check can see. Pandoc stamps a tblLook attribute on every table — flags you never chose and can't currently configure — which tells Word which parts of your template's table style to apply. Ours arrived with header-row formatting switched off, so the navy header shading and row banding the template defined never rendered; the fix was rebuilding the table style and patching firstRow back on after render. Then the theme: the reference document carried Office's newer Aptos theme fonts while its styles hardcoded Calibri, and theme attributes quietly outrank hardcoded font names — so the headings rendered in the wrong typeface. And 11-point monospace wrapped a 93-character ASCII architecture diagram into orphaned fragments; it took two rounds to land it, because 8-point was safely narrow but unreadable and 9-point fit with margin to spare.

None of that shows up in a grep. All of it shows up in a screenshot. Worse, the check script itself lied twice — a regex tripping over /> spacing reported failures that weren't there — a reminder that verification code is code.

This is the argument the visual-testing world has already had about UIs — functional tests verify logic and behavior, not the pixels the user actually sees — replayed against documents. And the counterpoint is real too: rendered-image checks are slow and environment-sensitive (font rendering alone varies machine to machine), so the structural checks stay as the fast, repeatable line of defense. But for anything with layout, "the check script passed" is necessary and not sufficient. Structural verification proves the content is present; only a rendered image proves it's readable. It took three build-render-look loops before the pages finally showed what the template promised. Render it and look before you call it done.