Running a snippet through firefox-probe.py

Read --help for every flag, step kind and output shape, and toolkit/themes/tools/probelib.py’s docstring for the launch flags and exit codes; this file holds what they do not say.

1. Flags and output

  • The pref read-back checks the pref, not what it controls, so read that back too: for layout.css.devPixelsPerPx, devicePixelRatio. A pref the product rewrites at startup reads back as dropped whatever its type, and needs setting on the running instance instead.

  • The result is the JSON on stdout. The mozversion INFO lines, the runner’s own messages and a glean.dispatcher panic (Global Glean object not initialized, mach’s telemetry, harmless) all go to stderr, so send stderr to its own file (>probe.json 2>probe.err) and parse stdout whole. A result can be a scalar (e.g. 42, "text", true, null) printed on one line, so a filter that starts at the first line beginning with { or [ prints nothing for it. A call that builds the virtualenv (SKILL.md §1 says when) prints “Creating the ‘wpt’ site”, and on a Linux host without pkg-config and the cairo and GObject introspection headers, a harmless failure to build the optional PyGObject (bug 2090261), which can land in stdout after the result. Build it with a call of its own before the first probe, as that section says, and the probes after it print the result alone.

  • Return plain values: a cyclic object prints nothing and exits 1 with Cyclic object value.

  • --window-size WIDTHxHEIGHT sets the outer window, so the content viewport comes out smaller by the height of the toolbars above it; read the content’s innerHeight back rather than computing it.

  • --chrome-setup-async takes the same body as --async (§2). Whatever the chrome setup returns prints to stderr as chrome setup returned: ….

  • Steps act in the --realm the probe runs in, so under chrome they click and type into browser UI. A grab refuses to overwrite a PNG an earlier run left, so give each run its own output directory; a grab writes into the directory that holds the --steps file.

  • An author sheet the probe loads itself never matches -moz-pref(), a data: one included (css_guidelines “Chrome-only media features go by the stylesheet, not the document” lists the sheets that do), so check a chrome-only media query through the computed value the shipped rule sets.

firefox-probe.py needs no running server. It runs on a throwaway profile, so a pref it sets dies with the run. It sets toolkit.asyncshutdown.crash_timeout to 5000 there, so a shutdown blocker that hangs, as on a binary built at another revision than the tree’s JS, ends the run in seconds with a minidump line in the browser log instead of holding it 60 s. A SIGINT, SIGTERM or SIGHUP (e.g. an outer timeout, a harness kill) still tears the browser down and removes its profile; a SIGKILL cannot, so give an outer timeout no -s KILL.

The grab step captures the compositor’s output; before choosing it over a canvas, read §2 “The compositor’s output” in measuring-pixels.md. The script runs headless by default; before passing --no-headless, read §1 “Pick the display rung by what the measurement needs” in running-a-probe.md: a non-headless run opens on the user’s desktop unless the host has an isolated display (its platform file, section DISPLAYS).

2. The chrome sandbox and --async

  • The snippet runs in Marionette’s chrome sandbox, not in the window. globalThis is not window. ChromeUtils.importESModule works there, and its Failed to load means no module lives at that URL: many browser modules moved from resource:///modules/ to moz-src:///browser/… (CustomizableUI.sys.mjs among them), so take the URL from an existing importer, or use the window’s global (window.CustomizableUI).

  • firefox-probe.py --async takes a bare body that may await and returns its result; a throw or rejection exits 1 with its message and stack. On a ScriptTimeoutException, pass --gecko-log and read the browser log (it holds NUL bytes, so search it with rg -a or grep -a) before assuming the workload was slow; a wedge that looks like a slow loop is usually a TypeError on the first iteration.

The run’s window opens on about:blank (SKILL.md §2 “A probe launch is not a user’s profile”). --url loads a page in the initial tab before a chrome snippet runs, and --serve serves a --url file:///abs/path over http. To load one mid-run, call win.openTrustedLinkIn("data:text/html,x", "current") and poll until win.gBrowser.currentURI.spec starts with data:.

The runner’s content sandbox has Xray vision over a web page, under --sandbox system too, so a custom element’s own methods and expandos read undefined there (a TypeError: … is not a function); reach them through el.wrappedJSObject. On a page with a system principal (document.nodePrincipal.isSystemPrincipal, as on many about: pages) no Xray applies under --sandbox system: el.wrappedJSObject is undefined and the element’s own members read directly. The MCP’s evaluate_script runs in the page’s realm and needs no waiver.