name	verify
description	Build, launch and drive SumatraPDF on Windows to verify a change end-to-end (GUI automation, screenshots, log capture).

Verifying SumatraPDF changes

Build & launch

Build: bun ./cmd/build.ts → out/dbg64/SumatraPDF-dll.exe (NOT SumatraPDF.exe, which is a stale static target).
If new source files were added to premake5.files.lua / premake5.lua, run bun cmd/premake.ts first to regenerate vs2022/*.vcxproj, or the build fails with stale projects / link errors.
Always launch with -for-testing (fresh instance, no session restore, doesn't touch user settings).
Capture engine/app logs: -log -log-to-file <path> (collects logf/logfa output).

Driving the GUI

Injected SendInput is dropped on this machine; post window messages instead (see project memory env-gui-automation). Reuse the checked-in helpers from a bun script:

const { launchSumatra, waitForFrame, findCanvas, sendCommand } = await import("<root>/tests/win-automation.ts");
const { captureWindowToPng, sleep, postMessage } = await import("<root>/tests/winapi.ts");
const { cmdId } = await import("<root>/tests/util.ts");

const proc = launchSumatra(["-log", "-log-to-file", logPath, pdfPath]);
const frame = await waitForFrame(proc.pid!);
await sleep(2500); // first render
const canvas = findCanvas(frame);
captureWindowToPng(canvas, "before.png"); // works on occluded windows (PrintWindow)
sendCommand(frame, cmdId("CmdSomething")); // NEVER hardcode command ids
await sleep(2000);
captureWindowToPng(canvas, "after.png");
postMessage(frame, 0x0010 /*WM_CLOSE*/, 0, 0);

Compare before/after PNGs (byte diff is a good first signal; Read the PNGs to eyeball).
Repeating an action back to the same state reproduces byte-identical captures — useful as a determinism control.
Sample PDF in-repo: ext/zlib/zlib.3.pdf. Bug repros live in C:\Users\kjk\OneDrive\!sumatra\bugs\.
Synthetic PDFs are easy to hand-generate from a bun script (compute xref offsets from string lengths) when a specific content shape is needed (e.g. metadata, hairline strokes).

Gotchas

captureWindowToPng (PrintWindow) does NOT capture the custom caption row's buttons (painted via BeginPaint directly on the frame DC) nor native scrollbars (non-client area) — those regions come out blank. Screen capture (CopyFromScreen) is also unavailable in this environment (blank desktop). To verify such drawing code, dump its output to a bitmap via a temporary harness (render into a CreateDIBSection DC, save with HBITMAPToBmpFormat
- file::WriteFile, view, then remove the harness).
out/dbg64/SumatraPDF-settings.txt exists (portable mode): the dbg build loads it even under -for-testing (which only prevents saving). Stale values there change app behavior in tests — e.g. a non-default PdfDocumentColorMode silently alters rendering. Check it when the app behaves unexpectedly at startup; it's written only by non--for-testing (manual) launches.
Unit tests: bun cmd/run-unit-tests.ts -dbg (but verification = driving the app, not tests).
PdfFilter/PdfPreview link mupdf through src/libmupdf.def; new fz_*/pdf_* calls in code they compile need exports added there.
New src/*.cpp that include mupdf headers before base/Base.h must be added to the PCH opt-out list in premake5.lua (setup_base_pch), or every symbol from those headers is "undeclared" (PCH skips everything before #include "base/Base.h").

Verifying SumatraPDF changes

Build & launch

Build: bun ./cmd/build.ts → out/dbg64/SumatraPDF-dll.exe (NOT SumatraPDF.exe, which is a stale static target).

If new source files were added to premake5.files.lua / premake5.lua, run bun cmd/premake.ts first to regenerate vs2022/*.vcxproj, or the build fails with stale projects / link errors.

Always launch with -for-testing (fresh instance, no session restore, doesn't touch user settings).

Capture engine/app logs: -log -log-to-file <path> (collects logf/logfa output).

Driving the GUI

Injected SendInput is dropped on this machine; post window messages instead (see project memory env-gui-automation). Reuse the checked-in helpers from a bun script:

const { launchSumatra, waitForFrame, findCanvas, sendCommand } = await import("<root>/tests/win-automation.ts"); const { captureWindowToPng, sleep, postMessage } = await import("<root>/tests/winapi.ts"); const { cmdId } = await import("<root>/tests/util.ts"); const proc = launchSumatra(["-log", "-log-to-file", logPath, pdfPath]); const frame = await waitForFrame(proc.pid!); await sleep(2500); // first render const canvas = findCanvas(frame); captureWindowToPng(canvas, "before.png"); // works on occluded windows (PrintWindow) sendCommand(frame, cmdId("CmdSomething")); // NEVER hardcode command ids await sleep(2000); captureWindowToPng(canvas, "after.png"); postMessage(frame, 0x0010 /*WM_CLOSE*/, 0, 0);

Compare before/after PNGs (byte diff is a good first signal; Read the PNGs to eyeball).

Repeating an action back to the same state reproduces byte-identical captures — useful as a determinism control.

Sample PDF in-repo: ext/zlib/zlib.3.pdf. Bug repros live in C:\Users\kjk\OneDrive\!sumatra\bugs\.

Synthetic PDFs are easy to hand-generate from a bun script (compute xref offsets from string lengths) when a specific content shape is needed (e.g. metadata, hairline strokes).

Gotchas

captureWindowToPng (PrintWindow) does NOT capture the custom caption row's buttons (painted via BeginPaint directly on the frame DC) nor native scrollbars (non-client area) — those regions come out blank. Screen capture (CopyFromScreen) is also unavailable in this environment (blank desktop). To verify such drawing code, dump its output to a bitmap via a temporary harness (render into a CreateDIBSection DC, save with HBITMAPToBmpFormat

file::WriteFile, view, then remove the harness).

out/dbg64/SumatraPDF-settings.txt exists (portable mode): the dbg build loads it even under -for-testing (which only prevents saving). Stale values there change app behavior in tests — e.g. a non-default PdfDocumentColorMode silently alters rendering. Check it when the app behaves unexpectedly at startup; it's written only by non--for-testing (manual) launches.

Unit tests: bun cmd/run-unit-tests.ts -dbg (but verification = driving the app, not tests).

PdfFilter/PdfPreview link mupdf through src/libmupdf.def; new fz_*/pdf_* calls in code they compile need exports added there.

New src/*.cpp that include mupdf headers before base/Base.h must be added to the PCH opt-out list in premake5.lua (setup_base_pch), or every symbol from those headers is "undeclared" (PCH skips everything before #include "base/Base.h").