# 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`](probe-recipes.md). Primary-selection assertions fail only headless. ## DISPLAYS [`running-a-probe.md`](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 /dist/bin/firefox --no-headless ... ``` - Strip the Wayland environment explicitly, as above. `xvfb-run` sets only `DISPLAY`; on a Wayland session `WAYLAND_DISPLAY` survives and Firefox prefers it, so the window lands on the desktop while the log reads like a clean virtual-display run, and a `grab` step reads an empty X root window. Gecko picks the backend from `WAYLAND_DISPLAY`, `DISPLAY`, `MOZ_ENABLE_WAYLAND` and `GDK_BACKEND`; `XDG_SESSION_TYPE` does not change under `xvfb-run` and proves nothing. Before believing a run was isolated, check that `WAYLAND_DISPLAY` is 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 > 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=true` to 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. ## MENUS No native menus by default: context and anchored menus are Gecko popups, so their geometry and `drawSnapshot` read normally. `widget.gtk.native-context-menus` (default false) opens context menus as GTK menus instead; check it is false in a profile that reports otherwise. ## PATHS The binary is `/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`](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-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`](measuring-pixels.md).