Linux hosts and targets
Linux, as a probe’s host and as a bug’s target. Everything here is X11/Wayland/GTK-specific; do not reuse these commands or environment variables on macOS or Windows.
HEADLESS
Headless GTK reads fixed look-and-feel values, not the desktop’s
(widget/docs/look-and-feel.md, “Headless”, lists them), so a color or metric
that comes from GTK cannot be reproduced here, and “what is the root font size
on this machine” has no answer. Read the desktop’s value off a non-headless run,
or from its own configuration (FONT below has the GTK setting); sweeping root
font sizes by setting documentElement.style.fontSize yourself still works
(desktop-theme-layout §1). Xvfb reads the desktop’s accent and color scheme
where headless reads fixed ones, so pin each one a result depends on and read it
back. --setpref ui.accentcolor=#rrggbb with ui.accentcolortext sets
AccentColor and AccentColorText. ui.systemUsesDarkTheme set to 0 or 1 pins
the scheme, which a theme’s colors follow too; read (prefers-color-scheme: dark) back. Pin ui.useOverlayScrollbars as well, since the default differs
between profiles (SCROLLBARS below). Headless GTK reports no compositing
(COMPOSITING below), so popup.css can force a popup’s border radius and
shadow margin to 0px; read both back, and for a popup radius or shadow reading
set --setpref ui.GtkCSDTransparencyAvailable=1. Headless Linux also lacks the
customtitlebar root attribute; to test a rule under it, read §4 “Test another
platform’s rule” in probe-recipes.md. Primary-selection
assertions fail only headless.
DISPLAYS
running-a-probe.md has the rules every display
follows. The rungs below rise in what they supply; take the cheapest one that
supplies what the measurement needs.
A virtual X server: real X11, no window manager
xvfb-run comes in the xvfb package on Debian and Ubuntu,
xorg-x11-server-Xvfb on Fedora and xorg-server-xvfb on Arch.
env -u WAYLAND_DISPLAY GDK_BACKEND=x11 MOZ_ENABLE_WAYLAND=0 xvfb-run -a -s "-screen 0 1600x1000x24" \
./mach python --virtualenv wpt .claude/skills/desktop-theme-probing/scripts/firefox-probe.py \
--binary <objdir>/dist/bin/firefox --no-headless ...
Strip the Wayland environment explicitly, as above.
xvfb-runsets onlyDISPLAY; on a Wayland sessionWAYLAND_DISPLAYsurvives and Firefox prefers it, so the window lands on the desktop while the log reads like a clean virtual-display run, and agrabstep reads an empty X root window. Gecko picks the backend fromWAYLAND_DISPLAY,DISPLAY,MOZ_ENABLE_WAYLANDandGDK_BACKEND;XDG_SESSION_TYPEdoes not change underxvfb-runand proves nothing. Before believing a run was isolated, check thatWAYLAND_DISPLAYis unset in the child’s environment.Firefox needs 24-bit depth. Size the screen to hold the window plus the browser chrome, since a coordinate step must land inside the viewport.
Wrap ./mach mochitest <path> > artifacts/probe.log 2>&1 in the same
env/xvfb-run prefix.
There is no window manager, so minimize, maximize, restore and the state events they emit fail whatever the patch does, and an open popup hides itself within about 300 ms; pass
--setpref ui.popup.disable_autohide=trueto keep it open for a reading or a grab.There is no compositing manager either, so this rung reproduces an X11 desktop without compositing, paint included (COMPOSITING below).
Xvfb’s startup failure reads
Xvfb failed to start.
Xvfb plus an X window manager: backend, window manager and seat on X11
Start an X window manager on the Xvfb display before Firefox, inside the same
xvfb-run command. Xvfb supplies a core keyboard and pointer, so size-mode
changes and focus behave as on a desktop.
A nested Wayland compositor: backend, window manager and seat on Wayland
CI’s Wayland test jobs start Xvfb, then a compositor nested inside it
(taskcluster/scripts/tester/test-linux.sh runs
mutter --display=:0 --wayland --nested and exports WAYLAND_DISPLAY), and
run Firefox against that compositor. Locally this needs a compositor that can
still run as a client of an X server; mutter 50 has dropped --nested, and
other compositors with an X11 backend (weston, wlroots-based ones such as sway
or cage) are untested here. Point Firefox at the nested compositor’s socket
(WAYLAND_DISPLAY) and confirm the window opened there rather than on the
desktop.
mutter’s headless backend: Wayland, no input seat
mutter --headless gives a real compositor with a window manager, but its
wl_seat advertises no capabilities, so the browser never takes keyboard focus
and a focus-waiting harness hangs before its first assertion. When neither
nested rung is available, a Wayland-specific failure leaves the user’s session
or a try run.
FONT
Gecko takes the chrome font from GTK’s gtk-font-name setting, which differs by
desktop (GNOME defaults to 11pt, KDE to 10pt), which puts chrome’s root at
roughly 14–15px on GNOME and about 13.3px on KDE. Read the value Gecko sees with
/usr/bin/python3 -c 'import gi; gi.require_version("Gtk", "3.0"); from gi.repository import Gtk; print(Gtk.Settings.get_default().props.gtk_font_name)' in the user’s session,
not gsettings.
SCROLLBARS
GTK defaults to overlay scrollbars
(widget.gtk.overlay-scrollbars.enabled), headless included, and the test
profiles turn that pref off, so a probe and a mochitest differ unless ui.useOverlayScrollbars (1 overlay, 0 classic, at launch) forces
either.
CONTRAST
With ui.useAccessibilityTheme=1 and browser.display.document_color_use=0,
chrome reports forced-colors: false and prefers-contrast true/more,
while the in-page copy enters forced colors. To put chrome under forced colors,
use the override in desktop-theme-colors
§2 “Simulate the other realm’s regime”.
Under Xvfb with the real GTK backend (DISPLAYS above), system colors come from
the stock GTK theme even with ui.useAccessibilityTheme=1: Adwaita gives
CanvasText and MenuText rgb(61, 61, 61), Canvas rgb(250, 250, 250) and
FieldText black, where headless reads CanvasText black on a white Canvas
(HEADLESS above). A prefers-contrast value built on CanvasText therefore looks
lower-contrast in an Xvfb grab than headless. GTK_THEME=HighContrast (or
HighContrastInverse) under Xvfb does not make Firefox report
prefers-contrast, so it cannot simulate a high-contrast GTK session (measured
2026-10-21).
COMPOSITING
(-moz-gtk-csd-transparency-available) is true only on a display with a
compositing manager: a Wayland session or a compositing X11 desktop (e.g. GNOME,
KDE) reads true, headless Linux and Xvfb read false. Chrome keys popup and
window shadow margins, rounded corners and transparent backgrounds on it.
Without compositing a pixel a popup window leaves transparent paints black.
ui.GtkCSDTransparencyAvailable (int, 0 or 1, at launch) forces either side;
read the media query back in each cell, and take the paint from a grab on a
virtual X server (DISPLAYS above), since a headless run has no paint to grab.
PATHS
The binary is <objdir>/dist/bin/firefox, and the system temp directory is
/tmp. A plain jar.mn entry (e.g. CSS, JS, .mjs) is a symlink into the source
tree (§2 “What is live at the next launch” in
build-freshness.md).
GRABS
A grab takes the X root window of a private Xvfb display, and its coordinates
match the screen’s. A grab step refuses any other X server (the PID in
/tmp/.X<n>-lock names it), since that is usually the live desktop, unless
--grab-any-display is given for another isolated server.
Before reading a grab, read §2 “The compositor’s output” in
measuring-pixels.md.