qunitx-cli 0.1.2 → 0.5.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)"
+    ]
+  }
+}

package/.env

@@ -0,0 +1 @@
+export CHROME_BIN=$(which google-chrome-stable)

package/Makefile

@@ -0,0 +1,35 @@
+.PHONY: check test lint build demo release
+
+check: lint test
+
+lint:
+	npm run lint
+
+test:
+	npm test
+
+build:
+	npm run build
+
+# Regenerate demo/demo.gif using VHS.
+# Requires: vhs (brew install vhs | nix profile install nixpkgs#vhs)
+#           Chrome (google-chrome-stable or chromium)
+demo:
+	@which vhs > /dev/null 2>&1 || (echo "vhs not found — install: brew install vhs  or  nix profile install nixpkgs#vhs" && exit 1)
+	@CHROME=$$(which google-chrome-stable 2>/dev/null || which google-chrome 2>/dev/null || which chromium 2>/dev/null); \
+	test -n "$$CHROME" || (echo "Chrome not found — install google-chrome-stable or chromium" && exit 1); \
+	CHROME_BIN=$$CHROME vhs demo/demo.tape
+
+# Lint, bump version, update changelog, commit, tag, push, publish to npm.
+# CI then pushes the versioned Docker image and creates the GitHub release.
+# Usage: make release LEVEL=patch|minor|major
+release:
+	@test -n "$(LEVEL)" || (echo "Usage: make release LEVEL=patch|minor|major" && exit 1)
+	npm run lint
+	npm version $(LEVEL) --no-git-tag-version
+	npm run changelog:update
+	git add package.json package-lock.json CHANGELOG.md
+	git commit -m "Release $$(node -p 'require("./package.json").version')"
+	git tag "v$$(node -p 'require("./package.json").version')"
+	git push && git push --tags
+	npm publish --access public

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/cliff.toml

@@ -0,0 +1,23 @@
+[changelog]
+header = """# Changelog
+
+All notable changes to this project will be documented in this file.
+"""
+body = """
+{% if version %}\
+## {{ version | trim_start_matches(pat="v") }} — {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+## Unreleased
+{% endif %}\
+{% for commit in commits %}\
+- {{ commit.message | split(pat="\n") | first | trim | upper_first }}
+{% endfor %}
+"""
+footer = ""
+trim = true
+
+[git]
+conventional_commits = false
+filter_unconventional = false
+tag_pattern = "v[0-9].*"
+sort_commits = "newest"

package/demo/demo.tape

@@ -0,0 +1,59 @@
+# qunitx-cli demo — generates demo/demo.gif
+# Run via: make demo  (handles Chrome discovery automatically)
+
+Output demo/demo.gif
+
+Set Shell bash
+Set FontSize 15
+Set Width 800
+Set Height 750
+Set Theme "Dracula"
+Set Padding 20
+Set Framerate 24
+Set TypingSpeed 45ms
+
+Env PUPPETEER_SKIP_DOWNLOAD "true"
+Env FORCE_COLOR "1"
+Env PS1 "$ "
+
+# ── 1. Show the test file ─────────────────────────────────────────────────────
+Type "# 1/5  Inspect the test file"
+Enter
+Sleep 400ms
+Type "cat demo/example-test.js"
+Enter
+Sleep 3000ms
+
+# ── 2. Run all tests — concurrent by default, all green ──────────────────────
+Type "# 2/5  Run tests — concurrent by default"
+Enter
+Sleep 400ms
+Type "qunitx demo/example-test.js"
+Enter
+Sleep 7000ms
+
+# ── 3. --debug: pipe Chrome's console.log to your terminal ───────────────────
+Type "# 3/5  --debug: pipe Chrome console to your terminal"
+Enter
+Sleep 400ms
+Type "qunitx demo/example-test.js --debug"
+Enter
+Sleep 7000ms
+
+# ── 4. --failFast: stop immediately on the first failure ─────────────────────
+Type "# 4/5  --failFast: stop on the first failure"
+Enter
+Sleep 400ms
+Type "qunitx demo/failing-test.js --failFast"
+Enter
+Sleep 7000ms
+
+# ── 5. --watch: stay alive and re-run on every file save ─────────────────────
+Type "# 5/5  --watch: re-run on every file save"
+Enter
+Sleep 400ms
+Type "qunitx demo/example-test.js --watch"
+Enter
+Sleep 6000ms
+Ctrl+C
+Sleep 1200ms

package/demo/example-test.js

@@ -0,0 +1,53 @@
+import { module, test } from 'qunitx';
+
+// Tests run in real headless Chrome — not jsdom, not Node.js.
+
+module('Browser', () => {
+  test('has window, document & navigator', (assert) => {
+    assert.ok(typeof window !== 'undefined', 'window exists');
+    assert.ok(document.body !== null, 'document.body exists');
+    assert.ok(navigator.userAgent.includes('Chrome'), 'running in Chrome');
+  });
+
+  test('can build and query a DOM tree', (assert) => {
+    const ul = document.createElement('ul');
+    ['Alice', 'Bob', 'Carol'].forEach((name) => {
+      const li = document.createElement('li');
+      li.textContent = name;
+      ul.appendChild(li);
+    });
+    assert.equal(ul.querySelectorAll('li').length, 3);
+    assert.equal(ul.querySelector('li').textContent, 'Alice');
+  });
+
+  test('crypto.randomUUID() works', (assert) => {
+    const id = crypto.randomUUID();
+    console.log('[debug] uuid:', id);
+    assert.ok(/^[0-9a-f-]{36}$/.test(id), 'valid UUID format');
+  });
+});
+
+module('Async', () => {
+  test('resolves a promise', async (assert) => {
+    const value = await Promise.resolve('hello from Chrome');
+    assert.equal(value, 'hello from Chrome');
+  });
+
+  test('rejects are caught', async (assert) => {
+    await assert.rejects(Promise.reject(new Error('boom')), /boom/);
+  });
+});
+
+module('Assertions', () => {
+  test('equal & deepEqual', (assert) => {
+    assert.equal(1 + 1, 2);
+    assert.deepEqual(
+      { user: 'alice', roles: ['admin', 'viewer'] },
+      { user: 'alice', roles: ['admin', 'viewer'] },
+    );
+  });
+
+  test('throws on bad input', (assert) => {
+    assert.throws(() => JSON.parse('{bad json}'), SyntaxError);
+  });
+});

package/demo/failing-test.js

@@ -0,0 +1,22 @@
+import { module, test } from 'qunitx';
+
+module('Cart', () => {
+  test('calculates subtotal', (assert) => {
+    const items = [{ price: 10 }, { price: 20 }, { price: 5 }];
+    const total = items.reduce((sum, item) => sum + item.price, 0);
+    assert.equal(total, 35, 'subtotal is correct');
+  });
+
+  test('applies 10% discount', (assert) => {
+    assert.equal(Math.round(100 * 0.9), 90);
+  });
+
+  test('validates stock level', (assert) => {
+    const stock = 0;
+    assert.ok(stock > 0, 'expected items in stock'); // ← will fail
+  });
+
+  test('calculates tax', (assert) => {
+    assert.equal(100 * 0.2, 20); // ← never reached with --failFast
+  });
+});

package/flake.lock

@@ -38,16 +38,16 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1690860117,
-        "narHash": "sha256-srkCfjMlg777HxDVMfhkIFgRhhtuZjIOIyR2ejLYK+Y=",
+        "lastModified": 1772822230,
+        "narHash": "sha256-yf3iYLGbGVlIthlQIk5/4/EQDZNNEmuqKZkQssMljuw=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "96d403ee2479f2070050353b94808209f1352edb",
+        "rev": "71caefce12ba78d84fe618cf61644dce01cf3a96",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "nixpkgs-unstable",
+        "ref": "nixos-25.11",
         "repo": "nixpkgs",
         "type": "github"
       }

package/flake.nix

@@ -1,7 +1,7 @@
 {
   description = "A flake for napalm";
 
-  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
   inputs.napalm.url = "github:nix-community/napalm";
 
   # NOTE: This is optional, but is how to configure napalm's env
@@ -13,14 +13,43 @@
     pkgs = nixpkgs.legacyPackages."${system}";
   in {
     packages."${system}".default = napalm.legacyPackages."${system}".buildPackage ./. {
-      nodejs = pkgs.nodejs_20;
+      nodejs = pkgs.nodejs_24;
       PUPPETEER_SKIP_DOWNLOAD=1;
     };
 
     devShells."${system}".default = pkgs.mkShell {
-      nativeBuildInputs = with pkgs; [
-        nodejs_20
+      nativeBuildInputs = [
+        pkgs.pkg-config
+        pkgs.deno
+        pkgs.nodejs_24
+        pkgs.git-cliff
+        pkgs.vhs
+        # self.packages.default.nativeBuildInputs
+        # self.packages.default.buildInputs
       ];
+
+      doCheck = false; # Disables automatically running tests for `$ nix develop` and direnv
+
+      shellHook = ''
+        export ZDOTDIR=$(mktemp -d)
+        cat > "$ZDOTDIR/.zshrc" << 'EOF'
+          source ~/.zshrc # Source the original ~/.zshrc, required.
+          function parse_git_branch {
+            git branch --no-color 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/\ ->\ \1/'
+          }
+          function display_jobs_count_if_needed {
+            local job_count=$(jobs -s | wc -l | tr -d " ")
+            if [ $job_count -gt 0 ]; then
+              echo "%B%F{yellow}%j| ";
+            fi
+          }
+          # NOTE: Custom prompt with a snowflake: signals we are in `$ nix develop` shell
+          PROMPT="%F{blue}$(date +%H:%M:%S) $(display_jobs_count_if_needed)%B%F{green}%n %F{blue}%~%F{cyan} ❄%F{yellow}$(parse_git_branch) %f%{$reset_color%}"
+        EOF
+        if [ -z "$DIRENV_IN_ENVRC" ]; then # This makes `$ nix develop` universally working with direnv without infinite loop
+          exec ${pkgs.zsh}/bin/zsh -i
+        fi
+      '';
     };
   };
 }

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
 `);