qunitx-cli 0.9.10 → 0.11.0

package/README.md

@@ -22,9 +22,12 @@ output to the terminal.
 - `--watch` mode re-runs affected tests on file change
 - `--failFast` stops the run after the first failing test
 - `--debug` prints the local server URL and pipes browser console to stdout
+- `--open` / `-o` opens the test output in the same browser the tests run in as soon as the bundle is ready; `--open=brave` opens in a specific binary instead
 - `--before` / `--after` hook scripts for server setup and teardown
 - `--timeout` controls the maximum ms to wait for the full suite to finish
+- `--port` defaults to 1234 and auto-increments if taken; fails fast if an explicit port is unavailable
 - `--browser` flag to run tests in Chromium, Firefox, or WebKit
+- `--version` / `-v` prints the installed version
 - Docker image for zero-install CI usage
 
 ## Installation
@@ -74,6 +77,13 @@ qunitx test/**/*.js --failFast
 # Print the server URL and pipe browser console to stdout
 qunitx test/**/*.js --debug
 
+# Open output in the test browser as soon as the bundle is ready
+qunitx test/**/*.js --open
+
+# Open output in a specific browser binary instead
+qunitx test/**/*.js --open=brave
+qunitx test/**/*.js --open=google-chrome-lts
+
 # Custom timeout (ms)
 qunitx test/**/*.js --timeout=30000
 
@@ -89,6 +99,7 @@ qunitx test/**/*.js --browser=webkit
 ```
 
 > **Prerequisite for Firefox / WebKit:** install the Playwright browser binaries once:
+>
 > ```sh
 > npx playwright install firefox
 > npx playwright install webkit
@@ -153,6 +164,7 @@ All CLI flags can also be set in `package.json` under the `qunitx` key, so you d
 {
   "qunitx": {
     "inputs": ["test/**/*-test.js", "test/**/*-test.ts"],
+    "htmlPaths": ["test/tests.html"],
     "extensions": ["js", "ts"],
     "output": "tmp",
     "timeout": 20000,
@@ -163,18 +175,31 @@ All CLI flags can also be set in `package.json` under the `qunitx` key, so you d
 }
 ```
 
-| Key | Default | Description |
-|-----|---------|-------------|
-| `inputs` | `[]` | Glob patterns, file paths, or directories to use as test entry points. Merged with any paths given on the CLI. |
-| `extensions` | `["js", "ts"]` | File extensions tracked for test discovery (directory scans) and watch-mode rebuild triggers. Add `"mjs"`, `"cjs"`, or any other extension your project uses. |
-| `output` | `"tmp"` | Directory where compiled test bundles are written. |
-| `timeout` | `20000` | Maximum milliseconds to wait for the full test suite before timing out. |
-| `failFast` | `false` | Stop the run after the first failing test. |
-| `port` | `1234` | Preferred HTTP server port. qunitx auto-selects a free port if this one is taken. |
-| `browser` | `"chromium"` | Browser engine to use: `"chromium"`, `"firefox"`, or `"webkit"`. Overridden by `--browser` on the CLI. |
+| Key          | Default        | Description                                                                                                                                                             |
+| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `inputs`     | `[]`           | Glob patterns, file paths, or directories to use as test entry points. Merged with any paths given on the CLI.                                                          |
+| `htmlPaths`  | `[]`           | Optional HTML templates to run tests inside. Any listed `.html` file that contains `{{qunitxScript}}` or other handlebars-style tokens is treated as a test runner template. |
+| `extensions` | `["js", "ts"]` | File extensions tracked for test discovery (directory scans) and watch-mode rebuild triggers. Add `"mjs"`, `"cjs"`, or any other extension your project uses.           |
+| `output`     | `"tmp"`        | Directory where compiled test bundles are written.                                                                                                                      |
+| `timeout`    | `20000`        | Maximum milliseconds to wait for the full test suite before timing out.                                                                                                 |
+| `failFast`   | `false`        | Stop the run after the first failing test.                                                                                                                              |
+| `port`       | `1234`         | Preferred HTTP server port. qunitx auto-selects a free port if this one is taken.                                                                                       |
+| `browser`    | `"chromium"`   | Browser engine to use: `"chromium"`, `"firefox"`, or `"webkit"`. Overridden by `--browser` on the CLI.                                                                  |
 
 CLI flags always override `package.json` values when both are present.
 
+If you do not provide any HTML template, qunitx falls back to its built-in `test/tests.html` boilerplate internally, so `qunitx init` is optional.
+
+You can also pass a custom HTML file on the CLI:
+
+```sh
+qunitx test/**/*.js custom.html
+```
+
+If that file contains `{{qunitxScript}}`, qunitx injects the runner script block at that exact spot. If it contains other handlebars-style tokens (e.g. `{{applicationName}}`), qunitx still treats it as a custom runner template and injects the runner before `</body>`.
+
+The `{{qunitxScript}}` placeholder is replaced with a `<script>` tag containing the WebSocket runtime, QUnit event hooks, and the bundled test code.
+
 ## CLI Reference
 
 ```
@@ -189,6 +214,8 @@ Options:
   --extensions=<...>  Comma-separated file extensions to track  [default: js,ts]
   --before=<file>     Script to run (and optionally await) before tests start
   --after=<file>      Script to run (and optionally await) after tests finish
+  --open, -o          Open output in the test browser as soon as the bundle is ready
+  --open=<binary>     Open output in a specific browser binary (e.g. brave, google-chrome-lts)
   --port=<n>          HTTP server port (auto-selects a free port if taken)
   --browser=<name>    Browser engine: chromium (default), firefox, or webkit
 ```

package/dist/cli.js

@@ -39,10 +39,11 @@ var init_find_chrome = __esm({
 
 // lib/utils/pre-launch-chrome.ts
 import { spawn } from "node:child_process";
-function preLaunchChrome(chromePath, args) {
+function preLaunchChrome(chromePath, args, headless = true) {
   if (!chromePath) return Promise.resolve(null);
+  const headlessArgs = headless ? ["--headless=new"] : [];
   return new Promise((resolve) => {
-    const proc = spawn(chromePath, ["--remote-debugging-port=0", "--headless=new", ...args], {
+    const proc = spawn(chromePath, ["--remote-debugging-port=0", ...headlessArgs, ...args], {
       stdio: ["ignore", "ignore", "pipe"]
     });
     let buffer = "";
@@ -107,7 +108,7 @@ var init_perf_logger = __esm({
 });
 
 // lib/utils/early-chrome.ts
-var NON_RUN_COMMANDS, isRunCommand, browserFromArgv, earlyChromeProcRef, earlyBrowserPromise;
+var NON_RUN_COMMANDS, isRunCommand, browserFromArgv, openFromArgv, watchFromArgv, openWatchMode, earlyChromeProcRef, earlyBrowserPromise;
 var init_early_chrome = __esm({
   "lib/utils/early-chrome.ts"() {
     init_find_chrome();
@@ -116,13 +117,30 @@ var init_early_chrome = __esm({
     init_perf_logger();
     NON_RUN_COMMANDS = /* @__PURE__ */ new Set(["help", "h", "p", "print", "new", "n", "g", "generate", "init"]);
     isRunCommand = Boolean(process.argv[2]) && !NON_RUN_COMMANDS.has(process.argv[2]);
-    browserFromArgv = process.argv.find((arg) => arg.startsWith("--browser="))?.split("=")[1] || "chromium";
+    ({ browserFromArgv, openFromArgv, watchFromArgv } = process.argv.reduce(
+      (flags, arg) => {
+        if (arg.startsWith("--browser=")) flags.browserFromArgv = arg.slice(10);
+        else if (arg === "--open" || arg === "-o") flags.openFromArgv = true;
+        else if (arg === "--watch" || arg === "-w") flags.watchFromArgv = true;
+        return flags;
+      },
+      { browserFromArgv: "chromium", openFromArgv: false, watchFromArgv: false }
+    ));
+    openWatchMode = openFromArgv && watchFromArgv;
     earlyChromeProcRef = null;
-    process.on("exit", () => earlyChromeProcRef?.kill());
+    if (!openWatchMode) {
+      process.on("exit", () => {
+        if (!earlyChromeProcRef) return;
+        try {
+          earlyChromeProcRef.kill("SIGKILL");
+        } catch {
+        }
+      });
+    }
     perfLog("early-chrome.js: module evaluated");
     earlyBrowserPromise = isRunCommand && browserFromArgv === "chromium" ? findChrome().then((chromePath) => {
       perfLog("early-chrome.js: findChrome resolved", chromePath);
-      return preLaunchChrome(chromePath, chromium_args_default);
+      return preLaunchChrome(chromePath, chromium_args_default, !openWatchMode);
     }).then((info) => {
       perfLog("early-chrome.js: Chrome CDP ready", info?.cdpEndpoint ?? null);
       if (info) earlyChromeProcRef = info.proc;
@@ -220,6 +238,37 @@ var init_find_internal_assets_from_html = __esm({
   }
 });
 
+// lib/utils/html-content-marker.ts
+function findHTMLContentMarker(html) {
+  return html.includes(HTML_CONTENT_MARKER) ? HTML_CONTENT_MARKER : void 0;
+}
+function htmlHasDynamicContentMarker(html) {
+  return !!findHTMLContentMarker(html) || HANDLEBARS_TOKEN_REGEX.test(html);
+}
+function replaceHTMLContentMarker(html, content) {
+  const marker = findHTMLContentMarker(html);
+  if (marker) {
+    return html.replace(marker, content);
+  }
+  if (htmlHasDynamicContentMarker(html)) {
+    if (html.includes("</body>")) {
+      return html.replace("</body>", `${content}</body>`);
+    }
+    if (html.includes("</html>")) {
+      return html.replace("</html>", `${content}</html>`);
+    }
+    return `${html}${content}`;
+  }
+  return html;
+}
+var HTML_CONTENT_MARKER, HANDLEBARS_TOKEN_REGEX;
+var init_html_content_marker = __esm({
+  "lib/utils/html-content-marker.ts"() {
+    HTML_CONTENT_MARKER = "{{qunitxScript}}";
+    HANDLEBARS_TOKEN_REGEX = /{{\s*[^}]+\s*}}/;
+  }
+});
+
 // lib/tap/dump-yaml.ts
 function needsQuoting(str) {
   return NEEDS_QUOTING.test(str);
@@ -354,7 +403,19 @@ var init_display_test_result = __esm({
 
 // lib/setup/bind-server-to-port.ts
 async function bindServerToPort(server, config) {
-  await server.listen(0);
+  let port = config.port;
+  while (true) {
+    try {
+      await server.listen(port);
+      break;
+    } catch (err) {
+      if (err.code === "EADDRINUSE" && !config.portExplicit) {
+        port++;
+        continue;
+      }
+      throw err;
+    }
+  }
   config.port = server._server.address().port;
   return server;
 }
@@ -440,6 +501,7 @@ var init_http = __esm({
         });
         this.wss = new WebSocketServer({ server: this._server });
         this.wss.on("error", (error) => {
+          if (error.code === "EADDRINUSE") return;
           console.log("# [WebSocketServer] Error:");
           console.log(error);
         });
@@ -611,10 +673,17 @@ import path3 from "node:path";
 function setupWebServer(config, cachedContent) {
   const STATIC_FILES_PATH = path3.join(config.projectRoot, config.output);
   const server = new HTTPServer();
+  const mainHTMLWithReplacedAssets = replaceAssetPaths(
+    cachedContent.mainHTML.html,
+    cachedContent.mainHTML.filePath,
+    config.projectRoot
+  );
   server.wss.on("connection", function connection(socket) {
     socket.on("message", function message(data) {
       const { event, details, abort } = JSON.parse(data);
-      if (event === "connection") {
+      if (event === "wsOpen") {
+        config._onWsOpen?.();
+      } else if (event === "connection") {
         if (!config._groupMode) console.log("TAP version 13");
         config._resetTestTimeout?.();
       } else if (event === "testEnd" && !abort) {
@@ -631,17 +700,46 @@ function setupWebServer(config, cachedContent) {
       }
     });
   });
+  server.get("/tests.js", (_req, res) => {
+    const bytes = cachedContent.allTestCode?.length ?? null;
+    console.log(
+      `# [HTTPServer] GET /tests.js \u2192 ${bytes !== null ? `${bytes} bytes` : "NOT READY (allTestCode is null)"}`
+    );
+    if (bytes === null) {
+      res.writeHead(503, { "Content-Type": "application/javascript", "Cache-Control": "no-store" });
+      res.end(
+        'console.error("[qunitx] /tests.js requested before bundle was built \u2014 allTestCode is null");'
+      );
+      return;
+    }
+    config._onTestsJsServed?.();
+    res.writeHead(200, { "Content-Type": "application/javascript", "Cache-Control": "no-store" });
+    res.end(cachedContent.allTestCode);
+  });
+  server.get("/filtered-tests.js", (_req, res) => {
+    const bytes = cachedContent.filteredTestCode?.length ?? null;
+    console.log(
+      `# [HTTPServer] GET /filtered-tests.js \u2192 ${bytes !== null ? `${bytes} bytes` : "NOT READY (filteredTestCode is null)"}`
+    );
+    if (bytes === null) {
+      res.writeHead(503, { "Content-Type": "application/javascript", "Cache-Control": "no-store" });
+      res.end(
+        'console.error("[qunitx] /filtered-tests.js requested before bundle was built \u2014 filteredTestCode is null");'
+      );
+      return;
+    }
+    config._onTestsJsServed?.();
+    res.writeHead(200, { "Content-Type": "application/javascript", "Cache-Control": "no-store" });
+    res.end(cachedContent.filteredTestCode);
+  });
   server.get("/", async (_req, res) => {
     const TEST_RUNTIME_TO_INJECT = testRuntimeToInject(config.port, config);
     const htmlContent = escapeAndInjectTestsToHTML(
-      replaceAssetPaths(
-        cachedContent.mainHTML.html,
-        cachedContent.mainHTML.filePath,
-        config.projectRoot
-      ),
+      mainHTMLWithReplacedAssets,
       TEST_RUNTIME_TO_INJECT,
-      cachedContent.allTestCode
+      "./tests.js"
     );
+    res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-store" });
     res.write(htmlContent);
     res.end();
     return await fsPromise.writeFile(
@@ -652,14 +750,11 @@ function setupWebServer(config, cachedContent) {
   server.get("/qunitx.html", async (_req, res) => {
     const TEST_RUNTIME_TO_INJECT = testRuntimeToInject(config.port, config);
     const htmlContent = escapeAndInjectTestsToHTML(
-      replaceAssetPaths(
-        cachedContent.mainHTML.html,
-        cachedContent.mainHTML.filePath,
-        config.projectRoot
-      ),
+      mainHTMLWithReplacedAssets,
       TEST_RUNTIME_TO_INJECT,
-      cachedContent.filteredTestCode
+      "./filtered-tests.js"
     );
+    res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-store" });
     res.write(htmlContent);
     res.end();
     return await fsPromise.writeFile(
@@ -674,8 +769,9 @@ function setupWebServer(config, cachedContent) {
       const htmlContent = escapeAndInjectTestsToHTML(
         possibleDynamicHTML,
         TEST_RUNTIME_TO_INJECT,
-        cachedContent.allTestCode
+        "/tests.js"
       );
+      res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-store" });
       res.write(htmlContent);
       res.end();
       return await fsPromise.writeFile(
@@ -715,8 +811,31 @@ function testRuntimeToInject(port, config) {
     }, 1000);
 
     (function() {
+      // wsOpenStatus: true once the WebSocket 'open' event fires (or immediately for static files).
+      // testsLoaded: true once tests.js has executed and dispatched 'qunitx:tests-ready'.
+      // Both must be true before setupQUnit() is called, ensuring QUnit.start() only runs
+      // after all test modules are registered.
+      let wsOpenStatus = window.location.protocol === 'file:';
+      let testsLoaded = false;
+
+      function maybeStart() {
+        if (wsOpenStatus && testsLoaded) setupQUnit();
+      }
+
+      // tests.js (loaded as an async external script) dispatches this event after registering
+      // all test modules. Decoupled from WS so Chrome can compile tests.js in a background
+      // thread while the main thread handles the WebSocket handshake.
+      window.addEventListener('qunitx:tests-ready', function() {
+        testsLoaded = true;
+        maybeStart();
+      });
+
+      // For static files (file:// protocol) there is no WebSocket server.
+      // wsOpenStatus is already true above; setupQUnit fires when tests load.
+      if (window.location.protocol === 'file:') return;
+
       let wsRetryCount = 0;
-      const WS_MAX_RETRIES = 50; // 500ms total before giving up
+      const WS_MAX_RETRIES = Math.ceil(${config.timeout} / 10); // retry for the full test timeout window
 
       function setupWebSocket() {
         try {
@@ -728,7 +847,14 @@ function testRuntimeToInject(port, config) {
         }
 
         window.socket.addEventListener('open', function() {
-          setupQUnit();
+          wsOpenStatus = true;
+          // Notify Node.js that the WS socket is open. This fires immediately (< 1 s) because
+          // this runtime script is tiny \u2014 tests.js background compilation hasn't finished yet.
+          // Node.js uses this to distinguish "WS never connected" from "WS connected but bundle slow".
+          if (window.IS_PLAYWRIGHT) {
+            window.socket.send(JSON.stringify({ event: 'wsOpen' }));
+          }
+          maybeStart();
         });
         window.socket.addEventListener('error', function() {
           retryOrFail();
@@ -757,8 +883,6 @@ function testRuntimeToInject(port, config) {
       setupWebSocket();
     })();
 
-    {{allTestCode}}
-
     function getCircularReplacer() {
       const ancestors = [];
       return function (key, value) {
@@ -829,17 +953,18 @@ function testRuntimeToInject(port, config) {
     }
   </script>`;
 }
-function escapeAndInjectTestsToHTML(html, testRuntimeCode, testContentCode) {
-  return html.replace(
-    "{{content}}",
-    testRuntimeCode.replace("{{allTestCode}}", testContentCode).replace("</script>", "</script>")
-    // NOTE: remove this when simple-html-tokenizer PR gets merged
+function escapeAndInjectTestsToHTML(html, testRuntimeCode, testBundleUrl) {
+  return replaceHTMLContentMarker(
+    html,
+    `${testRuntimeCode}
+<script src="${testBundleUrl}" async></script>`
   );
 }
 var fsPromise;
 var init_web_server = __esm({
   "lib/setup/web-server.ts"() {
     init_find_internal_assets_from_html();
+    init_html_content_marker();
     init_display_test_result();
     init_path_exists();
     init_http();
@@ -869,12 +994,28 @@ async function launchBrowser(config) {
       return browser;
     }
     const executablePath = await findChrome();
-    const launchOptions = { args: chromium_args_default, headless: true };
+    const launchOptions = {
+      args: chromium_args_default,
+      headless: true,
+      // Disable Playwright's async SIGTERM/SIGHUP handlers. When the CLI is killed by an
+      // external signal (e.g. exec() timeout in tests), those handlers start an async browser
+      // graceful-close that can hang indefinitely on CI, preventing the process from exiting
+      // and blocking the test runner. With these disabled, Node.js's default signal behaviour
+      // (synchronous process.exit) runs instead, and Playwright's synchronous exitHandler
+      // (registered via process.on('exit')) still kills the browser correctly.
+      handleSIGTERM: false,
+      handleSIGHUP: false
+    };
     if (executablePath) launchOptions.executablePath = executablePath;
     return playwrightCore2.chromium.launch(launchOptions);
   }
   const playwrightCore = await playwrightCorePromise;
-  return playwrightCore[browserName].launch({ headless: true });
+  return playwrightCore[browserName].launch({
+    headless: !(config.open && config.watch),
+    // See comment in the chromium fallback path above for why these are disabled.
+    handleSIGTERM: false,
+    handleSIGHUP: false
+  });
 }
 async function setupBrowser(config, cachedContent, existingBrowser = null) {
   const setupStart = Date.now();
@@ -891,7 +1032,9 @@ async function setupBrowser(config, cachedContent, existingBrowser = null) {
     window.IS_PLAYWRIGHT = true;
   });
   page.on("console", async (msg) => {
-    if (!config.debug) return;
+    const type = msg.type();
+    const alwaysShow = type === "warning" || type === "error";
+    if (!alwaysShow && !config.debug) return;
     try {
       const values = await Promise.all(msg.args().map((arg) => arg.jsonValue()));
       console.log(...values);
@@ -919,6 +1062,42 @@ var init_browser = __esm({
   }
 });
 
+// lib/utils/open-output-in-browser.ts
+import { spawn as spawn2 } from "node:child_process";
+async function openOutputInBrowser(config) {
+  try {
+    const outputFile = config.watch ? `http://localhost:${config.port}` : `file://${config.projectRoot}/${config.output}/index.html`;
+    if (typeof config.open === "string") {
+      spawnDetached(config.open, [outputFile]);
+      return;
+    }
+    const browserName = config.browser || "chromium";
+    if (browserName === "firefox") {
+      spawnDetached("firefox", [outputFile]);
+      return;
+    }
+    if (browserName === "webkit") {
+      if (process.platform === "darwin") spawnDetached("open", ["-a", "Safari", outputFile]);
+      return;
+    }
+    const chromePath = await findChrome() ?? (await import("playwright-core")).chromium.executablePath();
+    if (chromePath) spawnDetached(chromePath, [outputFile]);
+  } catch (err) {
+    console.error("# Warning: --open could not launch browser:", err);
+  }
+}
+function spawnDetached(cmd, args) {
+  const child = spawn2(cmd, args, { detached: true, stdio: "ignore" });
+  child.on("error", () => {
+  });
+  child.unref();
+}
+var init_open_output_in_browser = __esm({
+  "lib/utils/open-output-in-browser.ts"() {
+    init_find_chrome();
+  }
+});
+
 // lib/utils/time-counter.ts
 function timeCounter() {
   const startTime = /* @__PURE__ */ new Date();
@@ -974,18 +1153,31 @@ import esbuild from "esbuild";
 async function buildTestBundle(config, cachedContent) {
   const { projectRoot, output } = config;
   const allTestFilePaths = Object.keys(config.fsTree);
+  if (allTestFilePaths.length === 0) {
+    console.log("# [buildTestBundle] fsTree is empty \u2014 skipping build (no test files found)");
+    return;
+  }
+  const outfile = `${projectRoot}/${output}/tests.js`;
   await Promise.all([
-    esbuild.build({
-      stdin: {
-        contents: allTestFilePaths.map((f) => `import "${f}";`).join(""),
-        resolveDir: process.cwd()
+    buildWithOverlayfsRetry(
+      {
+        stdin: {
+          contents: allTestFilePaths.map((f) => `import "${f}";`).join(""),
+          resolveDir: process.cwd()
+        },
+        bundle: true,
+        logLevel: "error",
+        outfile,
+        keepNames: true,
+        sourcemap: config.debug ? "inline" : config.watch ? "linked" : false,
+        // Signal the runtime that all test modules are registered. The runtime's maybeStart()
+        // waits for both this event and the WebSocket 'open' event before calling QUnit.start().
+        // Dispatching from the bundle (rather than from a script onload attr) is reliable across
+        // all browsers and does not require changes to user test code.
+        footer: { js: 'window.dispatchEvent(new CustomEvent("qunitx:tests-ready"));' }
       },
-      bundle: true,
-      logLevel: "error",
-      outfile: `${projectRoot}/${output}/tests.js`,
-      keepNames: true,
-      sourcemap: config.debug || config.watch ? "inline" : false
-    }),
+      outfile
+    ),
     Promise.all(
       cachedContent.htmlPathsToRunTests.map(async (htmlPath) => {
         const targetPath = `${config.projectRoot}/${config.output}${htmlPath}`;
@@ -996,7 +1188,7 @@ async function buildTestBundle(config, cachedContent) {
       })
     )
   ]);
-  cachedContent.allTestCode = await fs8.readFile(`${projectRoot}/${output}/tests.js`);
+  cachedContent.allTestCode = await fs8.readFile(outfile);
 }
 async function runTestsInBrowser(config, cachedContent = {}, connections, targetTestFilesToFilter) {
   const { projectRoot, output } = config;
@@ -1010,6 +1202,9 @@ async function runTestsInBrowser(config, cachedContent = {}, connections, target
     if (!cachedContent.allTestCode) {
       await buildTestBundle(config, cachedContent);
     }
+    if (!cachedContent.allTestCode) {
+      return connections;
+    }
     if (runHasFilter) {
       const outputPath = `${projectRoot}/${output}/filtered-tests.js`;
       await buildFilteredTests(targetTestFilesToFilter, outputPath, config);
@@ -1052,34 +1247,78 @@ async function runTestsInBrowser(config, cachedContent = {}, connections, target
   return connections;
 }
 function buildFilteredTests(filteredTests, outputPath, config) {
-  return esbuild.build({
-    stdin: {
-      contents: filteredTests.map((f) => `import "${f}";`).join(""),
-      resolveDir: process.cwd()
+  return buildWithOverlayfsRetry(
+    {
+      stdin: {
+        contents: filteredTests.map((f) => `import "${f}";`).join(""),
+        resolveDir: process.cwd()
+      },
+      bundle: true,
+      logLevel: "error",
+      outfile: outputPath,
+      sourcemap: config.debug ? "inline" : config.watch ? "linked" : false,
+      footer: { js: 'window.dispatchEvent(new CustomEvent("qunitx:tests-ready"));' }
     },
-    bundle: true,
-    logLevel: "error",
-    outfile: outputPath,
-    sourcemap: config.debug || config.watch ? "inline" : false
-  });
+    outputPath
+  );
+}
+async function buildWithOverlayfsRetry(options, outfile) {
+  const RETRY_DELAY_MS = 100;
+  const MAX_RETRIES = 3;
+  const EMPTY_BUNDLE_THRESHOLD = 500;
+  let result = await esbuild.build(options);
+  for (let retry = 1; retry <= MAX_RETRIES; retry++) {
+    const bytes2 = (await fs8.stat(outfile)).size;
+    if (bytes2 >= EMPTY_BUNDLE_THRESHOLD) return result;
+    console.log(
+      `# [buildWithOverlayfsRetry] bundle is ${bytes2} bytes (< ${EMPTY_BUNDLE_THRESHOLD}) on attempt ${retry}/${MAX_RETRIES} \u2014 overlayfs flush race, retrying in ${RETRY_DELAY_MS}ms`
+    );
+    await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+    result = await esbuild.build(options);
+  }
+  const bytes = (await fs8.stat(outfile)).size;
+  if (bytes < EMPTY_BUNDLE_THRESHOLD) {
+    console.log(
+      `# [buildWithOverlayfsRetry] bundle is ${bytes} bytes after ${MAX_RETRIES} retries \u2014 proceeding`
+    );
+  }
+  return result;
 }
 async function runTestInsideHTMLFile(filePath, { page, server, browser }, config) {
   let QUNIT_RESULT;
   let targetError;
   let timeoutHandle;
+  let wsConnected = false;
   try {
     console.log("#", blue(`QUnitX running: http://localhost:${config.port}${filePath}`));
+    let resolveTestRace;
     const testRaceResult = new Promise((resolve) => {
-      config._testRunDone = () => resolve(false);
-      config._resetTestTimeout = () => {
-        clearTimeout(timeoutHandle);
-        timeoutHandle = setTimeout(() => resolve(true), config.timeout);
-      };
-    });
-    await page.goto(`http://localhost:${config.port}${filePath}`, {
-      timeout: config.timeout + 1e4
+      resolveTestRace = resolve;
     });
-    config._resetTestTimeout();
+    config._testRunDone = resolveTestRace;
+    config._onWsOpen = () => {
+      wsConnected = true;
+      clearTimeout(timeoutHandle);
+      timeoutHandle = setTimeout(resolveTestRace, config.timeout * 3);
+    };
+    config._onTestsJsServed = () => {
+      clearTimeout(timeoutHandle);
+      timeoutHandle = setTimeout(resolveTestRace, config.timeout * 4);
+    };
+    config._resetTestTimeout = () => {
+      wsConnected = true;
+      clearTimeout(timeoutHandle);
+      timeoutHandle = setTimeout(resolveTestRace, config.timeout);
+    };
+    const targetUrl = `http://localhost:${config.port}${filePath}`;
+    const navOptions = { timeout: config.timeout + 1e4, waitUntil: "commit" };
+    if (page.url().split("?")[0] === targetUrl) {
+      await page.reload(navOptions);
+    } else {
+      await page.goto(targetUrl, navOptions);
+    }
+    clearTimeout(timeoutHandle);
+    timeoutHandle = setTimeout(resolveTestRace, config.timeout * 3);
     await testRaceResult;
     QUNIT_RESULT = await page.evaluate(() => window.QUNIT_RESULT);
   } catch (error) {
@@ -1088,15 +1327,23 @@ async function runTestInsideHTMLFile(filePath, { page, server, browser }, config
     console.error(error);
   } finally {
     clearTimeout(timeoutHandle);
+    config._onWsOpen = null;
+    config._onTestsJsServed = null;
     config._resetTestTimeout = null;
+    config._testRunDone = null;
   }
   if (!QUNIT_RESULT || QUNIT_RESULT.totalTests === 0) {
-    console.log(targetError);
+    if (targetError) console.log(targetError);
+    const wsReason = !wsConnected ? "WebSocket connection never received \u2014 Chrome may be CPU-starved or the page failed to load" : "WebSocket connected but no tests ran \u2014 QUnit may have failed to start";
+    console.log(`# TIMEOUT: ${wsReason}`);
     console.log("BROWSER: runtime error thrown during executing tests");
     console.error("BROWSER: runtime error thrown during executing tests");
     await failOnNonWatchMode(config.watch, { server, browser }, config._groupMode);
   } else if (QUNIT_RESULT.totalTests > QUNIT_RESULT.finishedTests) {
-    console.log(targetError);
+    if (targetError) console.log(targetError);
+    console.log(
+      `# TIMEOUT: test stalled after ${QUNIT_RESULT.finishedTests}/${QUNIT_RESULT.totalTests} finished \u2014 last active: ${QUNIT_RESULT.currentTest}`
+    );
     console.log(`BROWSER: TEST TIMED OUT: ${QUNIT_RESULT.currentTest}`);
     console.error(`BROWSER: TEST TIMED OUT: ${QUNIT_RESULT.currentTest}`);
     await failOnNonWatchMode(config.watch, { server, browser }, config._groupMode);
@@ -1139,12 +1386,21 @@ import { stat } from "node:fs/promises";
 import path4 from "node:path";
 function setupFileWatchers(testFileLookupPaths, config, onEventFunc, onFinishFunc) {
   const extensions = config.extensions || ["js", "ts"];
+  const readyPromises = [];
+  const parentWatchers = [];
   const fileWatchers = testFileLookupPaths.reduce((watchers, watchPath) => {
     let ready = false;
-    const watcher = fs9.watch(watchPath, { recursive: true }, async (eventType, filename) => {
+    const lastChangeMs = {};
+    const CHANGE_DEDUPE_MS = 30;
+    const childWatcher = fs9.watch(watchPath, { recursive: true }, async (eventType, filename) => {
       if (!ready || !filename) return;
       const fullPath = path4.join(watchPath, filename);
       if (eventType === "change") {
+        if (!config._building) {
+          const now = Date.now();
+          if (now - (lastChangeMs[fullPath] ?? 0) < CHANGE_DEDUPE_MS) return;
+          lastChangeMs[fullPath] = now;
+        }
         return handleWatchEvent(config, extensions, "change", fullPath, onEventFunc, onFinishFunc);
       }
       try {
@@ -1158,19 +1414,55 @@ function setupFileWatchers(testFileLookupPaths, config, onEventFunc, onFinishFun
           onFinishFunc
         );
       } catch {
-        const event = config.fsTree && fullPath in config.fsTree ? "unlink" : "unlinkDir";
-        handleWatchEvent(config, extensions, event, fullPath, onEventFunc, onFinishFunc);
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        try {
+          const s = await stat(fullPath);
+          handleWatchEvent(
+            config,
+            extensions,
+            s.isDirectory() ? "addDir" : "add",
+            fullPath,
+            onEventFunc,
+            onFinishFunc
+          );
+          return;
+        } catch {
+        }
+        if (!(config.fsTree && fullPath in config.fsTree)) return;
+        handleWatchEvent(config, extensions, "unlink", fullPath, onEventFunc, onFinishFunc);
       }
     });
-    setImmediate(() => {
-      ready = true;
+    const parentDir = path4.dirname(watchPath);
+    const watchedBasename = path4.basename(watchPath);
+    const parentWatcher = fs9.watch(parentDir, async (eventType, filename) => {
+      if (!ready || filename !== watchedBasename || eventType !== "rename") return;
+      try {
+        await stat(watchPath);
+      } catch {
+        handleWatchEvent(config, extensions, "unlinkDir", watchPath, onEventFunc, onFinishFunc);
+        childWatcher.close();
+        parentWatcher.close();
+        delete watchers[watchPath];
+      }
     });
-    return Object.assign(watchers, { [watchPath]: watcher });
+    parentWatchers.push(parentWatcher);
+    readyPromises.push(
+      new Promise(
+        (resolve) => setImmediate(() => {
+          ready = true;
+          resolve();
+        })
+      )
+    );
+    return Object.assign(watchers, { [watchPath]: childWatcher });
   }, {});
   return {
     fileWatchers,
+    ready: Promise.all(readyPromises).then(() => {
+    }),
     killFileWatchers() {
-      Object.keys(fileWatchers).forEach((watcherKey) => fileWatchers[watcherKey].close());
+      Object.keys(fileWatchers).forEach((key) => fileWatchers[key].close());
+      parentWatchers.forEach((pw) => pw.close());
       return fileWatchers;
     }
   };
@@ -1199,7 +1491,16 @@ function handleWatchEvent(config, extensions, event, filePath, onEventFunc, onFi
       onFinishFunc ? onFinishFunc(event, filePath) : null;
     }).catch((error) => {
       console.error("#", red("Build error:"), error.message || error);
-    }).finally(() => config._building = false);
+    }).finally(() => {
+      config._building = false;
+      if (config._pendingBuildTrigger) {
+        const trigger = config._pendingBuildTrigger;
+        config._pendingBuildTrigger = null;
+        trigger();
+      }
+    });
+  } else {
+    config._pendingBuildTrigger = () => handleWatchEvent(config, extensions, event, filePath, onEventFunc, onFinishFunc);
   }
 }
 function mutateFSTree(fsTree, event, path5) {
@@ -1346,6 +1647,9 @@ async function run(config) {
     ]);
     config.expressApp = connections.server;
     setupKeyboardEvents(config, cachedContent, connections);
+    if (config.open) {
+      void openOutputInBrowser(config);
+    }
     if (config.before) {
       await runUserModule(`${process.cwd()}/${config.before}`, config, "before");
     }
@@ -1358,19 +1662,24 @@ async function run(config) {
       ]);
       throw error;
     }
+    if (config.watch) {
+      const { ready: watcherReady } = setupFileWatchers(
+        config.testFileLookupPaths,
+        config,
+        async (event, file) => {
+          if (event === "addDir") return;
+          if (["change", "unlink", "unlinkDir"].includes(event)) {
+            if (event === "change" && !(file in config.fsTree)) return;
+            cachedContent.allTestCode = null;
+            return await runTestsInBrowser(config, cachedContent, connections);
+          }
+          await runTestsInBrowser(config, cachedContent, connections, [file]);
+        },
+        (_path, _event) => connections.server.publish("refresh", "refresh")
+      );
+      await watcherReady;
+    }
     logWatcherAndKeyboardShortcutInfo(config, connections.server);
-    await setupFileWatchers(
-      config.testFileLookupPaths,
-      config,
-      async (event, file) => {
-        if (event === "addDir") return;
-        if (["unlink", "unlinkDir"].includes(event)) {
-          return await runTestsInBrowser(config, cachedContent, connections);
-        }
-        await runTestsInBrowser(config, cachedContent, connections, [file]);
-      },
-      (_path, _event) => connections.server.publish("refresh", "refresh")
-    );
   } else {
     const allFiles = Object.keys(config.fsTree);
     const groupCount = Math.min(allFiles.length, availableParallelism());
@@ -1397,6 +1706,9 @@ async function run(config) {
         )
       )
     ]);
+    if (config.open) {
+      void openOutputInBrowser(config);
+    }
     const TIME_COUNTER = timeCounter();
     const GROUP_TIMEOUT_MS = 3 * 60 * 1e3;
     const keepAlive = setInterval(() => {
@@ -1473,14 +1785,14 @@ async function buildCachedContent(config, htmlPaths) {
       if (buffer === null) return result;
       const filePath = config.htmlPaths[index];
       const html = buffer.toString();
-      if (html.includes("{{content}}")) {
+      if (htmlHasDynamicContentMarker(html)) {
         result.dynamicContentHTMLs[filePath] = html;
         result.htmlPathsToRunTests.push(filePath.replace(config.projectRoot, ""));
       } else {
         console.log(
           "#",
           yellow(
-            `WARNING: Static html file with no {{content}} detected. Therefore ignoring ${filePath}`
+            `WARNING: Static html file with no {{qunitxScript}} or handlebars-style tokens detected. Therefore ignoring ${filePath}`
           )
         );
         result.staticHTMLs[filePath] = html;
@@ -1524,9 +1836,10 @@ function splitIntoGroups(files, groupCount) {
   return groups.filter((g) => g.length > 0);
 }
 function logWatcherAndKeyboardShortcutInfo(config, _server) {
+  const prefix = "Watching files...";
   console.log(
     "#",
-    blue(`Watching files... You can browse the tests on http://localhost:${config.port} ...`)
+    blue(`${prefix} You can browse the tests on http://localhost:${config.port} ...`)
   );
   console.log(
     "#",
@@ -1542,6 +1855,7 @@ function normalizeInternalAssetPathFromHTML(projectRoot, assetPath, htmlPath) {
 var init_run = __esm({
   "lib/commands/run.ts"() {
     init_browser();
+    init_open_output_in_browser();
     init_color();
     init_tests_in_browser();
     init_file_watcher();
@@ -1552,6 +1866,7 @@ var init_run = __esm({
     init_time_counter();
     init_display_final_result();
     init_read_boilerplate();
+    init_html_content_marker();
   }
 });
 
@@ -1566,7 +1881,7 @@ init_color();
 var package_default = {
   name: "qunitx-cli",
   type: "module",
-  version: "0.9.10",
+  version: "0.11.0",
   description: "Browser runner for QUnitx: run your qunitx tests in google-chrome",
   author: "Izel Nakri",
   license: "MIT",
@@ -1595,9 +1910,10 @@ var package_default = {
     "changelog:unreleased": "git-cliff --unreleased --strip all",
     "changelog:preview": "git-cliff",
     "changelog:update": "git-cliff --output CHANGELOG.md",
-    postinstall: "deno install --allow-scripts=npm:playwright-core || true",
+    postinstall: "PLAYWRIGHT_SKIP_DOWNLOAD=true deno install --allow-scripts=npm:playwright-core || true",
     test: `node --experimental-strip-types test/setup.ts && FORCE_COLOR=0 node --experimental-strip-types --test --test-concurrency=$(node -p 'require("os").availableParallelism()') test/**/*-test.ts`,
     "test:browser": `node --experimental-strip-types test/setup.ts && FORCE_COLOR=0 node --experimental-strip-types --test --test-concurrency=$(node -p 'require("os").availableParallelism()') test/flags/*-test.ts test/inputs/*-test.ts`,
+    "test:release": "bash scripts/test-release.sh",
     "test:sanity-first": "./cli.ts test/helpers/failing-tests.js test/helpers/failing-tests.ts",
     "test:sanity-second": "./cli.ts test/helpers/passing-tests.js test/helpers/passing-tests.ts"
   },
@@ -1613,16 +1929,16 @@ var package_default = {
     url: "git+https://github.com/izelnakri/qunitx-cli.git"
   },
   dependencies: {
-    esbuild: "^0.27.3",
-    "playwright-core": "^1.58.2",
+    esbuild: "^0.28.0",
+    "playwright-core": "^1.59.1",
     ws: "^8.20.0"
   },
   devDependencies: {
     cors: "^2.8.6",
     express: "^5.2.1",
     "js-yaml": "^4.1.1",
-    prettier: "^3.8.1",
-    qunitx: "^1.1.2",
+    prettier: "^3.8.2",
+    qunitx: "^1.2.1",
     typescript: "^6.0.2"
   },
   volta: {
@@ -1654,6 +1970,7 @@ ${highlight("Input options:")}
 ${highlight("Optional flags:")}
 ${color("--debug")} : print console output when tests run in browser
 ${color("--watch")} : run the target file or folders, watch them for continuous run and expose http server under localhost
+${color("--open")} : run tests in a visible browser window instead of headless; keeps the server alive (short: ${color("-o")})
 ${color("--timeout")} : change default timeout per test case
 ${color("--output")} : folder to distribute built qunitx html and js that a webservers can run[default: tmp]
 ${color("--failFast")} : run the target file or folders with immediate abort if a single test fails
@@ -1902,6 +2219,10 @@ function parseCliFlags(projectRoot) {
         return Object.assign(result, { debug: parseBoolean(arg.split("=")[1]) });
       } else if (arg.startsWith("--watch")) {
         return Object.assign(result, { watch: parseBoolean(arg.split("=")[1]) });
+      } else if (arg === "-o" || arg.startsWith("-o=") || arg.startsWith("--open")) {
+        const value = arg.split("=")[1];
+        const open = value === void 0 || value === "true" ? true : value === "false" ? false : value;
+        return Object.assign(result, { open });
       } else if (arg.startsWith("--failfast") || arg.startsWith("--failFast")) {
         return Object.assign(result, { failFast: parseBoolean(arg.split("=")[1]) });
       } else if (arg.startsWith("--timeout")) {
@@ -1916,7 +2237,7 @@ function parseCliFlags(projectRoot) {
         }
         return result;
       } else if (arg.startsWith("--port")) {
-        return Object.assign(result, { port: Number(arg.split("=")[1]) });
+        return Object.assign(result, { port: Number(arg.split("=")[1]), portExplicit: true });
       } else if (arg.startsWith("--extensions")) {
         return Object.assign(result, {
           extensions: arg.split("=")[1].split(",").map((e) => e.trim())
@@ -1937,6 +2258,10 @@ function parseCliFlags(projectRoot) {
       } else if (arg === "--trace-perf") {
         return result;
       }
+      if (arg.startsWith("-")) {
+        console.warn(`# Warning: Unknown flag "${arg}" \u2014 ignored`);
+        return result;
+      }
       result.inputs.add(arg.startsWith(projectRoot) ? arg : `${process.cwd()}/${arg}`);
       return result;
     },
@@ -1977,7 +2302,9 @@ async function setupConfig() {
     lastRanTestFiles: null,
     COUNTER: { testCount: 0, failCount: 0, skipCount: 0, passCount: 0, errorCount: 0 },
     _testRunDone: null,
-    _resetTestTimeout: null
+    _resetTestTimeout: null,
+    _onWsOpen: null,
+    _onTestsJsServed: null
   };
   config.htmlPaths = normalizeHTMLPaths(config.projectRoot, config.htmlPaths);
   config.fsTree = await buildFSTree(config.testFileLookupPaths, config);
@@ -2000,6 +2327,8 @@ process4.title = "qunitx";
 (async () => {
   if (!process4.argv[2]) {
     return await displayHelpOutput();
+  } else if (["--version", "-v", "version"].includes(process4.argv[2])) {
+    return process4.stdout.write(package_default.version + "\n");
   } else if (["help", "h", "p", "print"].includes(process4.argv[2])) {
     return await displayHelpOutput();
   } else if (["new", "n", "g", "generate"].includes(process4.argv[2])) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "qunitx-cli",
   "type": "module",
-  "version": "0.9.10",
+  "version": "0.11.0",
   "description": "Browser runner for QUnitx: run your qunitx tests in google-chrome",
   "author": "Izel Nakri",
   "license": "MIT",
@@ -30,9 +30,10 @@
     "changelog:unreleased": "git-cliff --unreleased --strip all",
     "changelog:preview": "git-cliff",
     "changelog:update": "git-cliff --output CHANGELOG.md",
-    "postinstall": "deno install --allow-scripts=npm:playwright-core || true",
+    "postinstall": "PLAYWRIGHT_SKIP_DOWNLOAD=true deno install --allow-scripts=npm:playwright-core || true",
     "test": "node --experimental-strip-types test/setup.ts && FORCE_COLOR=0 node --experimental-strip-types --test --test-concurrency=$(node -p 'require(\"os\").availableParallelism()') test/**/*-test.ts",
     "test:browser": "node --experimental-strip-types test/setup.ts && FORCE_COLOR=0 node --experimental-strip-types --test --test-concurrency=$(node -p 'require(\"os\").availableParallelism()') test/flags/*-test.ts test/inputs/*-test.ts",
+    "test:release": "bash scripts/test-release.sh",
     "test:sanity-first": "./cli.ts test/helpers/failing-tests.js test/helpers/failing-tests.ts",
     "test:sanity-second": "./cli.ts test/helpers/passing-tests.js test/helpers/passing-tests.ts"
   },
@@ -48,16 +49,16 @@
     "url": "git+https://github.com/izelnakri/qunitx-cli.git"
   },
   "dependencies": {
-    "esbuild": "^0.27.3",
-    "playwright-core": "^1.58.2",
+    "esbuild": "^0.28.0",
+    "playwright-core": "^1.59.1",
     "ws": "^8.20.0"
   },
   "devDependencies": {
     "cors": "^2.8.6",
     "express": "^5.2.1",
     "js-yaml": "^4.1.1",
-    "prettier": "^3.8.1",
-    "qunitx": "^1.1.2",
+    "prettier": "^3.8.2",
+    "qunitx": "^1.2.1",
     "typescript": "^6.0.2"
   },
   "volta": {

package/templates/setup/tests.hbs

@@ -10,6 +10,6 @@
     <div id="qunit"></div>
     <div id="qunit-fixture"></div>
 
-    {{content}}
+    {{qunitxScript}}
   </body>
 </html>