Source code
Revision control
Copy as Markdown
Other Tools
# Probe recipes
Recipes for setting up a probe and for finding what a rule does, one heading
per task. `SKILL.md` §2 routes here by heading.
## 1. Open the surface the way its tests do
Before probing any surface, read the feature's browser-chrome tests and the
helpers they import (e.g. the directory's `head.js`, a `*TestUtils.sys.mjs`
module): they show how the product's own tests open the surface, fill it and
wait for it to settle, and a probe can do the same once it undoes what a probe
launch changes (`SKILL.md` §2 "A probe launch is not a user's profile"). The
test harness registers, points at the objdir's `_tests/modules`:
```js
const dir = new FileUtils.File("<absolute objdir path>/_tests/modules");
Services.io.getProtocolHandler("resource")
.QueryInterface(Ci.nsIResProtocolHandler)
.setSubstitution("testing-common", Services.io.newFileURI(dir));
```
Then import a helper with `ChromeUtils.importESModule` and call it as the tests
do. A helper with an `init(scope)` method takes a stub holding the members it
calls (e.g. `Assert`, `info`, `registerCleanupFunction`), and an argument that a
harness global fills in a test (e.g. `waitForFocus`) needs a stand-in. Where a
helper needs more of the harness than a stub gives, write the probe as a
scratch browser-chrome test instead (`SKILL.md` §3).
A second browser window takes `BrowserWindowTracker.promiseOpenWindow()` (from
`BrowserTestUtils.openNewBrowserWindow()`, which does not settle in a probe; it
resolves once the window has finished delayed startup. `OpenBrowserWindow()`
returns while the new window is still `about:blank` and has no
`delayedStartupPromise` yet, so awaiting that property right after the call
waits for nothing, and the window's globals read `undefined`.
Reach a panel view with `PanelMultiView.getViewNode(document, id)` (from
`moz-src:///browser/components/customizableui/PanelMultiView.sys.mjs`), not
`document.getElementById` (`browser/components/customizableui/docs/panelmultiview.md`,
"Open or closed"). `PanelUI.show()` returns undefined, so poll until
`getComputedStyle(el).display` is non-empty before reading.
## 2. Read a part inside a shadow root
A `part` attribute is a list of names: select it with
`shadowRoot.querySelector('[part~="name"]')`, since `[part=name]` misses a
part that lists a second name. A climb by
`parentElement` from a slotted child skips the shadow tree; climb through
`assignedSlot`, as `./mach theme check-hcm-colors` and `./mach theme contrast` do.
## 3. Install a theme in the probe profile
**An add-on theme.** A theme hosted on addons.mozilla.org is not in the tree, so
install its XPI from `--chrome-setup-async`:
`AddonManager.installTemporaryAddon(new FileUtils.File(path))` (both modules
wait for `lwtheme` on the root before resolving. The temporary add-on goes with
the throwaway profile. Pick the variant with `ui.systemUsesDarkTheme`: a theme
with a `dark_theme` applies it when the chrome is dark. When the theme's XPI is
out of reach, zip a `manifest.json` with `"theme": {"colors": {...}}` holding
the keys under test into a stand-in; installTemporaryAddon takes it the same
way. A copy of the real manifest with the proposed colors tests a fix that
belongs in the theme.
**A built-in theme.** A probe profile holds only the default theme until idle
startup installs the others, so enable one from `--chrome-setup-async`: first
`await BuiltInThemes.ensureBuiltInThemes()`
`(await AddonManager.getAddonByID(id)).enable()` with an id from
`browser/themes/BuiltInThemeConfig.sys.mjs`, then wait for the root's
`theme-effective-id` to name it before resolving. Which token layer each kind
of theme paints is in `desktop-theme-tokens`' `references/token-layers.md` §2.
## 4. Test another platform's rule
A `ui.*` look-and-feel override
in `widget/nsXPLookAndFeel.cpp` makes a platform media feature match anywhere
(`ui.windowsMica=1` for `(-moz-windows-mica)`), but the platform's own sheet
(`browser/themes/windows/`, `osx/`, `linux/`) builds only on that platform. To
test the shipped rule text, read its block from the source file with
`IOUtils.readUTF8` (a chrome global, awaited; there is no module to import),
inject it into the document that loads the sheet (`browser.xhtml` or another
window's document) as
`doc.documentElement.appendChild(doc.createElementNS("http://www.w3.org/1999/xhtml", "style"))`, since a XUL document has no `head`, set the root attribute it
selects on (`customtitlebar`, for one),
read the values, then remove both and read again. When you inject a whole file
whose chrome URL the host platform also ships, disable the host's sheet at that
URL first (`node.sheet.disabled = true`, the node being its `<link>` or its
`<?xml-stylesheet?>` processing instruction), or
both cascade. That checks the cascade, not
the platform's paint; report the paint as environment-limited.
## 5. Lock a pseudo-class
`InspectorUtils.addPseudoClassLock(el, pc)`, then `clearPseudoClassLocks(el)` in
the same call. Confirm each lock with `InspectorUtils.hasPseudoClassLock(el,
pc)` (`SKILL.md` §2). `el.matches(pc)` is no substitute, since it can match
natively (`:-moz-window-inactive` in a headless window) and a bare `:hover`
never matches a non-link element in a quirks-mode page, locked or not (`*:hover`
does). Where it is reachable:
- the Marionette chrome sandbox, as `window.InspectorUtils`;
- a privileged content page such as about:preferences
(`firefox-probe.py --realm content`);
- any page, a web page included, under `firefox-probe.py --sandbox system`;
- a `SpecialPowers.spawn` task.
The Firefox MCP's `evaluate_script` runs in a web page's own realm and lacks
it; there `hover_by_uid` delivers a real pointer.
## 6. Match rules to an element
`prop` is a longhand; a shorthand reads `""` off a rule that sets only a
longhand. The filter keeps rules that set `prop` or a custom property its value
references, since a state rule often sets the token rather than the property; a
token set on an ancestor shows only in that ancestor's rules, so run it there
too. The same holds for an inherited property such as `color` or `fill`: an
empty list on an icon or label whose value is set means the rule sits on an
ancestor, such as the button that holds it. Never filter on `cssText`: an outer
rule's `cssText` contains every nested rule, so a hit there alone means the
nested rule did not apply, and some entries have no `cssText` at all. A nested
rule's `selectorText` is the bare `&:hover`, so the snippet walks `parentRule`
for the outer selectors.
```js
const rules = [...InspectorUtils.getMatchingCSSRules(el)];
const names = new Set([prop]);
for (const r of rules) {
const v = r.style?.getPropertyValue(prop) ?? "";
for (const [, n] of v.matchAll(/var\((--[\w-]+)/g)) names.add(n);
}
rules
.filter(r => [...names].some(n => r.style?.getPropertyValue(n)))
.map(r => {
const sel = [];
for (let x = r; x; x = x.parentRule) {
sel.unshift(x.selectorText ?? x.conditionText ?? "");
}
return `${r.parentStyleSheet?.href?.split("/").pop()}: ${sel.join(" ")}`;
});
```
## 7. Find the layer a declaration sits in
This probe checks `desktop-theme-tokens` §3's rule that an unlayered
redefinition outranks every token layer at the live document. It runs in the
chrome context, or in content through `firefox-probe.py --sandbox system`
(`InspectorUtils` and `ChromeUtils` need a system principal). Set `el` and
`name`.
```js
const cls = o => ChromeUtils.getClassName(o);
const layerOf = rule => {
for (let r = rule; r; ) {
if (cls(r) == "CSSLayerBlockRule") return r.name || "(anonymous)";
if (r.parentRule) { r = r.parentRule; continue; }
const owner = r.parentStyleSheet?.ownerRule;
if (owner && cls(owner) == "CSSImportRule" && owner.layerName !== null) return owner.layerName || "(anonymous)";
r = owner;
}
return null; // unlayered
};
// The nearest element that declares `name` decides the inherited value.
const declarers = (el, name) => {
for (let n = el; n; n = n.parentElement || n.getRootNode().host || null) {
const found = InspectorUtils.getMatchingCSSRules(n)
.filter(r => r.style?.getPropertyValue(name))
.map(r => ({ rule: r, layer: layerOf(r), value: r.style.getPropertyValue(name).trim() }));
if (n.style?.getPropertyValue(name)) found.push({ rule: null, layer: null, value: n.style.getPropertyValue(name) });
if (found.length) return { element: n, found };
}
return null;
};
const d = declarers(el, name);
const read = () => getComputedStyle(el).getPropertyValue(name).trim();
const before = read();
const saved = d.found.filter(f => f.rule && f.layer === null)
.map(f => [f.rule, f.rule.style.getPropertyValue(name), f.rule.style.getPropertyPriority(name)]);
for (const [r] of saved) r.style.removeProperty(name);
const without = read();
for (const [r, v, p] of saved) r.style.setProperty(name, v, p);
return { element: d.element.localName, found: d.found.map(f => [f.layer, f.value]), before, without, restored: read() };
```
A `without` that snaps to the layered value means the unlayered redefinition is
what paints. `getMatchingCSSRules` lists the rules in cascade order, so the last
normal declaration is the winner unless an earlier one is `!important`, which
reverses the layer order. Removing the property edits the live sheet of that
document only; `restored` should equal `before`. The probe finds the layer of a
`@layer` block, of a `@layer` block around `@media` and of an `@import …
layer()` rule.
## 8. Measure what a changed selector drops or adds
When a patch narrows an existing selector (e.g. a compound added or a rule moved
under an ancestor), enumerate the elements that fall out of it and measure one
of each: `[...document.querySelectorAll(oldSelector)].filter(el =>
!el.matches(newSelector))`. When it widens one (e.g. a compound dropped or a
rule moved out from under an ancestor), swap the two selectors to enumerate the
elements it newly reaches. A selector rewritten both ways (e.g. a renamed class,
or one compound added while another is dropped) does both, so run the snippet
in both directions. A result of zero or one in a fresh window means the
population is state-dependent (e.g. a panel not yet populated or a mode not
entered), not that nothing falls out or is newly reached; create it through the
product's own path first, then enumerate.