qunitx-cli 0.9.1 → 0.9.3

package/lib/servers/{http.js → http.ts}

@@ -1,10 +1,44 @@
 import http from 'node:http';
 // @deno-types="npm:@types/ws"
 import WebSocket, { WebSocketServer } from 'ws';
-import bindServerToPort from '../setup/bind-server-to-port.js';
+import bindServerToPort from '../setup/bind-server-to-port.ts';
+
+declare module 'node:http' {
+  interface IncomingMessage {
+    send: (data: string) => void;
+    path: string;
+    query: Record<string, string>;
+    params: Record<string, string>;
+  }
+  interface ServerResponse {
+    json: (data: unknown) => void;
+  }
+}
+
+type NodeServerWithWSS = http.Server & { wss: WebSocketServer };
+
+/** Route handler function signature for registered GET/POST/etc. routes. */
+export type RouteHandler = (
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+) => void | Promise<void>;
+/** Middleware function signature — call `next()` to continue the chain. */
+export type Middleware = (
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  next: () => void,
+) => void;
+
+interface Route {
+  path: string;
+  handler: RouteHandler;
+  paramNames: string[];
+  isWildcard: boolean;
+  paramValues?: string[];
+}
 
 /** Map of file extensions to their corresponding MIME type strings. */
-export const MIME_TYPES = {
+export const MIME_TYPES: Record<string, string> = {
   html: 'text/html; charset=UTF-8',
   js: 'application/javascript',
   css: 'text/css',
@@ -17,13 +51,27 @@ export const MIME_TYPES = {
 
 /** Minimal HTTP + WebSocket server used to serve test bundles and push reload events. */
 export default class HTTPServer {
+  /** Registered routes keyed by HTTP method then path. */
+  routes: Record<string, Record<string, Route>>;
+  /** Registered middleware functions, applied in order before each route handler. */
+  middleware: Middleware[];
+  /** Underlying Node.js HTTP server instance. */
+  _server: http.Server;
+  /** WebSocket server attached to the HTTP server for live-reload broadcasts. */
+  wss: WebSocketServer;
+
   /**
    * Creates and starts a plain `http.createServer` instance on the given port.
    * @returns {Promise<object>}
    */
-  static serve(config = { port: 1234 }, handler) {
-    const onListen = config.onListen || ((_server) => {});
-    const onError = config.onError || ((_error) => {});
+  static serve(
+    config: { port: number; onListen?: (s: object) => void; onError?: (e: Error) => void } = {
+      port: 1234,
+    },
+    handler: (req: http.IncomingMessage, res: http.ServerResponse) => void,
+  ): Promise<http.Server> {
+    const onListen = config.onListen || ((_server: object) => {});
+    const onError = config.onError || ((_error: Error) => {});
 
     return new Promise((resolve, reject) => {
       const server = http.createServer((req, res) => {
@@ -38,14 +86,13 @@ export default class HTTPServer {
           onListen(Object.assign({ hostname: '127.0.0.1', server }, config));
           resolve(server);
         });
-
-      server.wss = new WebSocketServer({ server });
-      server.wss.on('error', (error) => {
+      (server as NodeServerWithWSS).wss = new WebSocketServer({ server });
+      (server as NodeServerWithWSS).wss.on('error', (error: Error) => {
         console.log('# [WebSocketServer] Error:');
         console.trace(error);
       });
 
-      bindServerToPort(server, config);
+      bindServerToPort(server as unknown as HTTPServer, config as { port: number });
     });
   }
 
@@ -58,11 +105,11 @@ export default class HTTPServer {
     };
     this.middleware = [];
     this._server = http.createServer((req, res) => {
-      res.send = (data) => {
+      req.send = (data: string) => {
         res.setHeader('Content-Type', 'text/plain');
         res.end(data);
       };
-      res.json = (data) => {
+      res.json = (data: unknown) => {
         res.setHeader('Content-Type', 'application/json');
         res.end(JSON.stringify(data));
       };
@@ -77,15 +124,17 @@ export default class HTTPServer {
   }
 
   /**
-   * Closes the underlying HTTP server.
-   * @returns {object}
+   * Closes the underlying HTTP server and all active connections, returning a
+   * Promise that resolves once the server is fully closed.
+   * @returns {Promise<void>}
    */
-  close() {
-    return this._server.close();
+  close(): Promise<void> {
+    this._server.closeAllConnections?.();
+    return new Promise((resolve) => this._server.close(resolve as () => void));
   }
 
   /** Registers a GET route handler. */
-  get(path, handler) {
+  get(path: string, handler: RouteHandler): void {
     this.#registerRouteHandler('GET', path, handler);
   }
 
@@ -93,9 +142,9 @@ export default class HTTPServer {
    * Starts listening on the given port (0 = OS-assigned).
    * @returns {Promise<void>}
    */
-  listen(port = 0, callback = () => {}) {
+  listen(port = 0, callback: () => void = () => {}): Promise<void> {
     return new Promise((resolve, reject) => {
-      const onError = (err) => {
+      const onError = (err: Error) => {
         this._server.off('listening', onListening);
         reject(err);
       };
@@ -110,7 +159,7 @@ export default class HTTPServer {
   }
 
   /** Broadcasts a message to all connected WebSocket clients. */
-  publish(data) {
+  publish(data: string): void {
     this.wss.clients.forEach((client) => {
       if (client.readyState === WebSocket.OPEN) {
         client.send(data);
@@ -119,26 +168,26 @@ export default class HTTPServer {
   }
 
   /** Registers a POST route handler. */
-  post(path, handler) {
+  post(path: string, handler: RouteHandler): void {
     this.#registerRouteHandler('POST', path, handler);
   }
 
   /** Registers a DELETE route handler. */
-  delete(path, handler) {
+  delete(path: string, handler: RouteHandler): void {
     this.#registerRouteHandler('DELETE', path, handler);
   }
 
   /** Registers a PUT route handler. */
-  put(path, handler) {
+  put(path: string, handler: RouteHandler): void {
     this.#registerRouteHandler('PUT', path, handler);
   }
 
   /** Adds a middleware function to the chain. */
-  use(middleware) {
+  use(middleware: Middleware): void {
     this.middleware.push(middleware);
   }
 
-  #registerRouteHandler(method, path, handler) {
+  #registerRouteHandler(method: string, path: string, handler: RouteHandler): void {
     if (!this.routes[method]) {
       this.routes[method] = {};
     }
@@ -151,13 +200,13 @@ export default class HTTPServer {
     };
   }
 
-  #handleRequest(req, res) {
+  #handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void {
     const { method, url } = req;
-    const urlObj = new URL(url, 'http://localhost');
+    const urlObj = new URL(url!, 'http://localhost');
     const pathname = urlObj.pathname;
     req.path = pathname;
     req.query = Object.fromEntries(urlObj.searchParams);
-    const matchingRoute = this.#findRouteHandler(method, pathname);
+    const matchingRoute = this.#findRouteHandler(method!, pathname);
 
     if (matchingRoute) {
       req.params = this.#extractParams(matchingRoute, pathname);
@@ -169,7 +218,11 @@ export default class HTTPServer {
     }
   }
 
-  #runMiddleware(req, res, callback) {
+  #runMiddleware(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    callback: RouteHandler,
+  ): void {
     let index = 0;
     const next = () => {
       if (index >= this.middleware.length) {
@@ -183,7 +236,7 @@ export default class HTTPServer {
     next();
   }
 
-  #findRouteHandler(method, url) {
+  #findRouteHandler(method: string, url: string): Route | null {
     const routes = this.routes[method];
     if (!routes) {
       return null;
@@ -217,7 +270,7 @@ export default class HTTPServer {
     );
   }
 
-  #matchPathSegments(path, url) {
+  #matchPathSegments(path: string, url: string): boolean {
     const pathSegments = path.split('/');
     const urlSegments = url.split('/');
 
@@ -241,26 +294,26 @@ export default class HTTPServer {
     return true;
   }
 
-  #buildRegexPattern(path, _paramNames) {
+  #buildRegexPattern(path: string, _paramNames: string[]): string {
     let regexPattern = path.replace(/:[^/]+/g, '([^/]+)');
     regexPattern = regexPattern.replace(/\//g, '\\/');
 
     return regexPattern;
   }
 
-  #extractParamNames(path) {
+  #extractParamNames(path: string): string[] {
     const paramRegex = /:(\w+)/g;
     const paramMatches = path.match(paramRegex);
 
     return paramMatches ? paramMatches.map((match) => match.slice(1)) : [];
   }
 
-  #extractParams(route, _url) {
+  #extractParams(route: Route, _url: string): Record<string, string> {
     const { paramNames, paramValues } = route;
-    const params = {};
+    const params: Record<string, string> = {};
 
     for (let i = 0; i < paramNames.length; i++) {
-      params[paramNames[i]] = paramValues[i];
+      params[paramNames[i]] = paramValues![i];
     }
 
     return params;

package/lib/setup/bind-server-to-port.ts

@@ -0,0 +1,14 @@
+import type HTTPServer from '../servers/http.ts';
+
+/**
+ * Binds an HTTPServer to an OS-assigned port and writes the resolved port back to `config.port`.
+ * @returns {Promise<object>}
+ */
+export default async function bindServerToPort(
+  server: HTTPServer,
+  config: { port: number },
+): Promise<HTTPServer> {
+  await server.listen(0);
+  config.port = (server._server.address() as import('node:net').AddressInfo).port;
+  return server;
+}

package/lib/setup/{browser.js → browser.ts}

@@ -1,15 +1,17 @@
-import setupWebServer from './web-server.js';
-import bindServerToPort from './bind-server-to-port.js';
-import findChrome from '../utils/find-chrome.js';
-import CHROMIUM_ARGS from '../utils/chromium-args.js';
-import { earlyBrowserPromise } from '../utils/early-chrome.js';
-import { perfLog } from '../utils/perf-logger.js';
+import setupWebServer from './web-server.ts';
+import bindServerToPort from './bind-server-to-port.ts';
+import findChrome from '../utils/find-chrome.ts';
+import CHROMIUM_ARGS from '../utils/chromium-args.ts';
+import { earlyBrowserPromise } from '../utils/early-chrome.ts';
+import { perfLog } from '../utils/perf-logger.ts';
+import type { Browser } from 'playwright-core';
+import type { Config, CachedContent, Connections } from '../types.ts';
 
 // Playwright-core starts loading the moment run.js imports this module.
 // browser.js is intentionally the first import in run.js so playwright-core
 // starts loading before heavier deps (esbuild, chokidar) queue up I/O reads
 // and saturate libuv's thread pool, which would delay the dynamic import resolution.
-// early-chrome.js (statically imported by cli.js) already started Chrome pre-launch,
+// early-chrome.ts (statically imported by cli.ts) already started Chrome pre-launch,
 // so both race in parallel — Chrome is typically ready when playwright-core finishes.
 const playwrightCorePromise = import('playwright-core');
 perfLog('browser.js: playwright-core import started');
@@ -21,7 +23,7 @@ perfLog('browser.js: playwright-core import started');
  * For firefox/webkit: uses playwright's standard launch (requires `npx playwright install [browser]`).
  * @returns {Promise<object>}
  */
-export async function launchBrowser(config) {
+export async function launchBrowser(config: Config): Promise<Browser> {
   const browserName = config.browser || 'chromium';
 
   if (browserName === 'chromium') {
@@ -60,16 +62,10 @@ export async function launchBrowser(config) {
  * @returns {Promise<{server: object, browser: object, page: object}>}
  */
 export default async function setupBrowser(
-  config = {
-    port: 1234,
-    debug: false,
-    watch: false,
-    timeout: 10000,
-    browser: 'chromium',
-  },
-  cachedContent,
-  existingBrowser = null,
-) {
+  config: Config,
+  cachedContent: CachedContent,
+  existingBrowser: Browser | null = null,
+): Promise<Connections> {
   const setupStart = Date.now();
   const [server, resolvedExistingBrowser] = await Promise.all([
     setupWebServer(config, cachedContent),

package/lib/setup/config.ts

@@ -0,0 +1,55 @@
+import fs from 'node:fs/promises';
+import defaultProjectConfigValues from './default-project-config-values.ts';
+import findProjectRoot from '../utils/find-project-root.ts';
+import setupFSTree from './fs-tree.ts';
+import setupTestFilePaths from './test-file-paths.ts';
+import parseCliFlags from '../utils/parse-cli-flags.ts';
+import type { Config } from '../types.ts';
+
+/**
+ * Builds the merged qunitx config from package.json settings and CLI flags.
+ * @returns {Promise<object>}
+ */
+export default async function setupConfig(): Promise<Config> {
+  const projectRoot = await findProjectRoot();
+  const cliConfigFlags = parseCliFlags(projectRoot);
+  const projectPackageJSON = await readConfigFromPackageJSON(projectRoot);
+  const inputs = cliConfigFlags.inputs.concat(readInputsFromPackageJSON(projectPackageJSON));
+  const config = {
+    ...defaultProjectConfigValues,
+    htmlPaths: [] as string[],
+    ...((projectPackageJSON.qunitx as Partial<Config>) || {}),
+    ...cliConfigFlags,
+    projectRoot,
+    inputs,
+    testFileLookupPaths: setupTestFilePaths(projectRoot, inputs),
+    lastFailedTestFiles: null as string[] | null,
+    lastRanTestFiles: null as string[] | null,
+    COUNTER: { testCount: 0, failCount: 0, skipCount: 0, passCount: 0, errorCount: 0 },
+    _testRunDone: null as (() => void) | null,
+    _resetTestTimeout: null as (() => void) | null,
+  };
+  config.htmlPaths = normalizeHTMLPaths(config.projectRoot, config.htmlPaths);
+  config.fsTree = await setupFSTree(config.testFileLookupPaths, config);
+
+  return config as Config;
+}
+
+async function readConfigFromPackageJSON(projectRoot: string) {
+  const packageJSON = await fs.readFile(`${projectRoot}/package.json`);
+
+  return JSON.parse(packageJSON.toString()) as { qunitx?: unknown; [key: string]: unknown };
+}
+
+function normalizeHTMLPaths(projectRoot: string, htmlPaths: string[]): string[] {
+  return Array.from(new Set(htmlPaths.map((htmlPath) => `${projectRoot}/${htmlPath}`)));
+}
+
+function readInputsFromPackageJSON(packageJSON: {
+  qunitx?: unknown;
+  [key: string]: unknown;
+}): string[] {
+  const qunitx = packageJSON.qunitx as { inputs?: string[] } | undefined;
+
+  return qunitx && qunitx.inputs ? qunitx.inputs : [];
+}

package/lib/setup/{file-watcher.js → file-watcher.ts}

@@ -1,14 +1,21 @@
 import fs from 'node:fs';
 import { stat } from 'node:fs/promises';
 import path from 'node:path';
-import { green, magenta, red, yellow } from '../utils/color.js';
+import { green, magenta, red, yellow } from '../utils/color.ts';
+import type { FSWatcher } from 'node:fs';
+import type { Config, FSTree } from '../types.ts';
 
 /**
  * Starts `fs.watch` watchers for each lookup path and calls `onEventFunc` on JS/TS file changes, debounced via a flag.
  * Uses `config.fsTree` to distinguish `unlink` (tracked file) from `unlinkDir` (directory) on deletion.
  * @returns {object}
  */
-export default function setupFileWatchers(testFileLookupPaths, config, onEventFunc, onFinishFunc) {
+export default function setupFileWatchers(
+  testFileLookupPaths: string[],
+  config: Config,
+  onEventFunc: (event: string, file: string) => unknown,
+  onFinishFunc: ((path: string, event: string) => void) | null | undefined,
+): { fileWatchers: Record<string, FSWatcher>; killFileWatchers: () => Record<string, FSWatcher> } {
   const extensions = config.extensions || ['js', 'ts'];
   const fileWatchers = testFileLookupPaths.reduce((watchers, watchPath) => {
     let ready = false;
@@ -54,7 +61,14 @@ export default function setupFileWatchers(testFileLookupPaths, config, onEventFu
  * `unlinkDir` bypasses the extension filter so deleted directories always clean up fsTree.
  * @returns {void}
  */
-export function handleWatchEvent(config, extensions, event, filePath, onEventFunc, onFinishFunc) {
+export function handleWatchEvent(
+  config: Config,
+  extensions: string[],
+  event: string,
+  filePath: string,
+  onEventFunc: (event: string, file: string) => unknown,
+  onFinishFunc: ((path: string, event: string) => void) | null | undefined,
+): void {
   const isFileEvent = extensions.some((ext) => filePath.endsWith(`.${ext}`));
 
   if (!isFileEvent && event !== 'unlinkDir') return;
@@ -86,9 +100,8 @@ export function handleWatchEvent(config, extensions, event, filePath, onEventFun
       .then(() => {
         onFinishFunc ? onFinishFunc(event, filePath) : null;
       })
-      .catch(() => {
-        // TODO: make an index.html to display the error
-        // error type has to be derived from the error!
+      .catch((error) => {
+        console.error('#', red('Build error:'), error.message || error);
       })
       .finally(() => (config._building = false));
   }
@@ -98,7 +111,7 @@ export function handleWatchEvent(config, extensions, event, filePath, onEventFun
  * Mutates `fsTree` in place based on a chokidar file-system event.
  * @returns {void}
  */
-export function mutateFSTree(fsTree, event, path) {
+export function mutateFSTree(fsTree: FSTree, event: string, path: string): void {
   if (event === 'add') {
     fsTree[path] = null;
   } else if (event === 'unlink') {
@@ -110,7 +123,7 @@ export function mutateFSTree(fsTree, event, path) {
   }
 }
 
-function getEventColor(event) {
+function getEventColor(event: string): unknown {
   if (event === 'change') {
     return yellow('CHANGED:');
   } else if (event === 'add' || event === 'addDir') {

package/lib/setup/{fs-tree.js → fs-tree.ts}

@@ -2,8 +2,9 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 // @deno-types="npm:@types/picomatch"
 import picomatch from 'picomatch';
+import type { FSTree } from '../types.ts';
 
-async function readDirRecursive(dir, filter) {
+async function readDirRecursive(dir: string, filter: (name: string) => boolean): Promise<string[]> {
   const entries = await fs.readdir(dir, { recursive: true, withFileTypes: true });
   return entries
     .filter((e) => e.isFile() && filter(e.name))
@@ -14,7 +15,10 @@ async function readDirRecursive(dir, filter) {
  * Resolves an array of file paths, directories, or glob patterns into a flat `{ absolutePath: null }` map.
  * @returns {Promise<object>}
  */
-export default async function buildFSTree(fileAbsolutePaths, config = {}) {
+export default async function buildFSTree(
+  fileAbsolutePaths: string[],
+  config: { extensions?: string[] } = {},
+): Promise<FSTree> {
   const targetExtensions = config.extensions || ['js', 'ts'];
   const fsTree = {};
 
@@ -22,8 +26,6 @@ export default async function buildFSTree(fileAbsolutePaths, config = {}) {
     fileAbsolutePaths.map(async (fileAbsolutePath) => {
       const glob = picomatch.scan(fileAbsolutePath);
 
-      // TODO: maybe allow absolute path references
-
       try {
         if (glob.isGlob) {
           const fileNames = await readDirRecursive(glob.base, (name) => {

package/lib/setup/{keyboard-events.js → keyboard-events.ts}

@@ -1,12 +1,17 @@
-import { blue } from '../utils/color.js';
-import listenToKeyboardKey from '../utils/listen-to-keyboard-key.js';
-import runTestsInBrowser from '../commands/run/tests-in-browser.js';
+import { blue } from '../utils/color.ts';
+import listenToKeyboardKey from '../utils/listen-to-keyboard-key.ts';
+import runTestsInBrowser from '../commands/run/tests-in-browser.ts';
+import type { Config, CachedContent, Connections } from '../types.ts';
 
 /**
  * Registers watch-mode keyboard shortcuts: `qq` to abort, `qa` to run all, `qf` for last failed, `ql` for last run.
  * @returns {void}
  */
-export default function setupKeyboardEvents(config, cachedContent, connections) {
+export default function setupKeyboardEvents(
+  config: Config,
+  cachedContent: CachedContent,
+  connections: Connections,
+): void {
   listenToKeyboardKey('qq', () => abortBrowserQUnit(config, connections));
   listenToKeyboardKey('qa', () => {
     abortBrowserQUnit(config, connections);
@@ -28,6 +33,6 @@ export default function setupKeyboardEvents(config, cachedContent, connections)
   });
 }
 
-function abortBrowserQUnit(_config, connections) {
+function abortBrowserQUnit(_config: Config, connections: Connections): void {
   connections.server.publish('abort', 'abort');
 }

package/lib/setup/{test-file-paths.js → test-file-paths.ts}

@@ -1,11 +1,17 @@
 // @deno-types="npm:@types/picomatch"
 import picomatch from 'picomatch';
 
+interface PathMeta {
+  input: string;
+  isFile: boolean;
+  isGlob: boolean;
+}
+
 /**
  * Deduplicates a list of file, folder, and glob inputs so that more-specific paths covered by broader ones are removed.
  * @returns {string[]}
  */
-export default function setupTestFilePaths(_projectRoot, inputs) {
+export default function setupTestFilePaths(_projectRoot: string, inputs: string[]): string[] {
   // NOTE: very complex algorithm, order is very important
   const [folders, filesWithGlob, filesWithoutGlob] = inputs.reduce(
     (result, input) => {
@@ -52,13 +58,13 @@ export default function setupTestFilePaths(_projectRoot, inputs) {
   return result.map((metaItem) => metaItem.input);
 }
 
-function pathIsFile(path) {
+function pathIsFile(path: string): boolean {
   const inputs = path.split('/');
 
   return inputs[inputs.length - 1].includes('.');
 }
 
-function pathIsIncludedInPaths(paths, targetPath) {
+function pathIsIncludedInPaths(paths: PathMeta[], targetPath: PathMeta): boolean {
   return paths.some((path) => {
     if (path === targetPath) {
       return false;
@@ -70,7 +76,7 @@ function pathIsIncludedInPaths(paths, targetPath) {
   });
 }
 
-function buildGlobFormat(path) {
+function buildGlobFormat(path: PathMeta): string {
   if (!path.isFile) {
     if (!path.isGlob) {
       return `${path.input}/*`;

package/lib/setup/{web-server.js → web-server.ts}

@@ -1,9 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import findInternalAssetsFromHTML from '../utils/find-internal-assets-from-html.js';
-import TAPDisplayTestResult from '../tap/display-test-result.js';
-import pathExists from '../utils/path-exists.js';
-import HTTPServer, { MIME_TYPES } from '../servers/http.js';
+import findInternalAssetsFromHTML from '../utils/find-internal-assets-from-html.ts';
+import TAPDisplayTestResult from '../tap/display-test-result.ts';
+import pathExists from '../utils/path-exists.ts';
+import HTTPServer, { MIME_TYPES } from '../servers/http.ts';
+import type { Config, CachedContent } from '../types.ts';
 
 const fsPromise = fs.promises;
 
@@ -11,15 +12,7 @@ const fsPromise = fs.promises;
  * Creates and returns an HTTPServer with routes for the test HTML, filtered test page, and static assets, plus a WebSocket handler that streams TAP events.
  * @returns {object}
  */
-export default function setupWebServer(
-  config = {
-    port: 1234,
-    debug: false,
-    watch: false,
-    timeout: 10000,
-  },
-  cachedContent,
-) {
+export default function setupWebServer(config: Config, cachedContent: CachedContent): HTTPServer {
   const STATIC_FILES_PATH = path.join(config.projectRoot, config.output);
   const server = new HTTPServer();
 
@@ -29,11 +22,13 @@ export default function setupWebServer(
 
       if (event === 'connection') {
         if (!config._groupMode) console.log('TAP version 13');
+        config._resetTestTimeout?.();
       } else if (event === 'testEnd' && !abort) {
         if (details.status === 'failed') {
           config.lastFailedTestFiles = config.lastRanTestFiles;
         }
 
+        config._resetTestTimeout?.();
         TAPDisplayTestResult(config.COUNTER, details);
       } else if (event === 'done') {
         // Signal test completion. TCP ordering guarantees all testEnd messages
@@ -133,7 +128,7 @@ export default function setupWebServer(
   return server;
 }
 
-function replaceAssetPaths(html, htmlPath, projectRoot) {
+function replaceAssetPaths(html: string, htmlPath: string, projectRoot: string): string {
   const assetPaths = findInternalAssetsFromHTML(html);
   const htmlDirectory = htmlPath.split('/').slice(0, -1).join('/');
 
@@ -144,7 +139,7 @@ function replaceAssetPaths(html, htmlPath, projectRoot) {
   }, html);
 }
 
-function testRuntimeToInject(port, config) {
+function testRuntimeToInject(port: number, config: Config): string {
   return `<script>
     window.testTimeout = 0;
     setInterval(() => {
@@ -214,7 +209,7 @@ function testRuntimeToInject(port, config) {
     }
 
     function setupQUnit() {
-      window.QUNIT_RESULT = { totalTests: 0, finishedTests: 0, currentTest: '' };
+      window.QUNIT_RESULT = { totalTests: 0, finishedTests: 0, failedTests: 0, currentTest: '' };
 
       if (!window.QUnit) {
         console.log('QUnit not found after WebSocket connected');
@@ -239,6 +234,7 @@ function testRuntimeToInject(port, config) {
       window.QUnit.on('testEnd', (details) => { // NOTE: https://github.com/qunitjs/qunit/blob/master/src/html-reporter/diff.js
         window.testTimeout = 0;
         window.QUNIT_RESULT.finishedTests++;
+        if (details.status === 'failed') window.QUNIT_RESULT.failedTests++;
         window.QUNIT_RESULT.currentTest = null;
         if (window.IS_PLAYWRIGHT) {
           window.socket.send(JSON.stringify({ event: 'testEnd', details: details, abort: window.abortQUnit }, getCircularReplacer()));
@@ -251,10 +247,11 @@ function testRuntimeToInject(port, config) {
       window.QUnit.done((details) => {
         if (window.IS_PLAYWRIGHT) {
           window.socket.send(JSON.stringify({ event: 'done', details: details, abort: window.abortQUnit }, getCircularReplacer()));
-          // Delay the testTimeout fallback so the WS done event can arrive at Node.js first.
-          // Without this delay, waitForFunction resolves before Node.js processes the done WS
-          // message, causing the shared COUNTER to miss testEnd results under concurrent load.
-          window.setTimeout(() => { window.testTimeout = ${config.timeout}; }, 500);
+          // Do NOT set testTimeout here. The WS 'done' event (testsDone promise) is the
+          // canonical completion signal for Playwright runs. waitForFunction is reserved
+          // for true timeouts (test hangs) where testTimeout increments naturally via setInterval.
+          // Setting testTimeout after done caused a race: under CI load, waitForFunction could
+          // win before Node.js processed the WS done message, dropping all testEnd events.
         } else {
           window.testTimeout = ${config.timeout};
         }
@@ -265,7 +262,11 @@ function testRuntimeToInject(port, config) {
   </script>`;
 }
 
-function escapeAndInjectTestsToHTML(html, testRuntimeCode, testContentCode) {
+function escapeAndInjectTestsToHTML(
+  html: string,
+  testRuntimeCode: string,
+  testContentCode: Buffer | string | null | undefined,
+): string {
   return html.replace(
     '{{content}}',
     testRuntimeCode.replace('{{allTestCode}}', testContentCode).replace('</script>', '<\/script>'), // NOTE: remove this when simple-html-tokenizer PR gets merged