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
mozversionINFOlines, the runner’s own messages and aglean.dispatcherpanic (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 withoutpkg-configand 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 WIDTHxHEIGHTsets the outer window, so the content viewport comes out smaller by the height of the toolbars above it; read the content’sinnerHeightback rather than computing it.--chrome-setup-asynctakes the same body as--async(§2). Whatever the chrome setup returns prints to stderr aschrome setup returned: ….Steps act in the
--realmthe probe runs in, so underchromethey click and type into browser UI. Agrabrefuses 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--stepsfile.An author sheet the probe loads itself never matches
-moz-pref(), adata: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.
globalThisis notwindow.ChromeUtils.importESModuleworks there, and itsFailed to loadmeans no module lives at that URL: many browser modules moved fromresource:///modules/tomoz-src:///browser/…(CustomizableUI.sys.mjsamong them), so take the URL from an existing importer, or use the window’s global (window.CustomizableUI).firefox-probe.py --asynctakes a bare body that mayawaitandreturns its result; a throw or rejection exits 1 with its message and stack. On aScriptTimeoutException, pass--gecko-logand read the browser log (it holds NUL bytes, so search it withrg -aorgrep -a) before assuming the workload was slow; a wedge that looks like a slow loop is usually aTypeErroron 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.