qunitx-cli 0.1.2 → 0.5.1

package/README.md

@@ -1,92 +1,163 @@
-# QUnitX CLI
+# qunitx-cli
 
-CI browser runner for [qunitx](https://github.com/izelnakri/qunitx)
+[![CI](https://github.com/izelnakri/qunitx-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/izelnakri/qunitx-cli/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/qunitx-cli)](https://www.npmjs.com/package/qunitx-cli)
+[![npm downloads](https://img.shields.io/npm/dm/qunitx-cli)](https://www.npmjs.com/package/qunitx-cli)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-![QunitX terminal output](https://raw.githubusercontent.com/izelnakri/qunitx/main/docs/qunitx-help-stdout.png)
+Browser-based test runner for [QUnitX](https://github.com/izelnakri/qunitx) — bundles your JS/TS tests
+with esbuild, runs them in headless Chrome, and streams TAP output to the terminal.
 
-Default test output is TAP (_Test-Anything-Protocol_) thus you can use any tap reporter of your choice to display test
-output in anyway you like. Example:
+![qunitx-cli demo](demo/demo.gif)
 
-```zsh
-# using it with tap-difflet TAP reporter:
-qunitx tests/attachments tests/user | npx tap-difflet
+## Features
+
+- Runs `.js` and `.ts` test files in headless Chrome (Puppeteer + esbuild)
+- TypeScript works with zero configuration — esbuild handles transpilation
+- Inline source maps for accurate stack traces pointing to original source files
+- Streams TAP-formatted output to the terminal in real time
+- Concurrent mode (default) splits test files across all CPU cores for fast parallel runs
+- `--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
+- `--before` / `--after` hook scripts for server setup and teardown
+- `--timeout` controls the maximum ms to wait for the full suite to finish
+- Docker image for zero-install CI usage
+
+## Installation
+
+Requires Node.js >= 24.
+
+```sh
+npm install --save-dev qunitx-cli
 ```
 
-#### Installation:
+Or run without installing:
+
+```sh
+npx qunitx test/**/*.js
+```
+
+With Docker — no install needed:
+
+```sh
+docker run --rm -v "$(pwd):/code" -w /code ghcr.io/izelnakri/qunitx-cli:latest npx qunitx test/**/*.js
+```
 
-```zsh
-npm install -g qunitx-cli
+With Nix:
 
-qunitx
+```sh
+nix profile install github:izelnakri/qunitx-cli
 ```
 
-In order to use qunitx to execute existing qunit tests please change:
+## Usage
+
+```sh
+# Single file
+qunitx test/my-test.js
+
+# Multiple files / globs
+qunitx test/**/*.js test/**/*.ts
+
+# TypeScript — no tsconfig required
+qunitx test/my-test.ts
+
+# Watch mode: re-run on file changes
+qunitx test/**/*.js --watch
+
+# Stop on the first failure
+qunitx test/**/*.js --failFast
+
+# Print the server URL and pipe Chrome console to stdout
+qunitx test/**/*.js --debug
+
+# Custom timeout (ms)
+qunitx test/**/*.js --timeout=30000
+
+# Run a setup script before tests (can be async — awaited automatically)
+qunitx test/**/*.js --before=scripts/start-server.js
+
+# Run a teardown script after tests (can be async)
+qunitx test/**/*.js --after=scripts/stop-server.js
+```
+
+## Writing Tests
+
+qunitx-cli runs [QUnitX](https://github.com/izelnakri/qunitx) tests — a superset of QUnit with async
+hooks, concurrency control, and test metadata.
+
+Migrating from QUnit? Change a single import:
 
 ```js
+// before
 import { module, test } from 'qunit';
-
-// to:
+// after
 import { module, test } from 'qunitx';
 ```
 
-Example:
+Example test file — ES modules, npm imports, and nested modules all work out of the box:
 
 ```js
-// in some-test.js: (typescript is also supported for --browser mode and node.js with --loader flag)
+// some-test.js (TypeScript is also supported)
 import { module, test } from 'qunitx';
 import $ from 'jquery';
 
-module('Basic sanity check', function (hooks) {
-  test('it works', function (assert) {
+module('Basic sanity check', (hooks) => {
+  test('it works', (assert) => {
     assert.equal(true, true);
   });
 
-  module('More advanced cases', function (hooks) {
-    test('deepEqual works', function (assert) {
+  module('More advanced cases', (hooks) => {
+    test('deepEqual works', (assert) => {
       assert.deepEqual({ username: 'izelnakri' }, { username: 'izelnakri' });
     });
-    test('can import ES & npm modules', function (assert) {
+
+    test('can import ES & npm modules', (assert) => {
       assert.ok(Object.keys($));
     });
   });
 });
 ```
 
-```zsh
-# you can run the test in node with ES modules package.json{ "type": "module" }
-$ node --test some-test.js
+Run it:
 
-# Suggested mode: if you want to run it in CI/google chrome:
+```sh
+# Headless Chrome (recommended for CI)
+qunitx some-test.js
 
-$ qunitx some-test.js
-
-# with browser output enabled:
-
-$ qunitx some-test.js --debug
-
-# TypeScript also works, make sure on node.js mode, tsconfig.json exists with compilerOptions.module & compilerOptions.moduleResolution set to "NodeNext":
-
-$ node --loader=ts-node/esm/transpile-only --test some-test.ts
-
-$ qunitx some-test.ts --debug
+# With browser console output
+qunitx some-test.js --debug
 
+# TypeScript — no config needed
+qunitx some-test.ts
 ```
 
-### Code coverage
+## CLI Reference
 
-Since QUnitX proxies to default node.js test runner in when executed with node, you can use any code coverage tool you like. When running the tests in `qunit`(the browser mode) code coverage support is limited.
 ```
-c8 node test/attachments test/user
+Usage: qunitx [files/folders...] [options]
+
+Options:
+  --watch             Re-run tests on file changes
+  --failFast          Stop after the first failure
+  --debug             Print the server URL; pipe browser console to stdout
+  --timeout=<ms>      Max ms to wait for the suite to finish  [default: 20000]
+  --output=<dir>      Directory for compiled test assets     [default: ./tmp]
+  --before=<file>     Script to run (and optionally await) before tests start
+  --after=<file>      Script to run (and optionally await) after tests finish
+  --port=<n>          HTTP server port (auto-selects a free port if taken)
 ```
 
-You can browse [c8 documentation](https://github.com/bcoe/c8) for all configuration options.
+## Development
+
+```sh
+npm install
+make check                 # lint + test (run before every commit)
+make test                  # run tests only
+make demo                  # regenerate demo output
+make release LEVEL=patch   # bump version, update changelog, tag, push
+```
 
-Implementing code coverage for the browser mode is currently not possible because we use esbuild --bundle feature to
-create a JS bundles for testing in the browser, this could be instrumented with `puppeteer-to-istanbul` however
-instrumentation includes transpiled npm imports of `qunitx` and other potential npm imports developer
-includes in the code, this cannot be filtered since potential filtering can only occur after the `esbuild` bundling.
-When chrome browser and puppeteer fully supports ES asset maps we can remove esbuild from the browser mode, run
-everything in deno and make instrumentation for code coverage possible with the default v8 instrumentation.
+## License
 
-Esbuild plugin interface is an ongoing development, we might be able to figure out a way to generate this instrumentation
-with esbuild in the future, which could allow code coverage for --browser mode.
+MIT

package/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env -S TS_NODE_COMPILER_OPTIONS='{"module":"ES2020"}' node --loader ts-node/esm/transpile-only
+#!/usr/bin/env node
 import process from 'node:process';
 import displayHelpOutput from './lib/commands/help.js';
 import initializeProject from './lib/commands/init.js';

package/lib/boilerplates/default-project-config-values.js

@@ -2,5 +2,5 @@ export default {
   output: 'tmp',
   timeout: 20000,
   failFast: false,
-  port: 1234
-}
+  port: 1234,
+};

package/lib/boilerplates/test.js

@@ -1,6 +1,6 @@
 import { module, test } from 'qunitx';
 
-module('{{moduleName}}', function(hooks) {
+module('{{moduleName}}', function (hooks) {
   test('assert true works', function (assert) {
     assert.expect(3);
     assert.ok(true);
@@ -11,9 +11,10 @@ module('{{moduleName}}', function(hooks) {
   test('async test finishes', async function (assert) {
     assert.expect(3);
 
-    let wait = () => new Promise((resolve, reject) => {
-      setTimeout(() => resolve(true), 50);
-    });
+    let wait = () =>
+      new Promise((resolve, reject) => {
+        setTimeout(() => resolve(true), 50);
+      });
     let result = await wait();
 
     assert.ok(true);

package/lib/commands/generate.js

@@ -7,12 +7,13 @@ import pathExists from '../utils/path-exists.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-export default async function() {
+export default async function () {
   let projectRoot = await findProjectRoot();
   let moduleName = process.argv[3]; // TODO: classify this maybe in future
-  let path = process.argv[3].endsWith('.js') || process.argv[3].endsWith('.ts')
-    ? `${projectRoot}/${process.argv[3]}`
-    : `${projectRoot}/${process.argv[3]}.js`;
+  let path =
+    process.argv[3].endsWith('.js') || process.argv[3].endsWith('.ts')
+      ? `${projectRoot}/${process.argv[3]}`
+      : `${projectRoot}/${process.argv[3]}.js`;
 
   if (await pathExists(path)) {
     return console.log(`${path} already exists!`);
@@ -24,10 +25,7 @@ export default async function() {
   targetFolderPaths.pop();
 
   await fs.mkdir(targetFolderPaths.join('/'), { recursive: true });
-  await fs.writeFile(
-    path,
-    testJSContent.toString().replace('{{moduleName}}', moduleName)
-  );
+  await fs.writeFile(path, testJSContent.toString().replace('{{moduleName}}', moduleName));
 
   console.log(kleur.green(`${path} written`));
 }

package/lib/commands/help.js

@@ -7,30 +7,30 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const highlight = (text) => kleur.magenta().bold(text);
 const color = (text) => kleur.blue(text);
 
+export default async function () {
+  const config = JSON.parse(await fs.readFile(`${__dirname}/../../package.json`));
 
-export default async function() {
-  const config = JSON.parse((await fs.readFile(`${__dirname}/../../package.json`)));
+  console.log(`${highlight('[qunitx v' + config.version + '] Usage:')} qunitx ${color('[targets] --$flags')}
 
-  console.log(`${highlight("[qunitx v" + config.version + "] Usage:")} qunitx ${color('[targets] --$flags')}
-
-${highlight("Input options:")}
+${highlight('Input options:')}
 - File: $ ${color('qunitx test/foo.js')}
 - Folder: $ ${color('qunitx test/login')}
 - Globs: $ ${color('qunitx test/**/*-test.js')}
 - Combination: $ ${color('qunitx test/foo.js test/bar.js test/*-test.js test/logout')}
 
-${highlight("Optional flags:")}
+${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('--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
+${color('--port')} : HTTP server port (auto-selects a free port if the given port is taken)[default: 1234]
 ${color('--before')} : run a script before the tests(i.e start a new web server before tests)
 ${color('--after')} : run a script after the tests(i.e save test results to a file)
 
-${highlight("Example:")} $ ${color('qunitx test/foo.ts app/e2e --debug --watch --before=scripts/start-new-webserver.js --after=scripts/write-test-results.js')}
+${highlight('Example:')} $ ${color('qunitx test/foo.ts app/e2e --debug --watch --before=scripts/start-new-webserver.js --after=scripts/write-test-results.js')}
 
-${highlight("Commands:")}
+${highlight('Commands:')}
 ${color('$ qunitx init')}               # Bootstraps qunitx base html and add qunitx config to package.json if needed
 ${color('$ qunitx new $testFileName')}  # Creates a qunitx test file
 `);

package/lib/commands/init.js

@@ -7,49 +7,57 @@ import defaultProjectConfigValues from '../boilerplates/default-project-config-v
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-export default async function() {
+export default async function () {
   let projectRoot = await findProjectRoot();
   let oldPackageJSON = JSON.parse(await fs.readFile(`${projectRoot}/package.json`));
-  let htmlPaths = process.argv.slice(2).reduce((result, arg) => {
-    if (arg.endsWith('.html')) {
-      result.push(arg);
-    }
+  let htmlPaths = process.argv.slice(2).reduce(
+    (result, arg) => {
+      if (arg.endsWith('.html')) {
+        result.push(arg);
+      }
 
-    return result;
-  }, oldPackageJSON.qunitx && oldPackageJSON.qunitx.htmlPaths ? oldPackageJSON.qunitx.htmlPaths : []);
+      return result;
+    },
+    oldPackageJSON.qunitx && oldPackageJSON.qunitx.htmlPaths ? oldPackageJSON.qunitx.htmlPaths : [],
+  );
   let newQunitxConfig = Object.assign(
     defaultProjectConfigValues,
     htmlPaths.length > 0 ? { htmlPaths } : { htmlPaths: ['test/tests.html'] },
-    oldPackageJSON.qunitx
+    oldPackageJSON.qunitx,
   );
 
   await Promise.all([
     writeTestsHTML(projectRoot, newQunitxConfig, oldPackageJSON),
     rewritePackageJSON(projectRoot, newQunitxConfig, oldPackageJSON),
-    writeTSConfigIfNeeded(projectRoot)
+    writeTSConfigIfNeeded(projectRoot),
   ]);
 }
 
 async function writeTestsHTML(projectRoot, newQunitxConfig, oldPackageJSON) {
   let testHTMLTemplateBuffer = await fs.readFile(`${__dirname}/../boilerplates/setup/tests.hbs`);
 
-  return await Promise.all(newQunitxConfig.htmlPaths.map(async (htmlPath) => {
-    let targetPath = `${projectRoot}/${htmlPath}`;
-    if (await pathExists(targetPath)) {
-      return console.log(`${htmlPath} already exists`);
-    } else {
-      let targetDirectory = path.dirname(targetPath);
-      let targetOutputPath = path.relative(targetDirectory, `${projectRoot}/${newQunitxConfig.output}/tests.js`);
-      let testHTMLTemplate = testHTMLTemplateBuffer
-        .toString()
-        .replace('{{applicationName}}', oldPackageJSON.name);
+  return await Promise.all(
+    newQunitxConfig.htmlPaths.map(async (htmlPath) => {
+      let targetPath = `${projectRoot}/${htmlPath}`;
+      if (await pathExists(targetPath)) {
+        return console.log(`${htmlPath} already exists`);
+      } else {
+        let targetDirectory = path.dirname(targetPath);
+        let targetOutputPath = path.relative(
+          targetDirectory,
+          `${projectRoot}/${newQunitxConfig.output}/tests.js`,
+        );
+        let testHTMLTemplate = testHTMLTemplateBuffer
+          .toString()
+          .replace('{{applicationName}}', oldPackageJSON.name);
 
-      await fs.mkdir(targetDirectory, { recursive: true });
-      await fs.writeFile(targetPath, testHTMLTemplate);
+        await fs.mkdir(targetDirectory, { recursive: true });
+        await fs.writeFile(targetPath, testHTMLTemplate);
 
-      console.log(`${targetPath} written`);
-    }
-  }));
+        console.log(`${targetPath} written`);
+      }
+    }),
+  );
 }
 
 async function rewritePackageJSON(projectRoot, newQunitxConfig, oldPackageJSON) {
@@ -61,7 +69,9 @@ async function rewritePackageJSON(projectRoot, newQunitxConfig, oldPackageJSON)
 async function writeTSConfigIfNeeded(projectRoot) {
   let targetPath = `${projectRoot}/tsconfig.json`;
   if (!(await pathExists(targetPath))) {
-    let tsConfigTemplateBuffer = await fs.readFile(`${__dirname}/../boilerplates/setup/tsconfig.json`);
+    let tsConfigTemplateBuffer = await fs.readFile(
+      `${__dirname}/../boilerplates/setup/tsconfig.json`,
+    );
 
     await fs.writeFile(targetPath, tsConfigTemplateBuffer);
 

package/lib/commands/run/tests-in-browser.js

@@ -17,81 +17,99 @@ class BundleError extends Error {
   }
 }
 
+// Exported so run.js can pre-build all group bundles in parallel with Chrome startup.
+export async function buildTestBundle(config, cachedContent) {
+  const { projectRoot, output } = config;
+  const allTestFilePaths = Object.keys(config.fsTree);
+
+  await Promise.all([
+    esbuild.build({
+      stdin: {
+        contents: allTestFilePaths.map((f) => `import "${f}";`).join(''),
+        resolveDir: process.cwd(),
+      },
+      bundle: true,
+      logLevel: 'error',
+      outfile: `${projectRoot}/${output}/tests.js`,
+      keepNames: true,
+      sourcemap: 'inline',
+    }),
+    Promise.all(
+      cachedContent.htmlPathsToRunTests.map(async (htmlPath) => {
+        const targetPath = `${config.projectRoot}/${config.output}${htmlPath}`;
+        if (htmlPath !== '/') {
+          await fs.rm(targetPath, { force: true, recursive: true });
+          await fs.mkdir(targetPath.split('/').slice(0, -1).join('/'), { recursive: true });
+        }
+      }),
+    ),
+  ]);
+
+  cachedContent.allTestCode = await fs.readFile(`${projectRoot}/${output}/tests.js`);
+}
+
 export default async function runTestsInBrowser(
   config,
   cachedContent = {},
   connections,
-  targetTestFilesToFilter
+  targetTestFilesToFilter,
 ) {
-  const { projectRoot, timeout, output } = config;
+  const { projectRoot, output } = config;
   const allTestFilePaths = Object.keys(config.fsTree);
   const runHasFilter = !!targetTestFilesToFilter;
 
-  config.COUNTER = { testCount: 0, failCount: 0, skipCount: 0, passCount: 0 };
+  // In group mode the COUNTER is shared across all groups and managed by run.js.
+  if (!config._groupMode) {
+    config.COUNTER = { testCount: 0, failCount: 0, skipCount: 0, passCount: 0 };
+  }
   config.lastRanTestFiles = targetTestFilesToFilter || allTestFilePaths;
 
   try {
-    await Promise.all([
-      esbuild.build({
-        stdin: {
-          contents: allTestFilePaths.reduce((result, fileAbsolutePath) => {
-            return result + `import "${fileAbsolutePath}";`
-          }, ''),
-          resolveDir: process.cwd()
-        },
-        bundle: true,
-        logLevel: 'error',
-        outfile: `${projectRoot}/${output}/tests.js`,
-        keepNames: true
-      }), // NOTE: This prevents file cache most likely
-      Promise.all(cachedContent.htmlPathsToRunTests.map(async (htmlPath) => {
-        let targetPath = `${config.projectRoot}/${config.output}${htmlPath}`;
-
-        if (htmlPath !== '/') {
-          await fs.rm(targetPath, { force: true, recursive: true });
-          await fs.mkdir(targetPath.split('/').slice(0, -1).join('/'), { recursive: true }); // NOTE: this can be done earlier
-        }
-      }))
-    ]);
-    cachedContent.allTestCode = await fs.readFile(`${projectRoot}/${output}/tests.js`);
+    // Skip bundle build if run.js already pre-built it (group mode optimization).
+    if (!cachedContent.allTestCode) {
+      await buildTestBundle(config, cachedContent);
+    }
 
     if (runHasFilter) {
-      let outputPath = `${projectRoot}/${output}/filtered-tests.js`;
-
+      const outputPath = `${projectRoot}/${output}/filtered-tests.js`;
       await buildFilteredTests(targetTestFilesToFilter, outputPath);
       cachedContent.filteredTestCode = (await fs.readFile(outputPath)).toString();
     }
 
-    let TIME_COUNTER = timeCounter();
+    const TIME_COUNTER = timeCounter();
 
     if (runHasFilter) {
       await runTestInsideHTMLFile('/qunitx.html', connections, config);
     } else {
-      await Promise.all(cachedContent.htmlPathsToRunTests.map((htmlPath) => {
-        return runTestInsideHTMLFile(htmlPath, connections, config); // NOTE: maybe make this blocking
-      }));
+      await Promise.all(
+        cachedContent.htmlPathsToRunTests.map((htmlPath) =>
+          runTestInsideHTMLFile(htmlPath, connections, config),
+        ),
+      );
     }
 
-    let TIME_TAKEN = TIME_COUNTER.stop()
-
-    TAPDisplayFinalResult(config.COUNTER, TIME_TAKEN);
+    const TIME_TAKEN = TIME_COUNTER.stop();
 
-    if (config.after) {
-      await runUserModule(`${process.cwd()}/${config.after}`, config.COUNTER, 'after');
-    }
+    // In group mode the parent orchestrator handles the final summary, after hook, and exit.
+    if (!config._groupMode) {
+      TAPDisplayFinalResult(config.COUNTER, TIME_TAKEN);
 
-    if (!config.watch) {
-      await Promise.all([
-        connections.server && connections.server.close(),
-        connections.browser && connections.browser.close()
-      ]);
+      if (config.after) {
+        await runUserModule(`${process.cwd()}/${config.after}`, config.COUNTER, 'after');
+      }
 
-      return process.exit(config.COUNTER.failCount > 0 ? 1 : 0);
+      if (!config.watch) {
+        await Promise.all([
+          connections.server && connections.server.close(),
+          connections.browser && connections.browser.close(),
+        ]);
+        return process.exit(config.COUNTER.failCount > 0 ? 1 : 0);
+      }
     }
-  } catch(error) {
+  } catch (error) {
     config.lastFailedTestFiles = config.lastRanTestFiles;
     console.log(error);
-    let exception = new BundleError(error);
+    const exception = new BundleError(error);
 
     if (config.watch) {
       console.log(`# ${exception}`);
@@ -106,31 +124,41 @@ export default async function runTestsInBrowser(
 function buildFilteredTests(filteredTests, outputPath) {
   return esbuild.build({
     stdin: {
-      contents: filteredTests.reduce((result, fileAbsolutePath) => {
-        return result + `import "${fileAbsolutePath}";`
-      }, ''),
-      resolveDir: process.cwd()
+      contents: filteredTests.map((f) => `import "${f}";`).join(''),
+      resolveDir: process.cwd(),
     },
     bundle: true,
     logLevel: 'error',
-    outfile: outputPath
+    outfile: outputPath,
+    sourcemap: 'inline',
   });
 }
 
-async function runTestInsideHTMLFile(filePath, { page, server }, config) {
+async function runTestInsideHTMLFile(filePath, { page, server, browser }, config) {
   let QUNIT_RESULT;
   let targetError;
   try {
-    await wait(350);
     console.log('#', kleur.blue(`QUnitX running: http://localhost:${config.port}${filePath}`));
-    await page.goto(`http://localhost:${config.port}${filePath}`, { timeout: 0 });
-    await page.evaluate(() => {
+
+    const testsDone = new Promise((resolve) => {
+      config._testRunDone = resolve;
+    });
+
+    await page.evaluateOnNewDocument(() => {
       window.IS_PUPPETEER = true;
     });
-    await page.waitForFunction(`window.testTimeout >= ${config.timeout}`, { timeout: 0 });
+    await page.goto(`http://localhost:${config.port}${filePath}`, {
+      timeout: config.timeout + 10000,
+    });
+    await Promise.race([
+      testsDone,
+      page.waitForFunction(`window.testTimeout >= ${config.timeout}`, {
+        timeout: config.timeout + 10000,
+      }),
+    ]);
 
     QUNIT_RESULT = await page.evaluate(() => window.QUNIT_RESULT);
-  } catch(error) {
+  } catch (error) {
     targetError = error;
     console.log(error);
     console.error(error);
@@ -140,23 +168,25 @@ async function runTestInsideHTMLFile(filePath, { page, server }, config) {
     console.log(targetError);
     console.log('BROWSER: runtime error thrown during executing tests');
     console.error('BROWSER: runtime error thrown during executing tests');
-
-    await failOnNonWatchMode(config.watch);
+    await failOnNonWatchMode(config.watch, { server, browser }, config._groupMode);
   } else if (QUNIT_RESULT.totalTests > QUNIT_RESULT.finishedTests) {
     console.log(targetError);
     console.log(`BROWSER: TEST TIMED OUT: ${QUNIT_RESULT.currentTest}`);
     console.error(`BROWSER: TEST TIMED OUT: ${QUNIT_RESULT.currentTest}`);
-
-    await failOnNonWatchMode(config.watch);
+    await failOnNonWatchMode(config.watch, { server, browser }, config._groupMode);
   }
 }
 
-async function failOnNonWatchMode(watchMode = false) {
+async function failOnNonWatchMode(watchMode = false, connections = {}, groupMode = false) {
   if (!watchMode) {
-    await new Promise((resolve, reject) => setTimeout(() => resolve(process.exit(1)), 100));
+    if (groupMode) {
+      // Parent orchestrator handles cleanup and exit; signal failure via throw.
+      throw new Error('Browser test run failed');
+    }
+    await Promise.all([
+      connections.server && connections.server.close(),
+      connections.browser && connections.browser.close(),
+    ]);
+    process.exit(1);
   }
 }
-
-function wait(duration) {
-  return new Promise((resolve) => setTimeout(() => { resolve() }, duration));
-}