qunitx-cli 0.20.0 → 0.21.0

package/README.md

@@ -227,6 +227,117 @@ Options:
   --browser=<name>    Browser engine: chromium (default), firefox, or webkit
 ```
 
+## Timezone
+
+The browser inherits the **OS system timezone** automatically — no Playwright `timezoneId` option is involved. The browser's `Intl.DateTimeFormat().resolvedOptions().timeZone` will match the timezone that Node.js itself reads from the OS.
+
+### Setting a timezone for tests
+
+| Platform | How Chrome resolves the timezone | Override |
+|----------|----------------------------------|---------|
+| **Linux** | glibc reads `TZ` env var first, then `/etc/localtime` | `TZ=America/New_York npx qunitx …` works |
+| **macOS** | CoreFoundation reads the system timezone (ignores `TZ`) | Must set the system timezone: `sudo systemsetup -settimezone America/New_York` |
+| **Windows** | Reads the registry timezone (ignores `TZ`) | Must set the system timezone: `tzutil /s "Eastern Standard Time"` |
+
+On Linux, the `TZ` env var is the simplest way to run tests in a specific timezone:
+
+```sh
+TZ=UTC npx qunitx test/**/*.ts
+TZ=America/Los_Angeles npx qunitx test/**/*.ts
+TZ=Europe/Berlin npx qunitx test/**/*.ts
+```
+
+### CI pitfalls
+
+GitHub Actions (and most CI providers) run with **UTC** by default on all platforms. This is usually what you want for reproducible test results. If your tests assert on specific local times or date formatting, be aware:
+
+**Linux CI** — override with `TZ` in your workflow step:
+
+```yaml
+- run: npx qunitx test/**/*.ts
+  env:
+    TZ: America/New_York
+```
+
+**macOS CI** — `TZ` does not affect Chrome. Set the system timezone before running tests:
+
+```yaml
+- run: sudo systemsetup -settimezone America/New_York
+- run: npx qunitx test/**/*.ts
+```
+
+**Windows CI** — same constraint, use `tzutil`:
+
+```yaml
+- run: tzutil /s "Eastern Standard Time"
+- run: npx qunitx test/**/*.ts
+```
+
+If your test suite does not assert on local times or timezone-sensitive date formatting, none of this matters — the default UTC CI timezone is fine.
+
+### Mocking dates and times in tests
+
+For most cases you do not need to touch system settings or env vars at all. `Date`, `Intl`, and timers are plain browser globals — mock them in a qunitx `before` / `beforeEach` hook just like any other value:
+
+```js
+// test/some-test.ts
+import { module, test } from 'qunitx';
+
+module('Invoice formatting', (hooks) => {
+  let realDate;
+
+  hooks.before(() => {
+    realDate = globalThis.Date;
+    // Pin "now" to a fixed instant for the whole module
+    const FIXED = new realDate('2024-06-01T12:00:00Z');
+    globalThis.Date = class extends realDate {
+      constructor(...args) { super(args.length ? args : [FIXED]); }
+      static now() { return FIXED.getTime(); }
+    };
+  });
+
+  hooks.after(() => { globalThis.Date = realDate; });
+
+  test('formats the current date correctly', (assert) => {
+    assert.equal(new Date().toISOString().slice(0, 10), '2024-06-01');
+  });
+});
+```
+
+For richer control over timers (`setTimeout`, `setInterval`, `requestAnimationFrame`, …) use a fake-timer library such as [Sinon.JS](https://sinonjs.org/releases/latest/fake-timers/):
+
+```js
+import sinon from 'sinon';
+
+module('Debounce logic', (hooks) => {
+  let clock;
+
+  hooks.before(() => { clock = sinon.useFakeTimers({ now: new Date('2024-06-01T00:00:00Z') }); });
+  hooks.after(() => { clock.restore(); });
+
+  test('fires after 300 ms', (assert) => {
+    // clock.tick(300) advances fake time without waiting in real time
+    clock.tick(300);
+    assert.ok(/* your assertion */);
+  });
+});
+```
+
+If you need the mock active across the entire test run rather than inside a single module, put it in a `--before` script:
+
+```js
+// scripts/mock-date.js  (passed as: qunitx … --before=scripts/mock-date.js)
+const realDate = globalThis.Date;
+const FIXED    = new realDate('2024-06-01T12:00:00Z');
+
+globalThis.Date = class extends realDate {
+  constructor(...args) { super(args.length ? args : [FIXED]); }
+  static now() { return FIXED.getTime(); }
+};
+```
+
+This runs in the browser context before any test module loads, so every test in the run sees the mocked `Date` with no changes to the OS, no env vars, and no qunitx-cli configuration.
+
 ## Development
 
 ```sh

package/dist/cli.js

@@ -38,10 +38,11 @@ var init_find_chrome = __esm({
 });
 
 // lib/utils/kill-process-group.ts
+import { spawnSync } from "node:child_process";
 function killProcessGroup(pid) {
   try {
     if (process.platform === "win32") {
-      process.kill(pid, "SIGKILL");
+      spawnSync("taskkill", ["/F", "/T", "/PID", String(pid)], { stdio: "ignore" });
     } else {
       process.kill(-pid, "SIGKILL");
     }
@@ -199,8 +200,11 @@ var init_chromium_args = __esm({
       // ── Sandbox / rendering ──────────────────────────────────────────────────────
       "--no-sandbox",
       // required in most CI/container environments
-      "--disable-gpu",
-      // no GPU in headless; avoids GPU process startup
+      // SwiftShader software WebGL: needed on Linux CI (containerised, no GPU).
+      // Omit on macOS — Chrome uses Metal natively; SwiftShader crashes the renderer
+      // process on macOS arm64, causing "Target page, context or browser has been closed".
+      // Omit on Windows — ANGLE/D3D11 is available and SwiftShader is not needed.
+      ...process.platform === "linux" ? ["--enable-unsafe-swiftshader"] : [],
       // ── Window / UI ──────────────────────────────────────────────────────────────
       "--window-size=1440,900",
       "--hide-scrollbars",
@@ -307,7 +311,13 @@ var init_chrome_prelaunch = __esm({
         else if (arg === "--watch" || arg === "-w") flags.watchFromArgv = true;
         return flags;
       },
-      { browserFromArgv: "chromium", openFromArgv: false, watchFromArgv: false }
+      // QUNITX_BROWSER env var seeds the default so prelaunch is skipped for firefox/webkit
+      // even when --browser is not passed on the command line (e.g. browser-compat CI).
+      {
+        browserFromArgv: process.env.QUNITX_BROWSER || "chromium",
+        openFromArgv: false,
+        watchFromArgv: false
+      }
     ));
     openWatchMode = openFromArgv && watchFromArgv;
     earlyChrome = null;
@@ -318,7 +328,7 @@ var init_chrome_prelaunch = __esm({
       });
     }
     perfLog("chrome-prelaunch.ts: module evaluated");
-    prelaunchPromise = isRunCommand && browserFromArgv === "chromium" ? findChrome().then((chromePath) => {
+    prelaunchPromise = isRunCommand && browserFromArgv === "chromium" && process.platform !== "darwin" ? findChrome().then((chromePath) => {
       perfLog("chrome-prelaunch.ts: findChrome resolved", chromePath);
       return preLaunchChrome(chromePath, CHROMIUM_ARGS, !openWatchMode);
     }).then((info) => {
@@ -922,8 +932,8 @@ var init_http = __esm({
         });
       }
       /** Registers a GET route handler. */
-      get(path7, handler) {
-        this.#registerRouteHandler("GET", path7, handler);
+      get(path10, handler) {
+        this.#registerRouteHandler("GET", path10, handler);
       }
       /**
        * Starts listening on the given port (0 = OS-assigned).
@@ -954,32 +964,32 @@ var init_http = __esm({
         });
       }
       /** Registers a POST route handler. */
-      post(path7, handler) {
-        this.#registerRouteHandler("POST", path7, handler);
+      post(path10, handler) {
+        this.#registerRouteHandler("POST", path10, handler);
       }
       /** Registers a DELETE route handler. */
-      delete(path7, handler) {
-        this.#registerRouteHandler("DELETE", path7, handler);
+      delete(path10, handler) {
+        this.#registerRouteHandler("DELETE", path10, handler);
       }
       /** Registers a PUT route handler. */
-      put(path7, handler) {
-        this.#registerRouteHandler("PUT", path7, handler);
+      put(path10, handler) {
+        this.#registerRouteHandler("PUT", path10, handler);
       }
       /** Adds a middleware function to the chain. */
       use(middleware) {
         this.middleware.push(middleware);
       }
-      #registerRouteHandler(method, path7, handler) {
+      #registerRouteHandler(method, path10, handler) {
         if (!this.routes[method]) {
           this.routes[method] = {};
         }
-        const paramNames = this.#extractParamNames(path7);
-        this.routes[method][path7] = {
-          path: path7,
+        const paramNames = this.#extractParamNames(path10);
+        this.routes[method][path10] = {
+          path: path10,
           handler,
           paramNames,
-          isWildcard: path7 === "/*",
-          compiledRegex: paramNames.length > 0 ? new RegExp(`^${this.#buildRegexPattern(path7, paramNames)}$`) : null
+          isWildcard: path10 === "/*",
+          compiledRegex: paramNames.length > 0 ? new RegExp(`^${this.#buildRegexPattern(path10, paramNames)}$`) : null
         };
       }
       #handleRequest(req, res) {
@@ -1017,11 +1027,11 @@ var init_http = __esm({
           return null;
         }
         return routes[url] || Object.values(routes).find((route) => {
-          const { path: path7, isWildcard } = route;
-          if (!isWildcard && !path7.includes(":")) {
+          const { path: path10, isWildcard } = route;
+          if (!isWildcard && !path10.includes(":")) {
             return false;
           }
-          if (isWildcard || this.#matchPathSegments(path7, url)) {
+          if (isWildcard || this.#matchPathSegments(path10, url)) {
             if (route.compiledRegex) {
               const regexMatches = route.compiledRegex.exec(url);
               if (regexMatches) {
@@ -1033,8 +1043,8 @@ var init_http = __esm({
           return false;
         }) || null;
       }
-      #matchPathSegments(path7, url) {
-        const pathSegments = path7.split("/");
+      #matchPathSegments(path10, url) {
+        const pathSegments = path10.split("/");
         const urlSegments = url.split("/");
         if (pathSegments.length !== urlSegments.length) {
           return false;
@@ -1051,14 +1061,14 @@ var init_http = __esm({
         }
         return true;
       }
-      #buildRegexPattern(path7, _paramNames) {
-        let regexPattern = path7.replace(/:[^/]+/g, "([^/]+)");
+      #buildRegexPattern(path10, _paramNames) {
+        let regexPattern = path10.replace(/:[^/]+/g, "([^/]+)");
         regexPattern = regexPattern.replace(/\//g, "\\/");
         return regexPattern;
       }
-      #extractParamNames(path7) {
+      #extractParamNames(path10) {
         const paramRegex = /:(\w+)/g;
-        const paramMatches = path7.match(paramRegex);
+        const paramMatches = path10.match(paramRegex);
         return paramMatches ? paramMatches.map((match) => match.slice(1)) : [];
       }
       #extractParams(route, _url) {
@@ -1075,9 +1085,9 @@ var init_http = __esm({
 
 // lib/setup/web-server.ts
 import fs8 from "node:fs";
-import path4 from "node:path";
+import path5 from "node:path";
 function setupWebServer(config, cachedContent) {
-  const STATIC_FILES_PATH = path4.join(config.projectRoot, config.output);
+  const STATIC_FILES_PATH = path5.resolve(config.projectRoot, config.output);
   const server = new HTTPServer();
   const mainHTMLWithReplacedAssets = replaceAssetPaths(
     cachedContent.mainHTML.html,
@@ -1214,7 +1224,10 @@ function setupWebServer(config, cachedContent) {
         config._testRunDone?.();
         config._testRunDone = null;
       }
-      return saveHTML(`${config.projectRoot}/${config.output}/index.html`, htmlContent);
+      return saveHTML(
+        path5.join(path5.resolve(config.projectRoot, config.output), "index.html"),
+        htmlContent
+      );
     }
     if (cachedContent._noTestsWarning) {
       res.writeHead(200, HTML_HEADERS);
@@ -1222,14 +1235,20 @@ function setupWebServer(config, cachedContent) {
     }
     res.writeHead(200, HTML_HEADERS);
     res.end(mainIndexHTML);
-    saveHTML(`${config.projectRoot}/${config.output}/index.html`, mainIndexHTML);
+    saveHTML(
+      path5.join(path5.resolve(config.projectRoot, config.output), "index.html"),
+      mainIndexHTML
+    );
   });
   server.get("/qunitx.html", (_req, res) => {
     if (cachedContent._buildError) {
       const htmlContent = buildErrorHTML(cachedContent._buildError);
       res.writeHead(200, HTML_HEADERS);
       res.end(htmlContent);
-      return saveHTML(`${config.projectRoot}/${config.output}/qunitx.html`, htmlContent);
+      return saveHTML(
+        path5.join(path5.resolve(config.projectRoot, config.output), "qunitx.html"),
+        htmlContent
+      );
     }
     if (cachedContent._noTestsWarning) {
       res.writeHead(200, HTML_HEADERS);
@@ -1237,7 +1256,10 @@ function setupWebServer(config, cachedContent) {
     }
     res.writeHead(200, HTML_HEADERS);
     res.end(mainQunitxHTML);
-    saveHTML(`${config.projectRoot}/${config.output}/qunitx.html`, mainQunitxHTML);
+    saveHTML(
+      path5.join(path5.resolve(config.projectRoot, config.output), "qunitx.html"),
+      mainQunitxHTML
+    );
   });
   server.get("/*", (req, res) => {
     const possibleDynamicHTML = cachedContent.dynamicContentHTMLs[`${config.projectRoot}${req.path}`];
@@ -1249,13 +1271,13 @@ function setupWebServer(config, cachedContent) {
       );
       res.writeHead(200, HTML_HEADERS);
       res.end(htmlContent);
-      saveHTML(`${config.projectRoot}/${config.output}${req.path}`, htmlContent);
+      saveHTML(path5.join(path5.resolve(config.projectRoot, config.output), req.path), htmlContent);
       return;
     }
     const url = req.url;
     const requestStartedAt = Date.now();
     const filePath = (url.endsWith("/") ? [STATIC_FILES_PATH, url, "index.html"] : [STATIC_FILES_PATH, url]).join("");
-    const contentType = req.headers.accept?.includes("text/html") ? MIME_TYPES.html : MIME_TYPES[path4.extname(filePath).substring(1).toLowerCase()] || MIME_TYPES.html;
+    const contentType = req.headers.accept?.includes("text/html") ? MIME_TYPES.html : MIME_TYPES[path5.extname(filePath).substring(1).toLowerCase()] || MIME_TYPES.html;
     const stream = fs8.createReadStream(filePath);
     stream.on("open", () => {
       res.writeHead(200, { "Content-Type": contentType });
@@ -1280,7 +1302,7 @@ function replaceAssetPaths(html, htmlPath, projectRoot) {
   const assetPaths = findInternalAssetsFromHTML(html);
   const htmlDirectory = htmlPath.split("/").slice(0, -1).join("/");
   return assetPaths.reduce((result, assetPath) => {
-    const normalizedFullAbsolutePath = path4.normalize(`${htmlDirectory}/${assetPath}`);
+    const normalizedFullAbsolutePath = path5.normalize(`${htmlDirectory}/${assetPath}`);
     return result.replace(assetPath, normalizedFullAbsolutePath.replace(projectRoot, "."));
   }, html);
 }
@@ -1288,27 +1310,23 @@ function testRuntimeToInject(config, groupId) {
   const groupIdPart = groupId !== void 0 ? `, groupId: ${groupId}` : "";
   return `<script>
     (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();
+      // setupQUnit runs exactly once, after both the WebSocket is open and tests.js has loaded.
+      // Promise.all is naturally idempotent \u2014 resolving a Promise a second time is a no-op,
+      // so WebKit firing WS error after open (causing a retry that re-opens) cannot double-start.
+      let resolveWsReady = () => {};
+      const wsReadyPromise = window.location.protocol === 'file:'
+        ? Promise.resolve()
+        : new Promise(resolve => { resolveWsReady = resolve; });
+
+      // { once: true } auto-removes the listener after the first fire.
+      const testsReadyPromise = new Promise(resolve => {
+        window.addEventListener('qunitx:tests-ready', resolve, { once: true });
       });
 
-      // For static files (file:// protocol) there is no WebSocket server.
-      // wsOpenStatus is already true above; setupQUnit fires when tests load.
+      Promise.all([wsReadyPromise, testsReadyPromise]).then(setupQUnit);
+
+      // For static files (file:// protocol) there is no WebSocket server; wsReadyPromise
+      // is already resolved above, so setupQUnit fires as soon as tests load.
       if (window.location.protocol === 'file:') return;
 
       let wsRetryCount = 0;
@@ -1324,14 +1342,13 @@ function testRuntimeToInject(config, groupId) {
         }
 
         window.socket.addEventListener('open', function() {
-          wsOpenStatus = true;
+          resolveWsReady();
           // 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 (navigator.webdriver) {
             window.socket.send(JSON.stringify({ event: 'wsOpen'${groupIdPart} }));
           }
-          maybeStart();
         });
         window.socket.addEventListener('error', function() {
           retryOrFail();
@@ -1661,7 +1678,10 @@ function registerGroupRoutes(server, groupConfig, groupCachedContent, groupId) {
     }
     res.writeHead(200, HTML_HEADERS);
     res.end(mainGroupHTML);
-    saveHTML(`${groupConfig.projectRoot}/${groupConfig.output}/index.html`, mainGroupHTML);
+    saveHTML(
+      path5.join(path5.resolve(groupConfig.projectRoot, groupConfig.output), "index.html"),
+      mainGroupHTML
+    );
   });
   server.get(`/group-${groupId}/tests.js`, (_req, res) => {
     const bytes = groupCachedContent.allTestCode?.length ?? null;
@@ -1755,10 +1775,10 @@ function registerSharedStaticHandler(server, groupConfigs) {
       res.end("Not found");
       return;
     }
-    const STATIC_FILES_PATH = path4.join(groupConfig.projectRoot, groupConfig.output);
+    const STATIC_FILES_PATH = path5.resolve(groupConfig.projectRoot, groupConfig.output);
     const subPath = match[2] || "/";
     const filePath = (subPath.endsWith("/") ? [STATIC_FILES_PATH, subPath, "index.html"] : [STATIC_FILES_PATH, subPath]).join("");
-    const contentType = req.headers.accept?.includes("text/html") ? MIME_TYPES.html : MIME_TYPES[path4.extname(filePath).substring(1).toLowerCase()] || MIME_TYPES.html;
+    const contentType = req.headers.accept?.includes("text/html") ? MIME_TYPES.html : MIME_TYPES[path5.extname(filePath).substring(1).toLowerCase()] || MIME_TYPES.html;
     const stream = fs8.createReadStream(filePath);
     stream.on("open", () => {
       res.writeHead(200, { "Content-Type": contentType });
@@ -1828,13 +1848,23 @@ async function launchBrowser(config) {
     );
     if (prelaunch) {
       const connectStart = Date.now();
-      const browser = await playwrightCore2.chromium.connectOverCDP({
-        endpointURL: prelaunch.cdpEndpoint
-      });
-      perfLog(`browser.js: connectOverCDP took ${Date.now() - connectStart}ms`);
-      return browser;
+      try {
+        const browser = await playwrightCore2.chromium.connectOverCDP({
+          endpointURL: prelaunch.cdpEndpoint,
+          // Short timeout: if Chrome isn't CDP-ready within 5s (e.g. resource contention on
+          // slow CI runners with many concurrent pre-launches), fall back to chromium.launch().
+          timeout: 5e3
+        });
+        perfLog(`browser.js: connectOverCDP took ${Date.now() - connectStart}ms`);
+        return browser;
+      } catch {
+        perfLog(
+          `browser.js: connectOverCDP failed after ${Date.now() - connectStart}ms \u2014 falling back to chromium.launch()`
+        );
+        await shutdownPrelaunch();
+      }
     }
-    const executablePath = await findChrome();
+    const executablePath = process.platform !== "darwin" ? await findChrome() : null;
     const launchOptions = {
       args: CHROMIUM_ARGS,
       headless: true,
@@ -1930,9 +1960,11 @@ var init_browser = __esm({
 
 // lib/utils/open-output-in-browser.ts
 import { spawn as spawn2 } from "node:child_process";
+import path6 from "node:path";
+import { pathToFileURL } from "node:url";
 async function openOutputInBrowser(config) {
   try {
-    const outputFile = config.watch ? `http://localhost:${config.port}` : `file://${config.projectRoot}/${config.output}/index.html`;
+    const outputFile = config.watch ? `http://localhost:${config.port}` : pathToFileURL(path6.join(path6.resolve(config.projectRoot, config.output), "index.html")).href;
     if (typeof config.open === "string") {
       spawnDetached(config.open, [outputFile]);
       return;
@@ -1978,9 +2010,10 @@ var init_time_counter = __esm({
 });
 
 // lib/utils/run-user-module.ts
+import { pathToFileURL as pathToFileURL2 } from "node:url";
 async function runUserModule(modulePath, params, scriptPosition) {
   try {
-    const func = await import(modulePath);
+    const func = await import(pathToFileURL2(modulePath).href);
     if (func) {
       func.default ? await func.default(params) : typeof func === "function" ? await func(params) : null;
     }
@@ -2023,8 +2056,14 @@ var init_display_final_result = __esm({
 
 // lib/commands/run/tests-in-browser.ts
 import fs9 from "node:fs/promises";
-import path5 from "node:path";
+import path7 from "node:path";
 import esbuild from "esbuild";
+function toEsbuildImportPath(filePath) {
+  const rel = path7.relative(process.cwd(), filePath);
+  const normalized = rel.replace(/\\/g, "/");
+  if (path7.isAbsolute(rel)) return filePath.replace(/\\/g, "/");
+  return normalized.startsWith(".") ? normalized : "./" + normalized;
+}
 function deriveBuildErrorType(error) {
   const msgs = error?.errors ?? [];
   const text = msgs[0]?.text ?? (error instanceof Error ? error.message : String(error));
@@ -2060,13 +2099,14 @@ async function buildTestBundle(config, cachedContent) {
     console.log("# [buildTestBundle] fsTree is empty \u2014 skipping build (no test files found)");
     return;
   }
-  const outfile = `${projectRoot}/${output}/tests.js`;
-  await fs9.mkdir(`${projectRoot}/${output}`, { recursive: true });
+  const outDir = path7.resolve(projectRoot, output);
+  const outfile = path7.join(outDir, "tests.js");
+  await fs9.mkdir(outDir, { recursive: true });
   const sourcemap = "inline";
   const needsDisk = true;
   const buildOptions = {
     stdin: {
-      contents: allTestFilePaths.map((filePath) => `import "${filePath}";`).join(""),
+      contents: allTestFilePaths.map((filePath) => `import "${toEsbuildImportPath(filePath)}";`).join(""),
       resolveDir: process.cwd()
     },
     // Allow test files outside the project root (e.g. /tmp/my-test.ts) to import
@@ -2093,30 +2133,28 @@ async function buildTestBundle(config, cachedContent) {
       config.watch ? buildIncrementally(buildOptions, allTestFilePaths.join("\0"), cachedContent, needsDisk) : buildWithOverlayfsRetry(buildOptions, needsDisk),
       Promise.all(
         cachedContent.htmlPathsToRunTests.map(async (htmlPath) => {
-          const targetPath = `${config.projectRoot}/${config.output}${htmlPath}`;
+          const targetPath = path7.join(outDir, htmlPath);
           if (htmlPath !== "/") {
             await fs9.rm(targetPath, { force: true, recursive: true });
-            await fs9.mkdir(targetPath.split("/").slice(0, -1).join("/"), { recursive: true });
+            await fs9.mkdir(path7.dirname(targetPath), { recursive: true });
           }
         })
       )
     ]);
     cachedContent.allTestCode = allTestCode;
-    config._sourceMapDecoder = extractInlineSourceMap(allTestCode, `${projectRoot}/${output}`);
+    config._sourceMapDecoder = extractInlineSourceMap(allTestCode, outDir);
   } catch (error) {
     cachedContent._buildError = {
       type: deriveBuildErrorType(error),
       formatted: formatBuildErrors(error)
     };
-    await fs9.writeFile(
-      `${projectRoot}/${output}/index.html`,
-      buildErrorHTML(cachedContent._buildError)
-    );
+    await fs9.writeFile(path7.join(outDir, "index.html"), buildErrorHTML(cachedContent._buildError));
     throw error;
   }
 }
 async function runTestsInBrowser(config, cachedContent = {}, connections, targetTestFilesToFilter) {
   const { projectRoot, output } = config;
+  const outDir = path7.resolve(projectRoot, output);
   const allTestFilePaths = Object.keys(config.fsTree);
   const runHasFilter = !!targetTestFilesToFilter;
   if (!config._groupMode) {
@@ -2144,16 +2182,13 @@ async function runTestsInBrowser(config, cachedContent = {}, connections, target
       return connections;
     }
     if (runHasFilter) {
-      const outputPath = `${projectRoot}/${output}/filtered-tests.js`;
+      const outputPath = path7.join(outDir, "filtered-tests.js");
       cachedContent.filteredTestCode = await buildFilteredTests(
         targetTestFilesToFilter,
         outputPath,
         config
       );
-      config._sourceMapDecoder = extractInlineSourceMap(
-        cachedContent.filteredTestCode,
-        `${projectRoot}/${output}`
-      );
+      config._sourceMapDecoder = extractInlineSourceMap(cachedContent.filteredTestCode, outDir);
     }
     const TIME_COUNTER = timeCounter();
     if (runHasFilter) {
@@ -2187,7 +2222,7 @@ async function runTestsInBrowser(config, cachedContent = {}, connections, target
         console.log(
           `# Warning: 0 tests registered \u2014 no QUnit test cases found in ${allTestFilePaths.length} ${fileWord}`
         );
-        fs9.writeFile(`${projectRoot}/${output}/index.html`, buildNoTestsHTML(displayFiles)).catch(
+        fs9.writeFile(path7.join(outDir, "index.html"), buildNoTestsHTML(displayFiles)).catch(
           () => {
           }
         );
@@ -2216,7 +2251,7 @@ async function runTestsInBrowser(config, cachedContent = {}, connections, target
         formatted: formatBuildErrors(error)
       };
       fs9.writeFile(
-        `${projectRoot}/${output}/qunitx.html`,
+        path7.join(outDir, "qunitx.html"),
         buildErrorHTML(cachedContent._buildError)
       ).catch(
         (err) => config.debug && process.stderr.write(`# [qunitx] writeFile qunitx.html: ${err.message}
@@ -2237,7 +2272,7 @@ function buildFilteredTests(filteredTests, outputPath, config) {
   return buildWithOverlayfsRetry(
     {
       stdin: {
-        contents: filteredTests.map((filePath) => `import "${filePath}";`).join(""),
+        contents: filteredTests.map((filePath) => `import "${filePath.replace(/\\/g, "/")}";`).join(""),
         resolveDir: process.cwd()
       },
       nodePaths: ANCESTOR_NODE_MODULES,
@@ -2428,7 +2463,7 @@ async function buildAllGroupBundles(groupConfigs, groupCachedContents) {
     );
   await Promise.all(
     activeGroups.map(
-      (group) => fs9.mkdir(`${group.config.projectRoot}/${group.config.output}`, { recursive: true })
+      (group) => fs9.mkdir(path7.resolve(group.config.projectRoot, group.config.output), { recursive: true })
     )
   );
   const sourcemap = "inline";
@@ -2442,13 +2477,13 @@ async function buildAllGroupBundles(groupConfigs, groupCachedContents) {
       build.onLoad({ filter: /.*/, namespace: "group-entry" }, (args) => {
         const slotIndex = parseInt(args.path.replace("group-entry-", ""));
         return {
-          contents: activeGroups[slotIndex].files.map((filePath) => `import "${filePath}";`).join(""),
+          contents: activeGroups[slotIndex].files.map((filePath) => `import "${toEsbuildImportPath(filePath)}";`).join(""),
           resolveDir: process.cwd()
         };
       });
     }
   };
-  const esbuildOutdir = path5.join(projectRoot, "tmp");
+  const esbuildOutdir = path7.join(projectRoot, "tmp");
   const buildOptions = {
     entryPoints: activeGroups.map((_, slotIndex) => ({
       in: `group-entry-${slotIndex}`,
@@ -2486,7 +2521,10 @@ async function buildAllGroupBundles(groupConfigs, groupCachedContents) {
         const slotIndex = parseInt(match[1]);
         const isMap = Boolean(match[2]);
         const { config, cachedContent } = activeGroups[slotIndex];
-        const destPath = `${config.projectRoot}/${config.output}/tests.js${isMap ? ".map" : ""}`;
+        const destPath = path7.join(
+          path7.resolve(config.projectRoot, config.output),
+          "tests.js" + (isMap ? ".map" : "")
+        );
         if (!isMap) {
           cachedContent.allTestCode = Buffer.from(outputFile.contents);
           config._sourceMapDecoder = extractInlineSourceMap(
@@ -2503,7 +2541,10 @@ async function buildAllGroupBundles(groupConfigs, groupCachedContents) {
     await Promise.all(
       activeGroups.map((group) => {
         group.cachedContent._buildError = buildError;
-        return fs9.writeFile(`${group.config.projectRoot}/${group.config.output}/index.html`, errorHtml).catch(
+        return fs9.writeFile(
+          path7.join(path7.resolve(group.config.projectRoot, group.config.output), "index.html"),
+          errorHtml
+        ).catch(
           (err) => debug && process.stderr.write(`# [qunitx] writeFile index.html: ${err.message}
 `)
         );
@@ -2529,8 +2570,8 @@ var init_tests_in_browser = __esm({
         this.message = `esbuild Bundle Error: ${message}`.split("\n").join("\n# ");
       }
     };
-    ancestorNodeModules = (dir) => dir.split(path5.sep).map(
-      (_, i, parts) => path5.join(parts.slice(0, parts.length - i).join(path5.sep) || path5.sep, "node_modules")
+    ancestorNodeModules = (dir) => dir.split(path7.sep).map(
+      (_, i, parts) => path7.join(parts.slice(0, parts.length - i).join(path7.sep) || path7.sep, "node_modules")
     );
     ANCESTOR_NODE_MODULES = ancestorNodeModules(process.cwd());
     RETRY_DELAY_MS = 100;
@@ -2548,7 +2589,7 @@ var init_tests_in_browser = __esm({
 // lib/setup/file-watcher.ts
 import fs10 from "node:fs";
 import { stat, lstat } from "node:fs/promises";
-import path6 from "node:path";
+import path8 from "node:path";
 function setupFileWatchers(testFileLookupPaths, config, onEventFunc, onFinishFunc) {
   const extensions = config.extensions || ["js", "ts"];
   const readyPromises = [];
@@ -2557,13 +2598,17 @@ function setupFileWatchers(testFileLookupPaths, config, onEventFunc, onFinishFun
   const symlinkPollers = /* @__PURE__ */ new Map();
   function trackSymlink(filePath) {
     if (symlinkPollers.has(filePath)) return;
-    const handler = (curr) => {
+    const handler = (curr, prev) => {
       if (curr.nlink === 0) {
         fs10.unwatchFile(filePath, handler);
         symlinkPollers.delete(filePath);
         if (filePath in config.fsTree) {
           handleWatchEvent(config, extensions, "unlink", filePath, onEventFunc, onFinishFunc);
         }
+      } else if ((process.platform === "win32" || process.platform === "darwin") && curr.mtimeMs !== prev.mtimeMs) {
+        if (filePath in config.fsTree) {
+          handleWatchEvent(config, extensions, "change", filePath, onEventFunc, onFinishFunc);
+        }
       }
     };
     fs10.watchFile(filePath, { interval: SYMLINK_POLL_INTERVAL_MS, persistent: false }, handler);
@@ -2575,22 +2620,23 @@ function setupFileWatchers(testFileLookupPaths, config, onEventFunc, onFinishFun
   }
   for (const watchPath of testFileLookupPaths) {
     let ready = false;
-    const lastChangeMs = {};
+    const lastEventMs = {};
+    const seenMtimeMs = {};
     const childWatcher = fs10.watch(watchPath, { recursive: true }, async (eventType, filename) => {
       if (!ready || !filename) return;
-      const fullPath = filename === path6.basename(watchPath) ? watchPath : path6.join(watchPath, filename);
+      const fullPath = filename === path8.basename(watchPath) ? watchPath : path8.join(watchPath, filename);
       if (eventType === "change") {
         const now = Date.now();
-        const last = lastChangeMs[fullPath] ?? 0;
-        lastChangeMs[fullPath] = now;
-        if (now - last < CHANGE_DEDUPE_MS && (config._building || !config._lastBuildEndMs || config._lastBuildEndMs <= last))
-          return;
-        if (config._lastBuildEndMs) {
-          try {
-            const { mtimeMs } = await stat(fullPath);
-            if (mtimeMs < Math.floor(config._lastBuildEndMs / 1e3) * 1e3) return;
-          } catch {
-          }
+        const last = lastEventMs[fullPath] ?? 0;
+        lastEventMs[fullPath] = now;
+        try {
+          const { mtimeMs } = await stat(fullPath);
+          const prevMtime = seenMtimeMs[fullPath] ?? 0;
+          seenMtimeMs[fullPath] = mtimeMs;
+          if (now - last < CHANGE_DEDUPE_MS && mtimeMs > 0 && mtimeMs === prevMtime) return;
+          if (config._lastBuildEndMs && mtimeMs < Math.floor(config._lastBuildEndMs / 1e3) * 1e3)
+            return;
+        } catch {
         }
         return handleWatchEvent(config, extensions, "change", fullPath, onEventFunc, onFinishFunc);
       }
@@ -2607,8 +2653,8 @@ function setupFileWatchers(testFileLookupPaths, config, onEventFunc, onFinishFun
       }
       handleWatchEvent(config, extensions, event, fullPath, onEventFunc, onFinishFunc);
     });
-    const parentDir = path6.dirname(watchPath);
-    const watchedBasename = path6.basename(watchPath);
+    const parentDir = path8.dirname(watchPath);
+    const watchedBasename = path8.basename(watchPath);
     let parentUnlinkFired = false;
     const parentWatcher = fs10.watch(parentDir, async (eventType, filename) => {
       if (!ready || filename !== watchedBasename || eventType !== "rename") return;
@@ -2664,14 +2710,16 @@ async function classifyRenameEvent(fullPath, fsTree) {
     if (delay) await new Promise((resolve) => setTimeout(resolve, delay));
     try {
       const statResult = await stat(fullPath);
-      return statResult.isDirectory() ? "addDir" : "add";
+      if (statResult.isDirectory()) return "addDir";
+      return fsTree && fullPath in fsTree ? "change" : "add";
     } catch {
     }
   }
   if (!fsTree) return null;
   if (fullPath in fsTree) return "unlink";
-  const dirPrefix = fullPath + "/";
-  return Object.keys(fsTree).some((trackedPath) => trackedPath.startsWith(dirPrefix)) ? "unlinkDir" : null;
+  return Object.keys(fsTree).some(
+    (trackedPath) => trackedPath.startsWith(fullPath + "/") || trackedPath.startsWith(fullPath + "\\")
+  ) ? "unlinkDir" : null;
 }
 function handleWatchEvent(config, extensions, event, filePath, onEventFunc, onFinishFunc) {
   if (event !== "unlinkDir" && !extensions.some((ext) => filePath.endsWith(`.${ext}`)))
@@ -2711,15 +2759,15 @@ function handleWatchEvent(config, extensions, event, filePath, onEventFunc, onFi
     }
   });
 }
-function mutateFSTree(fsTree, event, path7) {
+function mutateFSTree(fsTree, event, filePath) {
   if (event === "add") {
-    fsTree[path7] = null;
+    fsTree[filePath] = null;
   } else if (event === "unlink") {
-    delete fsTree[path7];
+    delete fsTree[filePath];
   } else if (event === "unlinkDir") {
-    const dirPrefix = path7.endsWith("/") ? path7 : path7 + "/";
     for (const treePath of Object.keys(fsTree)) {
-      if (treePath.startsWith(dirPrefix)) delete fsTree[treePath];
+      if (treePath.startsWith(filePath + "/") || treePath.startsWith(filePath + "\\"))
+        delete fsTree[treePath];
     }
   }
 }
@@ -2815,24 +2863,27 @@ var init_keyboard_events = __esm({
 
 // lib/setup/write-output-static-files.ts
 import fs11 from "node:fs/promises";
+import path9 from "node:path";
 async function writeOutputStaticFiles({ projectRoot, output }, cachedContent) {
   const staticHTMLPromises = Object.keys(cachedContent.staticHTMLs).map(async (staticHTMLKey) => {
-    const htmlRelativePath = staticHTMLKey.replace(`${projectRoot}/`, "");
-    await ensureFolderExists(`${projectRoot}/${output}/${htmlRelativePath}`);
+    const htmlRelativePath = path9.relative(projectRoot, staticHTMLKey);
+    const outDir = path9.resolve(projectRoot, output);
+    await ensureFolderExists(path9.join(outDir, htmlRelativePath));
     await fs11.writeFile(
-      `${projectRoot}/${output}/${htmlRelativePath}`,
+      path9.join(outDir, htmlRelativePath),
       cachedContent.staticHTMLs[staticHTMLKey]
     );
   });
   const assetPromises = Array.from(cachedContent.assets).map(async (assetAbsolutePath) => {
-    const assetRelativePath = assetAbsolutePath.replace(`${projectRoot}/`, "");
-    await ensureFolderExists(`${projectRoot}/${output}/${assetRelativePath}`);
-    await fs11.copyFile(assetAbsolutePath, `${projectRoot}/${output}/${assetRelativePath}`);
+    const assetRelativePath = path9.relative(projectRoot, assetAbsolutePath);
+    const outDir = path9.resolve(projectRoot, output);
+    await ensureFolderExists(path9.join(outDir, assetRelativePath));
+    await fs11.copyFile(assetAbsolutePath, path9.join(outDir, assetRelativePath));
   });
   await Promise.all(staticHTMLPromises.concat(assetPromises));
 }
 async function ensureFolderExists(assetPath) {
-  await fs11.mkdir(assetPath.split("/").slice(0, -1).join("/"), { recursive: true });
+  await fs11.mkdir(path9.dirname(assetPath), { recursive: true });
 }
 var init_write_output_static_files = __esm({
   "lib/setup/write-output-static-files.ts"() {
@@ -3062,7 +3113,7 @@ async function run(config) {
       (err) => config.debug && process.stderr.write(`# [qunitx] persistTimings: ${err.message}
 `)
     );
-    printFileTimings(fileTimes, config.projectRoot);
+    if (config.debug) printFileTimings(fileTimes, config.projectRoot);
     if (config.after) {
       await runUserModule(`${process.cwd()}/${config.after}`, config.COUNTER, "after");
     }
@@ -3248,7 +3299,7 @@ init_color();
 var package_default = {
   name: "qunitx-cli",
   type: "module",
-  version: "0.20.0",
+  version: "0.21.0",
   description: "Browser runner for QUnitx: run your qunitx tests in google-chrome",
   author: "Izel Nakri",
   license: "MIT",
@@ -3304,9 +3355,9 @@ var package_default = {
   },
   devDependencies: {
     "js-yaml": "^4.1.1",
-    prettier: "^3.8.2",
-    qunitx: "^1.2.7",
-    typescript: "^6.0.2"
+    prettier: "^3.8.3",
+    qunitx: "^1.2.8",
+    typescript: "^6.0.3"
   },
   volta: {
     node: "24.14.0"
@@ -3364,9 +3415,9 @@ import process2 from "node:process";
 
 // lib/utils/path-exists.ts
 import fs2 from "node:fs/promises";
-async function pathExists(path7) {
+async function pathExists(path10) {
   try {
-    await fs2.access(path7);
+    await fs2.access(path10);
     return true;
   } catch {
     return false;
@@ -3438,7 +3489,7 @@ async function writeTestsHTML(projectRoot, config, oldPackageJSON) {
         const targetDirectory = path2.dirname(targetPath);
         const _targetOutputPath = path2.relative(
           targetDirectory,
-          `${projectRoot}/${config.output}/tests.js`
+          path2.join(path2.resolve(projectRoot, config.output), "tests.js")
         );
         const testHTMLTemplate = testHTMLTemplateBuffer.replace(
           "{{applicationName}}",
@@ -3484,17 +3535,17 @@ function pathToModuleName(filePath) {
 async function generateTestFiles() {
   const projectRoot = await findProjectRoot();
   const moduleName = pathToModuleName(process.argv[3]);
-  const path7 = process.argv[3].endsWith(".js") || process.argv[3].endsWith(".ts") ? `${projectRoot}/${process.argv[3]}` : `${projectRoot}/${process.argv[3]}.js`;
-  if (await pathExists(path7)) {
-    console.log(`${path7} already exists!`);
+  const path10 = process.argv[3].endsWith(".js") || process.argv[3].endsWith(".ts") ? `${projectRoot}/${process.argv[3]}` : `${projectRoot}/${process.argv[3]}.js`;
+  if (await pathExists(path10)) {
+    console.log(`${path10} already exists!`);
     return;
   }
   const testJSContent = await readTemplate("test.js");
-  const targetFolderPaths = path7.split("/");
+  const targetFolderPaths = path10.split("/");
   targetFolderPaths.pop();
   await fs5.mkdir(targetFolderPaths.join("/"), { recursive: true });
-  await fs5.writeFile(path7, testJSContent.replace("{{moduleName}}", moduleName));
-  console.log(green(`${path7} written`));
+  await fs5.writeFile(path10, testJSContent.replace("{{moduleName}}", moduleName));
+  console.log(green(`${path10} written`));
 }
 
 // lib/setup/config.ts
@@ -3595,23 +3646,24 @@ function setupTestFilePaths(_projectRoot, inputs2) {
   });
   return result.map((metaItem) => metaItem.input);
 }
-function pathIsFile(path7) {
-  const inputs2 = path7.split("/");
+function pathIsFile(path10) {
+  const inputs2 = path10.split("/");
   return inputs2[inputs2.length - 1].includes(".");
 }
 function pathIsIncludedInPaths(paths, targetPath) {
-  return paths.some((path7) => {
-    if (path7 === targetPath) {
+  return paths.some((path10) => {
+    if (path10 === targetPath) {
       return false;
     }
-    return matchesGlob(targetPath.input, buildGlobFormat(path7));
+    return matchesGlob(targetPath.input, buildGlobFormat(path10));
   });
 }
-function buildGlobFormat(path7) {
-  return path7.isFile ? path7.input : `${path7.input}/**`;
+function buildGlobFormat(path10) {
+  return path10.isFile ? path10.input : `${path10.input}/**`;
 }
 
 // lib/utils/parse-cli-flags.ts
+import path4 from "node:path";
 var FALLBACK_TIMEOUT_MS = 1e4;
 function parseCliFlags(projectRoot) {
   const providedFlags = process.argv.slice(2).reduce(
@@ -3664,12 +3716,22 @@ function parseCliFlags(projectRoot) {
         return result;
       }
       result.inputs.add(
-        arg.startsWith(projectRoot) || arg.startsWith("/") ? arg : `${process.cwd()}/${arg}`
+        arg.startsWith(projectRoot) || arg.startsWith("/") ? arg : path4.join(process.cwd(), arg)
       );
       return result;
     },
     { inputs: /* @__PURE__ */ new Set([]) }
   );
+  if (!providedFlags.browser && process.env.QUNITX_BROWSER) {
+    const envBrowser = process.env.QUNITX_BROWSER;
+    if (!["chromium", "firefox", "webkit"].includes(envBrowser)) {
+      console.error(
+        `Invalid QUNITX_BROWSER value: "${envBrowser}". Must be one of: chromium, firefox, webkit`
+      );
+      process.exit(1);
+    }
+    providedFlags.browser = envBrowser;
+  }
   return { ...providedFlags, inputs: Array.from(providedFlags.inputs) };
 }
 function parseBoolean(result, defaultValue = true) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "qunitx-cli",
   "type": "module",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Browser runner for QUnitx: run your qunitx tests in google-chrome",
   "author": "Izel Nakri",
   "license": "MIT",
@@ -57,9 +57,9 @@
   },
   "devDependencies": {
     "js-yaml": "^4.1.1",
-    "prettier": "^3.8.2",
-    "qunitx": "^1.2.7",
-    "typescript": "^6.0.2"
+    "prettier": "^3.8.3",
+    "qunitx": "^1.2.8",
+    "typescript": "^6.0.3"
   },
   "volta": {
     "node": "24.14.0"