@hominis/fireforge 0.19.2 → 0.19.3

package/CHANGELOG.md

@@ -10,6 +10,11 @@
 ### Hardening
 
 - **`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.
+
+### 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`).
 
 ## 0.18.0
 

package/README.md

@@ -638,6 +638,12 @@ xpcshell has a chrome-URI boundary that is worth knowing before writing assertio
 
 The two flags can be combined — `--with-tests --xpcshell` writes both harnesses.
 
+### 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.
+
 ### Stale-build preflight on `fireforge test`
 
 `fireforge test <path>` (without `--build`) now runs a preflight that diffs engine HEAD and the workdir against the last successful `fireforge build` (recorded at `.fireforge/last-build.json`). When packageable engine files have changed since that baseline, the command prints a single up-front warning naming the paths and pointing at `fireforge test --build`. This catches the class of failure where a newly scaffolded chrome resource or pref file is registered correctly but `obj-*/dist/` still holds the pre-edit bundle, so the test reads stale packaged artifacts and errors out with a cryptic `NS_ERROR_FILE_NOT_FOUND` inside xpcshell / mach test. The preflight is warn-only — a fork that rebuilt out-of-band (direct `./mach build`, IDE plugin, separate CI stage) is not blocked. Passing `--build` skips the preflight because the rebuild just refreshed the bundle.

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, isMarionetteFlavor, } from '../core/marionette-port.js';
+import { assertMarionettePortAvailable, extractForwardedMarionettePort, 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';
@@ -326,21 +326,22 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     //
     // Skip forwarding when the operator already supplied an equivalent arg
     // via `--mach-arg` — duplicates would be confusing without changing
-    // semantics. Skip with a notice for clearly-non-marionette flavours
-    // (xpcshell, or paths that don't look browser-chrome/mochitest) so the
-    // operator knows the preflight took the override but mach was not
-    // auto-configured. Same escape valve applies: any mach arg can still
-    // be supplied via `--mach-arg`.
+    // 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.
     if (options.marionettePort !== undefined) {
         const operatorAlreadyForwarded = forwardedPort !== undefined;
+        const machArgs = options.machArg ?? [];
         if (operatorAlreadyForwarded) {
             info(`--marionette-port=${options.marionettePort} set, but the same port is already forwarded via --mach-arg; skipping auto-forward.`);
         }
-        else if (isMarionetteFlavor(normalizedPaths, options.machArg ?? [])) {
+        else if (shouldAutoForwardMarionettePortToMach(machArgs)) {
             extraArgs.push(`--setpref=marionette.port=${options.marionettePort}`);
         }
         else {
-            info(`--marionette-port=${options.marionettePort} applied to the preflight probe, but the test paths do not look browser-chrome/mochitest — mach is not auto-configured. Pass --mach-arg --setpref=marionette.port=${options.marionettePort} explicitly if mach should also use this 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 (xpcshell ignores that pref). Pass --mach-arg --setpref=marionette.port=${options.marionettePort} explicitly if you still need mach to see the port.`);
         }
     }
     // xpcshell appdir auto-injection — see src/core/xpcshell-appdir.ts for the
@@ -408,7 +409,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 the auto-forwarded --setpref=marionette.port=<n> arg 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) 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) => {
         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,13 +64,31 @@ export declare function assertMarionettePortAvailable(port?: number, options?: {
  *   `undefined`.
  */
 export declare function extractForwardedMarionettePort(machArgs: string[]): number | undefined;
+/**
+ * True when forwarded mach args explicitly select the xpcshell harness.
+ * Used so `--marionette-port` auto-forward skips `--setpref=marionette.port`
+ * for runs where the pref is ignored anyway.
+ */
+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).
+ */
+export declare function shouldAutoForwardMarionettePortToMach(machArgs: string[]): boolean;
 /**
  * Heuristic: do the test paths or forwarded mach args indicate a flavour
  * that actually launches a Marionette-driven browser? Browser-chrome and
- * mochitest do; xpcshell does not. Used to decide whether to auto-forward
- * `--setpref=marionette.port=<n>` to mach when the operator passed
- * `--marionette-port`. A no-paths invocation (the default "run all tests"
- * shape) is treated as marionette-relevant since it includes browser-chrome.
+ * mochitest do; xpcshell does not. A no-paths invocation (the default "run
+ * all tests" shape) is treated as marionette-relevant since it includes
+ * browser-chrome.
+ *
+ * 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.
  *
  * @param testPaths - Engine-relative paths after `stripEnginePrefix`.
  * @param machArgs - Forwarded mach args (post-`--mach-arg`).

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

@@ -260,23 +260,47 @@ export function extractForwardedMarionettePort(machArgs) {
     }
     return undefined;
 }
+/**
+ * True when forwarded mach args explicitly select the xpcshell harness.
+ * Used so `--marionette-port` auto-forward skips `--setpref=marionette.port`
+ * for runs where the pref is ignored anyway.
+ */
+export function hasExplicitXpcshellFlavor(machArgs) {
+    for (const arg of machArgs) {
+        if (/^--flavor=xpcshell\b/.test(arg) || arg === '--flavor=xpcshell-tests')
+            return true;
+    }
+    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).
+ */
+export function shouldAutoForwardMarionettePortToMach(machArgs) {
+    return !hasExplicitXpcshellFlavor(machArgs);
+}
 /**
  * Heuristic: do the test paths or forwarded mach args indicate a flavour
  * that actually launches a Marionette-driven browser? Browser-chrome and
- * mochitest do; xpcshell does not. Used to decide whether to auto-forward
- * `--setpref=marionette.port=<n>` to mach when the operator passed
- * `--marionette-port`. A no-paths invocation (the default "run all tests"
- * shape) is treated as marionette-relevant since it includes browser-chrome.
+ * mochitest do; xpcshell does not. A no-paths invocation (the default "run
+ * all tests" shape) is treated as marionette-relevant since it includes
+ * browser-chrome.
+ *
+ * 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.
  *
  * @param testPaths - Engine-relative paths after `stripEnginePrefix`.
  * @param machArgs - Forwarded mach args (post-`--mach-arg`).
  * @returns `true` when the run is likely to bind a Marionette listener.
  */
 export function isMarionetteFlavor(testPaths, machArgs) {
-    for (const arg of machArgs) {
-        if (/^--flavor=xpcshell\b/.test(arg) || arg === '--flavor=xpcshell-tests')
-            return false;
-    }
+    if (hasExplicitXpcshellFlavor(machArgs))
+        return false;
     for (const arg of machArgs) {
         if (/^--flavor=(browser-chrome|mochitest|chrome|a11y)\b/.test(arg))
             return true;
@@ -291,6 +315,9 @@ export function isMarionetteFlavor(testPaths, machArgs) {
             return true;
         if (path.includes('/browser-chrome/') || path.startsWith('browser-chrome/'))
             return true;
+        if (path.includes('toolkit/content/tests/') && !path.includes('/tests/xpcshell/')) {
+            return true;
+        }
     }
     return false;
 }

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

@@ -319,9 +319,10 @@ export interface TestOptions {
     /**
      * 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. 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.
+     * `--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.
      */
     marionettePort?: number;
 }

package/package.json

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