qunitx-cli 0.21.3 → 0.22.0

package/README.md

@@ -14,8 +14,9 @@ output to the terminal.
 
 ## Features
 
-- Runs `.js` and `.ts` test files in headless Chrome, Firefox, or WebKit (Playwright + esbuild)
-- TypeScript works with zero configuration — esbuild handles transpilation
+- Runs `.js`, `.ts`, `.jsx`, and `.tsx` test files in headless Chrome, Firefox, or WebKit (Playwright + esbuild)
+- TypeScript and JSX work with zero configuration — esbuild handles transpilation, including the React 17+ automatic JSX runtime
+- Bring your own esbuild plugins through `package.json` for `.vue`, `.svelte`, and other custom loaders
 - 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
@@ -165,29 +166,93 @@ All CLI flags can also be set in `package.json` under the `qunitx` key, so you d
   "qunitx": {
     "inputs": ["test/**/*-test.js", "test/**/*-test.ts"],
     "htmlPaths": ["test/tests.html"],
-    "extensions": ["js", "ts"],
+    "extensions": ["js", "ts", "jsx", "tsx"],
     "output": "tmp",
     "timeout": 20000,
     "failFast": false,
     "port": 1234,
-    "browser": "chromium"
+    "browser": "chromium",
+    "plugins": []
   }
 }
 ```
 
-| Key          | Default        | Description                                                                                                                                                             |
-| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `inputs`     | `[]`           | Glob patterns, file paths, or directories to use as test entry points. Merged with any paths given on the CLI.                                                          |
-| `htmlPaths`  | `[]`           | Optional HTML templates to run tests inside. Any listed `.html` file that contains `{{qunitxScript}}` or other handlebars-style tokens is treated as a test runner template. |
-| `extensions` | `["js", "ts"]` | File extensions tracked for test discovery (directory scans) and watch-mode rebuild triggers. Add `"mjs"`, `"cjs"`, or any other extension your project uses.           |
-| `output`     | `"tmp"`        | Directory where compiled test bundles are written.                                                                                                                      |
-| `timeout`    | `20000`        | Maximum milliseconds to wait for the full test suite before timing out.                                                                                                 |
-| `failFast`   | `false`        | Stop the run after the first failing test.                                                                                                                              |
-| `port`       | `1234`         | Preferred HTTP server port. qunitx auto-selects a free port if this one is taken.                                                                                       |
-| `browser`    | `"chromium"`   | Browser engine to use: `"chromium"`, `"firefox"`, or `"webkit"`. Overridden by `--browser` on the CLI.                                                                  |
+| Key          | Default                       | Description                                                                                                                                                                 |
+| ------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `inputs`     | `[]`                          | Glob patterns, file paths, or directories to use as test entry points. Merged with any paths given on the CLI.                                                              |
+| `htmlPaths`  | `[]`                          | Optional HTML templates to run tests inside. Any listed `.html` file that contains `{{qunitxScript}}` or other handlebars-style tokens is treated as a test runner template. |
+| `extensions` | `["js", "ts", "jsx", "tsx"]`  | File extensions tracked for test discovery (directory scans) and watch-mode rebuild triggers. Add `"mjs"`, `"cjs"`, or any other extension your project uses.               |
+| `output`     | `"tmp"`                       | Directory where compiled test bundles are written.                                                                                                                          |
+| `timeout`    | `20000`                       | Maximum milliseconds to wait for the full test suite before timing out.                                                                                                     |
+| `failFast`   | `false`                       | Stop the run after the first failing test.                                                                                                                                  |
+| `port`       | `1234`                        | Preferred HTTP server port. qunitx auto-selects a free port if this one is taken.                                                                                           |
+| `browser`    | `"chromium"`                  | Browser engine to use: `"chromium"`, `"firefox"`, or `"webkit"`. Overridden by `--browser` on the CLI.                                                                      |
+| `plugins`    | `[]`                          | esbuild plugin specifiers loaded from your `node_modules` and applied to the test bundle. See [esbuild plugins](#esbuild-plugins).                                          |
 
 CLI flags always override `package.json` values when both are present.
 
+## JSX / TSX
+
+`.jsx` and `.tsx` files are picked up automatically — no configuration needed. The bundle uses esbuild's automatic JSX runtime so React 17+ "no `import React`" code just works:
+
+```tsx
+// test/button-test.tsx
+import { module, test } from 'qunitx';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import { Button } from '../src/button.tsx';
+
+module('Button', (hooks) => {
+  let container;
+  hooks.beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+  hooks.afterEach(() => container.remove());
+
+  test('renders the label', (assert) => {
+    flushSync(() => createRoot(container).render(<Button label="Save" />));
+    assert.equal(container.querySelector('button').textContent, 'Save');
+  });
+});
+```
+
+Vue, Preact, Solid, and other JSX dialects work via a one-line override at the top of each file:
+
+```tsx
+/** @jsxImportSource vue */
+import { createApp } from 'vue';
+// ...JSX uses vue/jsx-runtime instead of react/jsx-runtime
+```
+
+You can also set `compilerOptions.jsxImportSource` in your `tsconfig.json` to apply the override across a directory.
+
+## esbuild plugins
+
+For file formats esbuild does not handle natively (e.g. `.vue` SFCs, `.svelte`), declare plugin specifiers in `package.json#qunitx.plugins`. qunitx dynamic-imports each one from your project's `node_modules` and passes it to the build:
+
+```json
+{
+  "qunitx": {
+    "extensions": ["js", "ts", "jsx", "tsx", "vue"],
+    "plugins": [
+      "esbuild-plugin-vue-next",
+      ["esbuild-svelte", { "compilerOptions": { "css": "injected" } }]
+    ]
+  }
+}
+```
+
+Each entry is one of:
+
+| Form                          | Behavior                                                                                                                                                  |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"<package-name>"`             | Imports the package. If the default export is a function, it's called with no arguments to produce the plugin; otherwise the export is used as the plugin. |
+| `["<package-name>", <options>]` | Same, but the factory is called with `<options>` as its only argument. Use this form to pass plugin-specific configuration.                                |
+| `"./relative/plugin.js"`       | Loads a plugin you wrote yourself. Resolved against the project root (where your `package.json` lives).                                                   |
+
+Don't forget to add the plugin's file extension(s) to `qunitx.extensions` so directory scans and watch-mode rebuilds pick them up.
+
 ### Environment variables
 
 | Variable         | Description                                                                                                   |
@@ -218,7 +283,7 @@ Options:
   --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]
-  --extensions=<...>  Comma-separated file extensions to track  [default: js,ts]
+  --extensions=<...>  Comma-separated file extensions to track  [default: js,ts,jsx,tsx]
   --before=<file>     Script to run (and optionally await) before tests start
   --after=<file>      Script to run (and optionally await) after tests finish
   --open, -o          Open output in the test browser as soon as the bundle is ready

package/dist/cli.js

@@ -377,6 +377,21 @@ var init_color = __esm({
   }
 });
 
+// lib/setup/default-project-config-values.ts
+var defaultProjectConfigValues;
+var init_default_project_config_values = __esm({
+  "lib/setup/default-project-config-values.ts"() {
+    defaultProjectConfigValues = {
+      output: "tmp",
+      timeout: 2e4,
+      failFast: false,
+      port: 1234,
+      extensions: ["js", "ts", "jsx", "tsx"],
+      browser: "chromium"
+    };
+  }
+});
+
 // lib/utils/read-template.ts
 import fs3 from "node:fs/promises";
 import { dirname, join as join2 } from "node:path";
@@ -1987,10 +2002,10 @@ 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";
+import { pathToFileURL as pathToFileURL2 } from "node:url";
 async function openOutputInBrowser(config) {
   try {
-    const outputFile = config.watch ? `http://localhost:${config.port}` : pathToFileURL(path6.join(path6.resolve(config.projectRoot, config.output), "index.html")).href;
+    const outputFile = config.watch ? `http://localhost:${config.port}` : pathToFileURL2(path6.join(path6.resolve(config.projectRoot, config.output), "index.html")).href;
     if (typeof config.open === "string") {
       spawnDetached(config.open, [outputFile]);
       return;
@@ -2036,10 +2051,10 @@ var init_time_counter = __esm({
 });
 
 // lib/utils/run-user-module.ts
-import { pathToFileURL as pathToFileURL2 } from "node:url";
+import { pathToFileURL as pathToFileURL3 } from "node:url";
 async function runUserModule(modulePath, params, scriptPosition) {
   try {
-    const func = await import(pathToFileURL2(modulePath).href);
+    const func = await import(pathToFileURL3(modulePath).href);
     if (func) {
       func.default ? await func.default(params) : typeof func === "function" ? await func(params) : null;
     }
@@ -2140,6 +2155,11 @@ async function buildTestBundle(config, cachedContent) {
     legalComments: "none",
     target: esbuildTarget(config.browser),
     sourcemap,
+    // jsx: 'automatic' is a no-op for .ts/.js files (extension-gated by esbuild) and emits
+    // `import { jsx } from 'react/jsx-runtime'` for .tsx/.jsx files. Per-file overrides via
+    // tsconfig's `jsxImportSource` or a `@jsxImportSource <pkg>` pragma cover Vue/Preact/Solid.
+    jsx: "automatic",
+    plugins: config.plugins,
     // Signal the runtime that all test modules are registered. The runtime's maybeStart()
     // waits for both this event and the WebSocket 'open' event before calling QUnit.start().
     // Dispatching from the bundle (rather than from a script onload attr) is reliable across
@@ -2345,7 +2365,10 @@ async function buildAllGroupBundles(groupConfigs, groupCachedContents) {
       in: `group-entry-${slotIndex}`,
       out: `group-${slotIndex}`
     })),
-    plugins: [groupEntryPlugin],
+    // groupEntryPlugin must run first — it owns the virtual entry-point modules every other
+    // plugin sees. User plugins follow and apply to the resolved test files just like in
+    // single-group mode (`buildTestBundle`).
+    plugins: [groupEntryPlugin, ...groupConfigs[0].plugins ?? []],
     nodePaths: ANCESTOR_NODE_MODULES,
     bundle: true,
     logLevel: "silent",
@@ -2357,6 +2380,7 @@ async function buildAllGroupBundles(groupConfigs, groupCachedContents) {
     target: esbuildTarget(browser),
     sourcemap,
     write: false,
+    jsx: "automatic",
     footer: { js: 'window.dispatchEvent(new CustomEvent("qunitx:tests-ready"));' }
   };
   const hasSmallOutput = (result) => (result.outputFiles ?? []).some(
@@ -2425,6 +2449,8 @@ function buildFilteredTests(filteredTests, outputPath, config) {
       legalComments: "none",
       target: esbuildTarget(config.browser),
       sourcemap,
+      jsx: "automatic",
+      plugins: config.plugins,
       footer: { js: 'window.dispatchEvent(new CustomEvent("qunitx:tests-ready"));' }
     },
     needsDisk
@@ -2620,7 +2646,7 @@ import fs10 from "node:fs";
 import { readdir, stat, lstat } from "node:fs/promises";
 import path8 from "node:path";
 function setupFileWatchers(testFileLookupPaths, config, onEventFunc, onFinishFunc) {
-  const extensions = config.extensions || ["js", "ts"];
+  const extensions = config.extensions || defaultProjectConfigValues.extensions;
   const readyPromises = [];
   const parentWatchers = [];
   const rescanTimers = [];
@@ -2884,6 +2910,7 @@ var CHANGE_DEDUPE_MS, SYMLINK_POLL_INTERVAL_MS, OVERLAYFS_RENAME_RETRY_MS, RESCA
 var init_file_watcher = __esm({
   "lib/setup/file-watcher.ts"() {
     init_color();
+    init_default_project_config_values();
     CHANGE_DEDUPE_MS = 10;
     SYMLINK_POLL_INTERVAL_MS = 500;
     OVERLAYFS_RENAME_RETRY_MS = 50;
@@ -3004,7 +3031,8 @@ __export(run_exports, {
   run: () => run
 });
 import fs12 from "node:fs/promises";
-import { normalize } from "node:path";
+import { join as join3, normalize } from "node:path";
+import { createRequire as createRequire2 } from "node:module";
 import { availableParallelism } from "node:os";
 async function run(config) {
   const browserPromise = config.watch ? null : launchBrowser(config);
@@ -3296,7 +3324,7 @@ async function addCachedContentMainHTML(projectRoot, cachedContent) {
   } else {
     const html = await readTemplate("setup/tests.hbs");
     cachedContent.mainHTML = { filePath: `${projectRoot}/test/tests.html`, html };
-    cachedContent.assets.add(`${projectRoot}/node_modules/qunitx/vendor/qunit.css`);
+    cachedContent.assets.add(join3(resolveQunitxRoot(projectRoot), "vendor/qunit.css"));
   }
   return cachedContent;
 }
@@ -3369,6 +3397,12 @@ function normalizeInternalAssetPathFromHTML(projectRoot, assetPath, htmlPath) {
   const currentDirectory = htmlPath ? htmlPath.split("/").slice(0, -1).join("/") : projectRoot;
   return assetPath.startsWith("./") ? normalize(`${currentDirectory}/${assetPath.slice(2)}`) : normalize(`${currentDirectory}/${assetPath}`);
 }
+function resolveQunitxRoot(projectRoot) {
+  const mainEntry = createRequire2(`${projectRoot}/package.json`).resolve("qunitx");
+  const match = /^(.*[\\/]qunitx)[\\/]/.exec(mainEntry);
+  if (!match) throw new Error(`Could not derive qunitx root from ${mainEntry}`);
+  return match[1];
+}
 var WATCH_NAV_TIMEOUT_MS, PAGE_CLOSE_GRACE_MS, STDOUT_FLUSH_GRACE_MS, KEEP_ALIVE_INTERVAL_MS, EXIT_CODE_SIGTERM;
 var init_run = __esm({
   "lib/commands/run.ts"() {
@@ -3408,7 +3442,7 @@ init_color();
 var package_default = {
   name: "qunitx-cli",
   type: "module",
-  version: "0.21.3",
+  version: "0.22.0",
   description: "Browser runner for QUnitx: run your qunitx tests in google-chrome",
   author: "Izel Nakri",
   license: "MIT",
@@ -3465,8 +3499,11 @@ var package_default = {
   devDependencies: {
     "js-yaml": "^4.1.1",
     prettier: "^3.8.3",
-    qunitx: "^1.2.8",
-    typescript: "^6.0.3"
+    qunitx: "^1.2.9",
+    react: "^19.2.5",
+    "react-dom": "^19.2.5",
+    typescript: "^6.0.3",
+    vue: "^3.5.33"
   },
   volta: {
     node: "24.14.0"
@@ -3502,7 +3539,7 @@ ${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("--extensions")} : comma-separated file extensions to track for discovery and watch-mode rebuilds[default: js,ts]
+${color("--extensions")} : comma-separated file extensions to track for discovery and watch-mode rebuilds[default: js,ts,jsx,tsx]
 ${color("--browser")} : browser engine to run tests in: chromium, firefox, webkit[default: chromium]
 ${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)
@@ -3561,17 +3598,8 @@ async function findProjectRoot() {
   }
 }
 
-// lib/setup/default-project-config-values.ts
-var defaultProjectConfigValues = {
-  output: "tmp",
-  timeout: 2e4,
-  failFast: false,
-  port: 1234,
-  extensions: ["js", "ts"],
-  browser: "chromium"
-};
-
 // lib/commands/init.ts
+init_default_project_config_values();
 init_read_template();
 async function initializeProject() {
   const projectRoot = await findProjectRoot();
@@ -3658,13 +3686,17 @@ function pathToModuleName(filePath) {
 }
 
 // lib/setup/config.ts
+init_default_project_config_values();
 import fs7 from "node:fs/promises";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
 
 // lib/setup/fs-tree.ts
+init_default_project_config_values();
 import fs6, { glob as fsGlob } from "node:fs/promises";
 import path3 from "node:path";
 async function buildFSTree(fileAbsolutePaths, config = {}) {
-  const targetExtensions = config.extensions || ["js", "ts"];
+  const targetExtensions = config.extensions || defaultProjectConfigValues.extensions;
   const fsTree = {};
   await Promise.all(
     fileAbsolutePaths.map(async (fileAbsolutePath) => {
@@ -3849,11 +3881,13 @@ async function setupConfig() {
   const projectRoot = await findProjectRoot();
   const cliConfigFlags = parseCliFlags(projectRoot);
   const projectPackageJSON = await readConfigFromPackageJSON(projectRoot);
+  const { plugins: rawPlugins, ...userQunitx } = projectPackageJSON.qunitx ?? {};
+  const pluginsPromise = resolvePlugins(rawPlugins, projectRoot);
   const inputs2 = cliConfigFlags.inputs.concat(readInputsFromPackageJSON(projectPackageJSON));
   const config = {
     ...defaultProjectConfigValues,
     htmlPaths: [],
-    ...projectPackageJSON.qunitx || {},
+    ...userQunitx,
     ...cliConfigFlags,
     projectRoot,
     inputs: inputs2,
@@ -3874,7 +3908,10 @@ async function setupConfig() {
     _onTestsJsServed: null
   };
   config.htmlPaths = normalizeHTMLPaths(config.projectRoot, config.htmlPaths);
-  config.fsTree = await buildFSTree(config.testFileLookupPaths, config);
+  [config.fsTree, config.plugins] = await Promise.all([
+    buildFSTree(config.testFileLookupPaths, config),
+    pluginsPromise
+  ]);
   return config;
 }
 async function readConfigFromPackageJSON(projectRoot) {
@@ -3888,6 +3925,22 @@ function readInputsFromPackageJSON(packageJSON) {
   const qunitx = packageJSON.qunitx;
   return qunitx && qunitx.inputs ? qunitx.inputs : [];
 }
+function resolvePlugins(raw, projectRoot) {
+  if (raw == null) return Promise.resolve([]);
+  if (!Array.isArray(raw)) {
+    console.error(`# qunitx: package.json#qunitx.plugins must be an array`);
+    process.exit(1);
+  }
+  const projectRequire = createRequire(`${projectRoot}/package.json`);
+  return Promise.all(
+    raw.map(async (entry) => {
+      const [spec, options] = Array.isArray(entry) ? entry : [entry];
+      const mod = await import(pathToFileURL(projectRequire.resolve(spec)).href);
+      const exported = mod.default ?? mod;
+      return typeof exported === "function" ? exported(options) : exported;
+    })
+  );
+}
 
 // cli.ts
 process4.title = "qunitx";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "qunitx-cli",
   "type": "module",
-  "version": "0.21.3",
+  "version": "0.22.0",
   "description": "Browser runner for QUnitx: run your qunitx tests in google-chrome",
   "author": "Izel Nakri",
   "license": "MIT",
@@ -58,8 +58,11 @@
   "devDependencies": {
     "js-yaml": "^4.1.1",
     "prettier": "^3.8.3",
-    "qunitx": "^1.2.8",
-    "typescript": "^6.0.3"
+    "qunitx": "^1.2.9",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^6.0.3",
+    "vue": "^3.5.33"
   },
   "volta": {
     "node": "24.14.0"