@hominis/fireforge 0.19.4 → 0.19.6

package/CHANGELOG.md

@@ -12,9 +12,14 @@
 - **`modified-file-missing-header` — standard Mozilla MPL-2.0 block headers with wrapped line breaks.** The upstream fallback scan required a contiguous `Mozilla Public License` substring in the first few lines, so files that follow Mozilla’s usual `/* … Mozilla Public` / ` * License, v. 2.0 … */` wrap (including after Emacs/vim directive blocks) were warned despite a valid notice. `containsUpstreamLicenseText` in `src/core/license-headers.ts` now normalizes common block-comment continuation prefixes before matching, so forks need not add SPDX solely to satisfy patch lint.
 - **`fireforge test` — `--marionette-port` auto-forward matches toolkit mochitests and mixed suites.** Auto-forward of `--setpref=marionette.port=<n>` previously keyed off a path heuristic that missed `toolkit/content/tests/**` widget HTML tests (no `/mochitest/` segment), so the preflight could use the operator’s port while mach still defaulted to **2828**. Forwarding now runs whenever `--marionette-port` is set unless `--mach-arg` explicitly includes `--flavor=xpcshell` / `xpcshell-tests` (the pref is unused there). `isMarionetteFlavor` also treats `toolkit/content/tests/` paths as Marionette-relevant unless they sit under `/tests/xpcshell/`, for consistency with other callers of that helper.
 
+### Compatibility
+
+- **`furnace create --with-tests` defaults to `browser-chrome` again** (not `mochikit`, which was the default after the `--test-style` split). Forks whose top-level chrome document has no `tabbrowser` should pass **`--test-style=mochikit`** explicitly. On macOS, toolkit MochiKit / mochitest-chrome-style widget tests can idle until ~370s with no subtests; README documents the tradeoff.
+
 ### Documentation
 
 - **README — mochitest timeouts vs Marionette.** The Test harness section documents long idle timeouts (~370s, `TEST_END: TIMEOUT`) on fork custom chrome, `--marionette-port` behaviour with xpcshell flavor, and pointers to fork-side prefs and investigation (for example Hominis `AGENT_RULES.md`).
+- **README — default test harness and macOS mochitest-chrome.** The README sections “Picking a test harness for `furnace create`”, “Test harness options”, and “Known upstream build issues” describe the browser-chrome default, macOS single-process idle timeout, explicit `--test-style=mochikit`, and `--with-tests` + `--xpcshell` resolution.
 
 ## 0.18.0
 

package/README.md

@@ -59,6 +59,8 @@ Your project now has `fireforge.json`, an `engine/` directory with Firefox sourc
 
 - **macOS 15 (Darwin 25+) — `gecko-profiler` bindgen error `cannot find type _CharT in this scope`.** An Apple toolchain update changed `std::__CharT_pointer` to `_CharT_pointer` in the libc++ headers Firefox's bindgen walks, so `toolkit/library/rust/target-objects` fails during `mach build` even on a clean `fireforge bootstrap`. This is an upstream Firefox issue, not a FireForge bug. Two workarounds: pin Xcode's command line tools to a pre-September-2025 release via `xcode-select --install` / [Apple developer downloads](https://developer.apple.com/download/all/), or apply a one-line bindgen-basic-string-workaround patch (a downstream consumer may ship one in its patch queue). If you interrupt the resulting `fireforge build` and re-run `fireforge doctor`, the download/engine state is unaffected — the failure is isolated to the Rust compile phase.
 
+- **macOS (including Apple Silicon) — toolkit / MochiKit widget tests idle until ~370s (`TEST_END: TIMEOUT`, no subtests).** The **mochitest-chrome** flavor used for `toolkit/content/tests/widgets/test_*.html` runs **single-process** (`e10s: false`), which interacts badly with headed or headless compositing (for example SWGL) in some setups. Prefer **`furnace create --with-tests`** (defaults to **`browser-chrome`**, multi-process) for interactive chrome coverage, or place tests alongside your fork's browser modules (for example `engine/browser/modules/<fork>/test/`). If you must use **`--test-style=mochikit`**, expect possible hangs on macOS. Details: [Picking a test harness for `furnace create`](#picking-a-test-harness-for-furnace-create), [Test harness options](#test-harness-options).
+
 ### Workflow Overview
 
 1. Make changes inside the `engine/` directory.
@@ -417,15 +419,17 @@ The packaging-verification test that `--with-tests` scaffolds is what FireForge
 
 ### Picking a test harness for `furnace create`
 
-`furnace create --with-tests` defaults to a MochiKit test at `engine/toolkit/content/tests/widgets/test_<tag>.html`. MochiKit tests load the component module via `chrome://global/` and don't need a `tabbrowser`, so they run against any fork — including bespoke chrome documents (`mybrowser.xhtml`-class) that deliberately omit the upstream browser chrome.
+`furnace create --with-tests` defaults to a **browser-chrome** mochitest: `browser_<binary>_<tag>.js` under `engine/browser/base/content/test/<binary-name>/`, registered via `browser.toml` (and `browser/base/moz.build` when the scaffolder appends there). Use this when the component participates in real browser chrome (tabs, `gBrowser`, and similar).
+
+**MochiKit** (`--test-style=mochikit`) is opt-in: it emits `test_<tag>.html` under `engine/toolkit/content/tests/widgets/`, loads the module via `chrome://global/`, and does not need a `tabbrowser` — so it is the right choice for bespoke chrome documents that omit the upstream tab strip. On **macOS**, that harness can hit a long idle timeout (see [Known upstream build issues](#known-upstream-build-issues)); prefer browser-chrome tests when your fork has a normal tabbed window.
 
 Three styles are available via `--test-style`:
 
-| Style            | When to use                                                                                                                                                                                                         |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mochikit`       | Default. Pure-UI custom elements. Runs today against non-tabbrowser chrome. Emits `test_<tag>.html` under `toolkit/content/tests/widgets/`.                                                                         |
-| `browser-chrome` | Element talks to the browser window (open URLs, manipulate tabs). Requires a working `tabbrowser` in the chrome document. Emits the `browser_<bin>_<tag>.js` scaffold and registers it in `browser/base/moz.build`. |
-| `xpcshell`       | Storage-layer, observer-driven, or ESM-loading code. Headless, no tabbrowser. Emits `test_<name>_module_loads.js` + `xpcshell.toml` (registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator).           |
+| Style            | When to use                                                                                                                                                                                               |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `browser-chrome` | **Default** with `--with-tests`. Interactive chrome, tab strip, `gBrowser`. Requires a working `tabbrowser`. Emits `browser_<bin>_<tag>.js` and registers via `browser.toml` / `browser/base/moz.build`.  |
+| `mochikit`       | Pure-UI custom elements on forks **without** a `tabbrowser`. Emits `test_<tag>.html` under `toolkit/content/tests/widgets/`. May be unreliable on macOS (mochitest-chrome / single-process).              |
+| `xpcshell`       | Storage-layer, observer-driven, or ESM-loading code. Headless, no tabbrowser. Emits `test_<name>_module_loads.js` + `xpcshell.toml` (registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator). |
 
 `--xpcshell` is preserved as an alias for `--test-style=xpcshell`; conflicting flag combinations (`--xpcshell --test-style=mochikit`) are rejected.
 
@@ -628,7 +632,7 @@ Set this in `furnace.json` to extend the list (forks with additional platform pr
 
 ### Test harness options
 
-`fireforge furnace create --with-tests` scaffolds a **browser-chrome mochitest**. Use this when the component renders UI that depends on the tab strip (`openLinkIn` → `URILoadingHelper`, `gBrowser`, etc.).
+`fireforge furnace create --with-tests` scaffolds a **browser-chrome mochitest** by default. Use this when the component renders UI that depends on the tab strip (`openLinkIn` → `URILoadingHelper`, `gBrowser`, etc.). On **macOS**, avoid relying on **`--test-style=mochikit`** (toolkit `test_*.html` under `toolkit/content/tests/widgets/`) for primary chrome/widget coverage: the **mochitest-chrome** flavor runs **single-process** (`e10s: false`) and has been observed to **idle ~370s** with no subtests (headless or headed compositing / SWGL). Prefer browser-chrome tests (multi-process); for forks that organize interactive tests under `engine/browser/modules/<fork>/test/`, extend that tree rather than adding new `test_<tag>.html` scaffolds when browser-chrome is sufficient.
 
 `fireforge furnace create --xpcshell` scaffolds an **xpcshell test harness** instead. Use this when the component's code path is storage-only, observer-driven, or module-loading logic that does not touch a `tabbrowser`. xpcshell runs headless without browser chrome, so forks without an upstream tab strip can still cover these paths. The scaffolder writes `test_<name>_packaged.js` + `xpcshell.toml` into `engine/browser/base/content/test/<binary-name>-xpcshell/<component-name>/` and prints a note: registration in `XPCSHELL_TESTS_MANIFESTS` is the operator's call (the moz.build that should own the entry depends on where the component actually lives). `fireforge register <path>/xpcshell.toml` surfaces the same guidance when run directly rather than silently routing to a browser.toml-shaped advice.
 
@@ -636,13 +640,11 @@ The scaffolded xpcshell test is a **packaging probe**, not a module-load test. L
 
 xpcshell has a chrome-URI boundary that is worth knowing before writing assertions: `chrome://global/*` (toolkit chrome) IS registered and resolvable from the harness, but `chrome://browser/*` (browser chrome) is NOT — even when `firefox-appdir = "browser"` is set in the xpcshell.toml, the manifest set xpcshell loads lags what the real browser loads, so `NetUtil.asyncFetch("chrome://browser/content/…")` can still fail with `NS_ERROR_FILE_NOT_FOUND` against an artifact that IS present in `obj-*/dist/`. Assertions that need browser chrome URIs belong in a browser-chrome mochitest (`furnace create --test-style=browser-chrome`).
 
-The two flags can be combined — `--with-tests --xpcshell` writes both harnesses.
+If you pass **`--with-tests` and `--xpcshell` together**, FireForge resolves the harness to **xpcshell only** (`--xpcshell` takes precedence). To get the default browser-chrome mochitest as well, run a second `furnace create` with `--with-tests` only or add the browser test files manually.
 
 ### Mochitest stalls and `--marionette-port`
 
-When you pass `--marionette-port <n>`, FireForge uses that port for the stale-listener probe and for `--doctor`, and it forwards `--setpref=marionette.port=<n>` to `mach test` so the harness binds the same port. The only exception is an explicit `--mach-arg --flavor=xpcshell` (or `--flavor=xpcshell-tests`): that harness ignores the pref, so FireForge skips auto-forward and logs a short notice instead. Toolkit widget mochitests under `toolkit/content/tests/` (for example `test_*.html` next to `browser_*.js` suites) therefore stay aligned with the probe without duplicating `--mach-arg=--setpref=marionette.port=…`.
-
-Some forks see mochitests end with **`TEST_END: TIMEOUT`** after on the order of **370 seconds** with **no harness output** — including runs where mozinfo reports `headless: false`, so the failure is not explained by SWGL headless alone. When tests wait on custom chrome (for example a fork tile shell that never sets a `_readyForTesting` gate), the hang is **engine-side**; use your fork’s test docs and `browser.toml` defaults (for Hominis-style trees, see the fork’s `AGENT_RULES.md` for `hominis.testing.*` prefs). Operationally: ensure Marionette port **2828** is free, pass **`--marionette-port`** when you use a non-default port (FireForge keeps preflight and mach consistent as above), and narrow the failure with `--doctor` or by splitting a lighter smoke test that does not depend on full chrome init.
+When you pass `--marionette-port <n>`, FireForge uses that port for the **stale-listener probe** (before `mach test` runs) and for **`--doctor`**, forwards **`--setpref=marionette.port=<n>`** to `mach test` so the **browser Marionette listener** binds that port, and forwards **`--marionette=127.0.0.1:<n>`** so the **mochitest harness client** connects to the same endpoint (the client otherwise defaults to `127.0.0.1:2828`). If you already pass **`--mach-arg=--marionette=...`**, FireForge does not add a second client flag. If **`--mach-arg`** already forwards the port via **`--marionette-port=...`** or **`--setpref=marionette.port=...`**, FireForge skips duplicating the setpref (existing behaviour). The exception is an explicit **`--mach-arg --flavor=xpcshell`** (or **`--flavor=xpcshell-tests`**): that harness does not use the browser Marionette path, so FireForge skips both auto-forwarded flags and logs a short notice instead. Toolkit widget mochitests under `toolkit/content/tests/` (for example `test_*.html` next to `browser_*.js` suites) therefore stay aligned with the probe without duplicating **`--mach-arg=--setpref=marionette.port=…`**.
 
 ### Stale-build preflight on `fireforge test`
 

package/dist/src/commands/furnace/create.d.ts

@@ -5,14 +5,14 @@ export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'no
  * Collapses `--with-tests`, `--xpcshell`, and `--test-style` into the single
  * scaffold dispatch used inside the mutation phase.
  *
- * Backwards-compat invariants:
+ * Invariants:
  * - `--xpcshell` alone is equivalent to `--test-style=xpcshell`.
- * - `--with-tests` alone (no `--test-style`) now defaults to `mochikit`
- *   (previously it defaulted to browser-chrome; the dogfooding pass
- *   flagged browser-chrome as unrunnable against non-tabbrowser chrome).
- *   Operators who need the old behavior can pass
- *   `--with-tests --test-style=browser-chrome`.
- * - `--xpcshell --with-tests` is rejected as ambiguous.
+ * - `--with-tests` alone (no `--test-style`) defaults to `browser-chrome`
+ *   (multi-process mochitest; reliable on macOS for interactive chrome).
+ *   Forks whose chrome document has no `tabbrowser` should pass
+ *   `--test-style=mochikit` explicitly.
+ * - When both `--xpcshell` and `--with-tests` are set, `--xpcshell` wins
+ *   (resolved style is `xpcshell` only).
  * @throws InvalidArgumentError when flags conflict.
  */
 export declare function resolveTestStyle(options: FurnaceCreateOptions): ResolvedTestStyle;

package/dist/src/commands/furnace/create.js

@@ -204,14 +204,14 @@ async function writeComponentFiles(componentDir, componentName, className, descr
  * Collapses `--with-tests`, `--xpcshell`, and `--test-style` into the single
  * scaffold dispatch used inside the mutation phase.
  *
- * Backwards-compat invariants:
+ * Invariants:
  * - `--xpcshell` alone is equivalent to `--test-style=xpcshell`.
- * - `--with-tests` alone (no `--test-style`) now defaults to `mochikit`
- *   (previously it defaulted to browser-chrome; the dogfooding pass
- *   flagged browser-chrome as unrunnable against non-tabbrowser chrome).
- *   Operators who need the old behavior can pass
- *   `--with-tests --test-style=browser-chrome`.
- * - `--xpcshell --with-tests` is rejected as ambiguous.
+ * - `--with-tests` alone (no `--test-style`) defaults to `browser-chrome`
+ *   (multi-process mochitest; reliable on macOS for interactive chrome).
+ *   Forks whose chrome document has no `tabbrowser` should pass
+ *   `--test-style=mochikit` explicitly.
+ * - When both `--xpcshell` and `--with-tests` are set, `--xpcshell` wins
+ *   (resolved style is `xpcshell` only).
  * @throws InvalidArgumentError when flags conflict.
  */
 export function resolveTestStyle(options) {
@@ -226,7 +226,7 @@ export function resolveTestStyle(options) {
     if (xpcshellFlag)
         return 'xpcshell';
     if (withTests)
-        return 'mochikit';
+        return 'browser-chrome';
     return 'none';
 }
 /**

package/dist/src/commands/furnace/index.js

@@ -71,9 +71,9 @@ function registerFurnaceInfoCommands(furnace, context) {
         .option('-d, --description <desc>', 'Component description')
         .option('--localized', 'Include Fluent l10n support')
         .option('--no-register', 'Skip customElements.js registration')
-        .option('--with-tests', 'Scaffold a test harness (defaults to MochiKit; see --test-style)')
+        .option('--with-tests', 'Scaffold a test harness (defaults to browser-chrome; use --test-style=mochikit for tabbrowser-less chrome — may be flaky on macOS)')
         .option('--xpcshell', 'Scaffold an xpcshell test harness (for storage-layer code on forks without tabbrowser); equivalent to --test-style=xpcshell. Note: xpcshell resolves chrome://global/* URIs but not chrome://browser/* — use --test-style=browser-chrome for browser-chrome-dependent tests.')
-        .option('--test-style <style>', "Override the harness written by --with-tests: mochikit (default, runs against non-tabbrowser chrome), browser-chrome (today's scaffold, needs tabbrowser), or xpcshell (headless)", (value) => {
+        .option('--test-style <style>', 'Override the harness written by --with-tests: browser-chrome (default, needs tabbrowser), mochikit (toolkit/widgets, non-tabbrowser chrome), or xpcshell (headless)', (value) => {
         if (value !== 'mochikit' && value !== 'browser-chrome' && value !== 'xpcshell') {
             throw new Error(`--test-style must be one of: mochikit, browser-chrome, xpcshell. Got: "${value}".`);
         }

package/dist/src/commands/test.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, } from '../core/mach.js';
-import { assertMarionettePortAvailable, extractForwardedMarionettePort, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
+import { assertMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
@@ -320,17 +320,21 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         extraArgs.push(...options.machArg);
     }
     // Auto-forward the Marionette port to mach when `--marionette-port` is
-    // set. We use `--setpref=marionette.port=<n>` because the marionette
-    // listener reads that pref before binding (browser-chrome / mochitest
-    // path); xpcshell never reads it, so the pref is a no-op there.
+    // set. `--setpref=marionette.port=<n>` configures where the browser
+    // listener binds; `--marionette=127.0.0.1:<n>` tells the mochitest harness
+    // client to connect there (default client is 127.0.0.1:2828). xpcshell
+    // ignores both for browser Marionette.
     //
-    // Skip forwarding when the operator already supplied an equivalent arg
-    // via `--mach-arg` — duplicates would be confusing without changing
+    // Skip setpref forwarding when the operator already supplied an equivalent
+    // arg via `--mach-arg` — duplicates would be confusing without changing
     // semantics. Skip when mach args explicitly request `--flavor=xpcshell`
     // (or `xpcshell-tests`): the preflight still honours `--marionette-port`,
     // but mach does not use the marionette.port pref on that harness. Any
     // other arg shape still forwards so toolkit widget paths and mixed suites
     // stay aligned with the probe without duplicate `--mach-arg` flags.
+    //
+    // Skip auto `--marionette=...` when `--mach-arg` already includes a client
+    // `--marionette=...` (or two-token `--marionette host:port`).
     if (options.marionettePort !== undefined) {
         const operatorAlreadyForwarded = forwardedPort !== undefined;
         const machArgs = options.machArg ?? [];
@@ -341,7 +345,11 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             extraArgs.push(`--setpref=marionette.port=${options.marionettePort}`);
         }
         else {
-            info(`--marionette-port=${options.marionettePort} applied to the preflight probe, but --flavor=xpcshell is set — mach is not auto-configured with --setpref=marionette.port (xpcshell ignores that pref). Pass --mach-arg --setpref=marionette.port=${options.marionettePort} explicitly if you still need mach to see the port.`);
+            info(`--marionette-port=${options.marionettePort} applied to the preflight probe, but --flavor=xpcshell is set — mach is not auto-configured with --setpref=marionette.port or --marionette (xpcshell ignores the browser Marionette path). Pass --mach-arg --setpref=marionette.port=${options.marionettePort} explicitly if you still need mach to see the port.`);
+        }
+        if (shouldAutoForwardMarionettePortToMach(machArgs) &&
+            !forwardedMachArgsIncludeMarionetteClient(machArgs)) {
+            extraArgs.push(`--marionette=127.0.0.1:${options.marionettePort}`);
         }
     }
     // xpcshell appdir auto-injection — see src/core/xpcshell-appdir.ts for the
@@ -409,7 +417,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         acc.push(value);
         return acc;
     }, [])
-        .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and (unless --mach-arg includes --flavor=xpcshell) the auto-forwarded --setpref=marionette.port=<n> passed to mach. Use this when a stale process holds 2828 or a CI runner reserves a different port.', (raw) => {
+        .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and (unless --mach-arg includes --flavor=xpcshell) auto-forwarded mach args: --setpref=marionette.port=<n> (browser listener) and --marionette=127.0.0.1:<n> (mochitest client). Omits the client flag when --mach-arg already sets --marionette. Use when 2828 is busy or CI assigns another port.', (raw) => {
         const n = Number.parseInt(raw, 10);
         if (!Number.isFinite(n) || n < 1 || n > 65535) {
             throw new GeneralError(`--marionette-port must be an integer in 1..65535 (got "${raw}")`);

package/dist/src/core/marionette-port.d.ts

@@ -64,6 +64,15 @@ export declare function assertMarionettePortAvailable(port?: number, options?: {
  *   `undefined`.
  */
 export declare function extractForwardedMarionettePort(machArgs: string[]): number | undefined;
+/**
+ * True when forwarded mach args already set a Marionette **client** address
+ * for mach/mochitest (`--marionette=host:port` or `--marionette host:port`).
+ * Used only to avoid duplicating FireForge's auto-injected
+ * `--marionette=127.0.0.1:<n>`; this is not a full URL validator (IPv6, etc.).
+ *
+ * Deliberately does **not** treat `--marionette-port` as a client endpoint.
+ */
+export declare function forwardedMachArgsIncludeMarionetteClient(machArgs: string[]): boolean;
 /**
  * True when forwarded mach args explicitly select the xpcshell harness.
  * Used so `--marionette-port` auto-forward skips `--setpref=marionette.port`
@@ -71,11 +80,12 @@ export declare function extractForwardedMarionettePort(machArgs: string[]): numb
  */
 export declare function hasExplicitXpcshellFlavor(machArgs: string[]): boolean;
 /**
- * Whether `fireforge test` should append `--setpref=marionette.port=<n>` when
- * the operator passed `--marionette-port`. Forwards for every harness except
- * an explicit `--flavor=xpcshell` / `xpcshell-tests` (toolkit widget mochitests
- * under `toolkit/content/tests/` do not match the older path-only heuristic
- * but still launch a Marionette-driven browser).
+ * Whether `fireforge test` should append `--setpref=marionette.port=<n>` and
+ * `--marionette=127.0.0.1:<n>` when the operator passed `--marionette-port`.
+ * Forwards for every harness except an explicit `--flavor=xpcshell` /
+ * `xpcshell-tests` (toolkit widget mochitests under `toolkit/content/tests/`
+ * do not match the older path-only heuristic but still launch a
+ * Marionette-driven browser).
  */
 export declare function shouldAutoForwardMarionettePortToMach(machArgs: string[]): boolean;
 /**
@@ -88,7 +98,7 @@ export declare function shouldAutoForwardMarionettePortToMach(machArgs: string[]
  * Note: `fireforge test` auto-forward of `--marionette-port` to mach uses
  * {@link shouldAutoForwardMarionettePortToMach} (mach-arg flavor gate) rather
  * than this function alone, so toolkit paths without `/mochitest/` still get
- * the pref when appropriate.
+ * the listener pref and harness `--marionette=127.0.0.1:<n>` when appropriate.
  *
  * @param testPaths - Engine-relative paths after `stripEnginePrefix`.
  * @param machArgs - Forwarded mach args (post-`--mach-arg`).

package/dist/src/core/marionette-port.js

@@ -260,6 +260,31 @@ export function extractForwardedMarionettePort(machArgs) {
     }
     return undefined;
 }
+/**
+ * True when forwarded mach args already set a Marionette **client** address
+ * for mach/mochitest (`--marionette=host:port` or `--marionette host:port`).
+ * Used only to avoid duplicating FireForge's auto-injected
+ * `--marionette=127.0.0.1:<n>`; this is not a full URL validator (IPv6, etc.).
+ *
+ * Deliberately does **not** treat `--marionette-port` as a client endpoint.
+ */
+export function forwardedMachArgsIncludeMarionetteClient(machArgs) {
+    const valueLooksLikeHostPort = (token) => /:[0-9]+$/.test(token) || /^\[[^]]+\]:[0-9]+$/.test(token);
+    for (let i = 0; i < machArgs.length; i++) {
+        const arg = machArgs[i];
+        if (arg === undefined)
+            continue;
+        if (arg.startsWith('--marionette=') && !arg.startsWith('--marionette-port=')) {
+            return true;
+        }
+        if (arg === '--marionette') {
+            const next = machArgs[i + 1];
+            if (next !== undefined && valueLooksLikeHostPort(next))
+                return true;
+        }
+    }
+    return false;
+}
 /**
  * True when forwarded mach args explicitly select the xpcshell harness.
  * Used so `--marionette-port` auto-forward skips `--setpref=marionette.port`
@@ -273,11 +298,12 @@ export function hasExplicitXpcshellFlavor(machArgs) {
     return false;
 }
 /**
- * Whether `fireforge test` should append `--setpref=marionette.port=<n>` when
- * the operator passed `--marionette-port`. Forwards for every harness except
- * an explicit `--flavor=xpcshell` / `xpcshell-tests` (toolkit widget mochitests
- * under `toolkit/content/tests/` do not match the older path-only heuristic
- * but still launch a Marionette-driven browser).
+ * Whether `fireforge test` should append `--setpref=marionette.port=<n>` and
+ * `--marionette=127.0.0.1:<n>` when the operator passed `--marionette-port`.
+ * Forwards for every harness except an explicit `--flavor=xpcshell` /
+ * `xpcshell-tests` (toolkit widget mochitests under `toolkit/content/tests/`
+ * do not match the older path-only heuristic but still launch a
+ * Marionette-driven browser).
  */
 export function shouldAutoForwardMarionettePortToMach(machArgs) {
     return !hasExplicitXpcshellFlavor(machArgs);
@@ -292,7 +318,7 @@ export function shouldAutoForwardMarionettePortToMach(machArgs) {
  * Note: `fireforge test` auto-forward of `--marionette-port` to mach uses
  * {@link shouldAutoForwardMarionettePortToMach} (mach-arg flavor gate) rather
  * than this function alone, so toolkit paths without `/mochitest/` still get
- * the pref when appropriate.
+ * the listener pref and harness `--marionette=127.0.0.1:<n>` when appropriate.
  *
  * @param testPaths - Engine-relative paths after `stripEnginePrefix`.
  * @param machArgs - Forwarded mach args (post-`--mach-arg`).

package/dist/src/types/commands/options.d.ts

@@ -318,11 +318,12 @@ export interface TestOptions {
     machArg?: string[];
     /**
      * Override the Marionette control port (default 2828) used by the
-     * stale-browser probe, the `--doctor` preflight, and the auto-forwarded
-     * `--setpref=marionette.port=<n>` arg passed to mach (omitted when mach
-     * args explicitly set `--flavor=xpcshell` / `xpcshell-tests`). Set this
-     * when a stale process holds the default port and `kill` is not an option,
-     * or when a CI runner reserves a different port for parallel test runs.
+     * stale-browser probe, the `--doctor` preflight, and (unless mach args set
+     * `--flavor=xpcshell` / `xpcshell-tests`) auto-forwarded mach flags:
+     * `--setpref=marionette.port=<n>` for the browser listener and
+     * `--marionette=127.0.0.1:<n>` for the mochitest harness client. Omits the
+     * client flag when `--mach-arg` already passes `--marionette`. Set when a
+     * stale process holds the default port or CI uses another port.
      */
     marionettePort?: number;
 }
@@ -425,15 +426,15 @@ export interface FurnaceCreateOptions {
     /**
      * Test harness style to scaffold when `--with-tests` is set.
      *
-     * - `mochikit` (default when `--with-tests` is set alone) — a MochiKit
-     *   test at `engine/toolkit/content/tests/widgets/test_<tag>.html` that
-     *   loads the component module directly via `chrome://global/` and
-     *   asserts against `customElements`. Runs today on forks whose
-     *   top-level chrome document (e.g. `mybrowser.xhtml`) lacks a
-     *   `tabbrowser`, because it doesn't go through `URILoadingHelper`.
-     * - `browser-chrome` — today's browser-mochitest scaffold, requires a
-     *   working tabbrowser. Use for components that talk to the browser
-     *   window or open URLs.
+     * - `browser-chrome` (default when `--with-tests` is set without
+     *   `--test-style`) — browser mochitest scaffold; requires a working
+     *   `tabbrowser`. Prefer this for interactive chrome/widget coverage
+     *   (including on macOS).
+     * - `mochikit` — opt-in MochiKit test at
+     *   `engine/toolkit/content/tests/widgets/test_<tag>.html` that loads
+     *   the component via `chrome://global/`. Use when the top-level chrome
+     *   document lacks a `tabbrowser`; on macOS the toolkit mochitest-chrome
+     *   flavor can be unreliable (long idle timeout).
      * - `xpcshell` — equivalent to setting `--xpcshell`; headless, storage-only.
      */
     testStyle?: 'mochikit' | 'browser-chrome' | 'xpcshell';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.19.4",
+  "version": "0.19.6",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",