Visual QA — GPU Backend
Each subdirectory contains one test category. Inside you will find:
README.org— what to verify and what failure looks liketest.el— loads the same scenario in GPU and vanilla Emacs for side-by-side comparison
Automated pixel-parity run (layer 1)
Every static category can be captured and diffed automatically:
QA_EMACS=/path/to/emacs runner/run-all.sh # all categories + out/report.md QA_EMACS=/path/to/emacs runner/run.sh 02-text-glyphs # one category
On macOS QA_EMACS must be the installed signed app binary
(/Applications/Emacs GPU.app/Contents/MacOS/Emacs): the Screen
Recording permission belongs to the app bundle, and macOS will ask
for it on the first run. On GNU/Linux the capture uses ImageMagick's
import on the current X display (an Xvfb also works).
Requirements: python3 with Pillow; ImageMagick on GNU/Linux.
Each category run launches the same Emacs twice (GPU on, then
EMACS_GPU_DISABLE=1), lets the scenario settle, captures the frame
from inside Emacs, and diffs both shots. The verdict gates on
blob_pct (differing pixels that survive a 3x3 erosion, i.e. real
structure), while fringe_pct reports the glyph anti-aliasing halo,
which legitimately differs between rasterizers. Thresholds per
category live in runner/categories.conf. Frames float above every
other window while capturing; expect a few seconds of pop-ups per
category.
A run writes out/<category>/ with both captures, a
result-triptych.png (vanilla | gpu | diff heatmap) and
result.json, plus a summary matrix in out/report.md. If a
category fails, look at the triptych: bright red = structural
difference, dark red = anti-aliasing fringe (ignored by the gate).
What the runner cannot judge (animations, video, interaction,
resize) stays in layer 2: the manual checklists of each category's
README.org, with 16-video being manual-only.
How to run any test
Open two terminals. In the first, run the GPU version:
emacs --no-init-file -l qa/NN-name/test.el
In the second, run the vanilla baseline (GPU disabled):
EMACS_GPU_DISABLE=1 emacs --no-init-file -l qa/NN-name/test.el
Place both windows side by side and compare. Mark items in the README.org as PASS / FAIL / SKIP.
Test categories
| Dir | What is tested |
|---|---|
| 01-render-cycle/ | Present timing, no-flash on open/switch |
| 02-text-glyphs/ | ASCII, CJK, bold/italic, colors, box-draw |
| 03-compositions/ | Combining chars, Arabic, Hebrew, BiDi |
| 04-emoji/ | Color emoji, ZWJ sequences, flags |
| 05-decorations/ | Underline (5 styles), overline, strike |
| 06-boxes-reliefs/ | Box outline, raised/sunken relief |
| 07-cursor/ | 4 cursor types + Metal animation modes |
| 08-fringe/ | Built-in bitmaps, custom bitmap, background |
| 09-images/ | PNG/JPEG/SVG/GIF, alpha, scale, slice |
| 10-scroll/ | scroll_run parity, easings, hscroll |
| 11-bars/ | mode-line, header, tab-bar, tool-bar |
| 12-windows/ | Splits, dividers, child frames |
| 13-display-props/ | Overlays, line-numbers, hl-line, margins |
| 14-major-modes/ | org-mode, dired, magit, corfu |
| 15-transitions/ | Buffer crossfade, HiDPI capture |
| 16-video/ | Inline video (macOS Metal only) |
| 17-edge-cases/ | 10k-line buffer, atlas overflow, themes |