Macos Window Visual QA

macOS Window Visual QA

Treat visual QA as a reproducible test, not a screenshot hunt. Produce an identified target, a valid image artifact, measurable layout evidence, and a concise verdict.

Set the inspection contract

Before capturing anything, record:

• app, window, screen, route, or component under inspection;
• exact UI state and required test data;
• viewport size in points and appearance (light or dark);
• defects or invariants to check;
• evidence output directory.

Use the user's screenshot as the baseline when one exists. Inspect it first; do not recapture the same broken state merely to obtain your own copy.

Choose one capture route

1. Source-level render — preferred. For an editable SwiftUI/AppKit project, render the real production view in a fixed-size NSHostingView attached to an NSWindow. Assert geometry in the same test and export PNG evidence. Read references/swiftui-xctest-rendering.md before implementing this route.
2. Exact live window. Use this when window chrome, toolbar integration, launch state, focus, or a non-source app matters. Resolve the window before capture with scripts/macos-window-capture.
3. Existing artifact. If the user supplied a screenshot and no post-change evidence is needed, inspect it directly with the image-viewing tool.

Do not use a full-screen screenshot as a substitute for a window-level request. Do not use browser capture for a native macOS window.

Capture an exact live window

First probe candidates without writing an image:

zsh /absolute/path/to/scripts/macos-window-capture list --owner "App Name"

Run live-window probing with WindowServer access. In Codex's restricted shell, an empty result can be a sandbox artifact; if the app process is known to exist, rerun the same probe once with the tool's sandbox escalation instead of changing capture utilities.

Require a layer-0, on-screen candidate with plausible bounds. Refine ambiguous results with --title-contains, --pid, or use the reported --window-id. Prefer --pid for development builds without a stable app bundle name. A missing title can indicate unavailable Screen Recording metadata; PID and window ID remain usable.

Then capture once:

zsh /absolute/path/to/scripts/macos-window-capture capture \
  --owner "App Name" \
  --title-contains "Document or Page" \
  --output /absolute/evidence/window.png

The wrapper supplies an isolated Swift module cache, so it also works in restricted Codex shells. The script rejects zero matches, ambiguous matches, existing output paths, blank or invalid files, implausibly small captures, and dimension mismatches. Use --window-id ID when the target has already been resolved. Run help for all options.

Enforce the retry budget

• Never rerun an unchanged failed capture command.
• Allow at most one attempt per distinct route before diagnosing the failure.
• If no candidate exists, verify app/process state and launch or navigate once. Probe again once; then stop.
• If a known process has no candidates in a restricted shell, request WindowServer access and repeat that probe once. This is a permission diagnosis, not a reason to switch tools.
• If capture fails while a valid candidate exists, treat Screen Recording permission as the likely blocker. Report it and request the required macOS permission; do not cycle through screenshot utilities.
• If the output is blank, corrupt, implausibly small, or the wrong dimensions, reject it. Fix the identified cause before another capture.
• Do not take repeated images hoping one will look right. Multiple captures are allowed only for a declared matrix such as light/dark, breakpoints, or before/after.

Inspect and measure

After the capture command succeeds:

1. Open the PNG with the image-viewing tool. A successful command alone is not visual verification.
2. Confirm app/window identity, expected state, dimensions, and appearance.
3. Check content priority, clipping, overlap, occlusion, line wrapping, scrolling, icon/text centering, contrast, and loading/error states.
4. When source is available, turn every objective defect into an assertion: frame relationships, minimum readable width/height, scroll range, insets, hit target bounds, or visibility policy.
5. Verify all specified sizes and both appearances when relevant. Do not generalize from a single viewport.

Prefer frame conversion into one coordinate space before comparing geometry. Account for flipped AppKit coordinates explicitly.

Completion gate

Do not claim the visual issue is fixed unless all are true:

• the exact production view or exact live target was captured;
• the PNG was validated and visually inspected;
• relevant geometry assertions pass;
• the required viewport/appearance matrix was checked;
• the evidence path and commands are reported;
• project-required tests and builds pass.

If any item is blocked, name the missing item and the single blocking condition. Never hide the blocker behind more screenshot attempts.