qunitx-cli

Browser-based test runner for QUnitX — bundles your JS/TS tests with esbuild, runs them in a headless browser via Playwright, and streams TAP 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
• 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
• --browser flag to run tests in Chromium, Firefox, or WebKit
• Docker image for zero-install CI usage

Installation

Requires Node.js >= 24.

npm install --save-dev qunitx-cli

Or run without installing:

npx qunitx test/**/*.js

With Docker — no install needed:

docker run --rm -v "$(pwd):/code" -w /code ghcr.io/izelnakri/qunitx-cli:latest npx qunitx test/**/*.js

With Nix:

nix profile install github:izelnakri/qunitx-cli

Usage

# 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 browser 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

# Run in Firefox or WebKit instead of Chromium
qunitx test/**/*.js --browser=firefox
qunitx test/**/*.js --browser=webkit

Prerequisite for Firefox / WebKit: install the Playwright browser binaries once:

npx playwright install firefox
npx playwright install webkit

Writing Tests

qunitx-cli runs QUnitX tests — a superset of QUnit with async hooks, concurrency control, and test metadata.

Migrating from QUnit? Change a single import:

// before
import { module, test } from 'qunit';
// after
import { module, test } from 'qunitx';

Example test file — ES modules, npm imports, and nested modules all work out of the box:

// some-test.js (TypeScript is also supported)
import { module, test } from 'qunitx';
import $ from 'jquery';

module('Basic sanity check', (hooks) => {
  test('it works', (assert) => {
    assert.equal(true, true);
  });

  module('More advanced cases', (hooks) => {
    test('deepEqual works', (assert) => {
      assert.deepEqual({ username: 'izelnakri' }, { username: 'izelnakri' });
    });

    test('can import ES & npm modules', (assert) => {
      assert.ok(Object.keys($));
    });
  });
});

Run it:

# Headless Chromium (default, recommended for CI)
qunitx some-test.js

# With browser console output
qunitx some-test.js --debug

# TypeScript — no config needed
qunitx some-test.ts

Configuration

All CLI flags can also be set in package.json under the qunitx key, so you don't have to repeat them on every invocation:

{
  "qunitx": {
    "inputs": ["test/**/*-test.js", "test/**/*-test.ts"],
    "extensions": ["js", "ts"],
    "output": "tmp",
    "timeout": 20000,
    "failFast": false,
    "port": 1234,
    "browser": "chromium"
  }
}

Key	Default	Description
inputs	[]	Glob patterns, file paths, or directories to use as test entry points. Merged with any paths given on the CLI.
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.

CLI flags always override package.json values when both are present.

CLI Reference

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]
  --extensions=<...>  Comma-separated file extensions to track  [default: js,ts]
  --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)
  --browser=<name>    Browser engine: chromium (default), firefox, or webkit

Development

npm install
make check                      # lint + test (run before every commit)
make test                       # run full test suite (Chromium)
make test-firefox               # run browser tests with Firefox
make test-webkit                # run browser tests with WebKit
make test-all-browsers          # run full suite on all three browsers
make demo                       # regenerate docs/demo.gif
make release LEVEL=patch        # bump version, update changelog, tag, push

Use --trace-perf to print internal timing to stderr — useful when investigating startup or e2e regressions:

qunitx test/my-test.js --trace-perf

License

MIT