@hominis/fireforge 0.19.4 → 0.19.5

package/README.md

@@ -640,9 +640,7 @@ The two flags can be combined — `--with-tests --xpcshell` writes both harnesse
 
 ### 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/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;
 }

package/package.json

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