qunitx 0.12.2 → 0.12.4

package/README.md

@@ -1,11 +1,16 @@
+<div align="center">
+
+# QUnitX
+
 [![CI](https://github.com/izelnakri/qunitx/actions/workflows/ci.yml/badge.svg)](https://github.com/izelnakri/qunitx/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/izelnakri/qunitx/branch/main/graph/badge.svg)](https://codecov.io/gh/izelnakri/qunitx)
 [![npm](https://img.shields.io/npm/v/qunitx)](https://www.npmjs.com/package/qunitx)
 [![npm downloads](https://img.shields.io/npm/dm/qunitx)](https://www.npmjs.com/package/qunitx)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![Ask me anything](https://img.shields.io/badge/ask%20me-anything-1abc9c.svg)](https://github.com/izelnakri/qunitx/issues)
 [![Sponsor](https://img.shields.io/badge/sponsor-%E2%99%A5-pink)](https://github.com/sponsors/izelnakri)
 
-# QUnitX
+</div>
 
 **The oldest, most battle-tested JavaScript test API — now universal.**
 
@@ -36,6 +41,10 @@ ecosystem:
 QUnitX wraps this API to work with **Node.js's built-in `node:test` runner** and
 **Deno's native test runner** — no Jest, Vitest, or other framework needed.
 
+QUnit includes the fastest assertion and test runtime in JS world. I've previously contributed to some [speed optimizations](https://qunitjs.com/blog/2022/02/15/qunit-2-18-0/) to QUnit, we benchmark every possible thing to make it the fastest test
+runtime, faster than node.js and deno default assertions in most cases. Therefore I consider myself very objective
+when I say QUnit(X) is the best JS/TS testing tool out there.
+
 ---
 
 ## Demo
@@ -51,14 +60,12 @@ Live browser UI example (click to see filterable QUnit test suite):
 
 [objectmodel.js.org/test/?moduleId=6e15ed5f](https://objectmodel.js.org/test/?moduleId=6e15ed5f&moduleId=950ec9c5)
 
-![QUnitX CLI help](https://raw.githubusercontent.com/izelnakri/qunitx/main/docs/qunitx-help-stdout.png)
-
 ---
 
 ## Installation
 
 ```sh
-npm install qunitx
+npm install qunitx --save-dev
 ```
 
 Requires **Node.js >= 22** (LTS) or **Deno >= 2**.
@@ -204,6 +211,8 @@ familiar browser UI with zero extra layers.
 
 ## Code coverage
 
+Probably c8 isn't even needed since qunitx runs as a dependency(rather than runtime) on node.js and deno.
+
 ```sh
 # Node (any c8-compatible reporter)
 npx c8 node --test test/

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "qunitx",
   "type": "module",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "description": "A universal test framework for testing any js file on node.js, browser or deno with QUnit API",
   "author": "Izel Nakri",
   "license": "MIT",
@@ -63,8 +63,10 @@
     "url": "git+https://github.com/izelnakri/qunitx.git"
   },
   "scripts": {
-    "lint": "prettier --check \"test/**/*.js\" \"*.js\" \"package.json\"",
-    "lint:fix": "prettier --write \"test/**/*.js\" \"*.js\" \"package.json\"",
+    "format": "prettier --check \"test/**/*.js\" \"*.js\" \"package.json\"",
+    "format:fix": "prettier --write \"test/**/*.js\" \"*.js\" \"package.json\"",
+    "lint": "deno lint shims/",
+    "lint:docs": "deno doc --lint shims/deno/module.js shims/deno/test.js",
     "build": "node build.js",
     "run:all": "npm run run:node && npm run run:deno",
     "run:node": "node --test test/helpers/passing-tests.js && node --test test/helpers/failing-tests.js",
@@ -77,7 +79,11 @@
     "test:dev": "npm run test | tee test-output.log",
     "test:browser": "qunitx test/index.js --debug",
     "test:deno": "deno test --allow-read --allow-env --allow-run test/index.js",
-    "test:node": "node --test test/index.js"
+    "test:doctests": "deno test --doc --allow-env --allow-read shims/deno/module.js shims/deno/test.js",
+    "test:node": "node --test test/index.js",
+    "coverage": "deno test --coverage=tmp/coverage --allow-read --allow-env --allow-run test/index.js && deno coverage --lcov --output=tmp/coverage/lcov.info --include='shims/' tmp/coverage && node scripts/check-coverage.js",
+    "coverage:report": "npm run coverage && deno coverage --html --include='shims/' tmp/coverage",
+    "docs": "deno doc --html --name=\"QUnitX\" --output=docs/src shims/deno/index.js"
   },
   "devDependencies": {
     "prettier": "^3.8.1",

package/scripts/check-coverage.js

@@ -0,0 +1,15 @@
+import { readFile } from 'node:fs/promises';
+
+const THRESHOLD = 85;
+const lcov = await readFile('tmp/coverage/lcov.info', 'utf8');
+
+const lh = [...lcov.matchAll(/^LH:(\d+)/gm)].reduce((s, m) => s + parseInt(m[1]), 0);
+const lf = [...lcov.matchAll(/^LF:(\d+)/gm)].reduce((s, m) => s + parseInt(m[1]), 0);
+const pct = lf > 0 ? (lh / lf) * 100 : 0;
+
+console.log(`Coverage: ${pct.toFixed(1)}% (${lh}/${lf} lines)`);
+
+if (pct < THRESHOLD) {
+  console.error(`Error: coverage ${pct.toFixed(1)}% is below the ${THRESHOLD}% threshold.`);
+  process.exit(1);
+}

package/shims/deno/module.js

@@ -5,14 +5,41 @@ import ModuleContext from '../shared/module-context.js';
 // NOTE: QUnit expect() logic is buggy in nested modules
 // NOTE: after gets the last direct children test of the module, not last defined context of a module(last defined context is a module)
 
+/**
+ * Defines a test module (suite) for Deno's BDD test runner.
+ *
+ * Wraps `describe()` from `@std/testing/bdd` and sets up the QUnit lifecycle
+ * (before/beforeEach/afterEach/after hooks, assertion counting, steps tracking).
+ *
+ * @param {string} moduleName - Name of the test suite
+ * @param {object} [runtimeOptions] - Optional Deno BDD options forwarded to `describe()`
+ *   (e.g. `{ concurrency: false }`, `{ permissions: { read: true } }`)
+ * @param {function} moduleContent - Callback that defines tests and hooks via `hooks.before`,
+ *   `hooks.beforeEach`, `hooks.afterEach`, `hooks.after`
+ * @returns {void}
+ * @example
+ * ```js ignore
+ * import { module, test } from "qunitx";
+ *
+ * module("Math", (hooks) => {
+ *   hooks.before((assert) => {
+ *     assert.step("before hook ran");
+ *   });
+ *
+ *   test("addition", (assert) => {
+ *     assert.equal(2 + 2, 4);
+ *   });
+ * });
+ * ```
+ */
 export default function module(moduleName, runtimeOptions, moduleContent) {
-  let targetRuntimeOptions = moduleContent ? runtimeOptions : {};
-  let targetModuleContent = moduleContent ? moduleContent : runtimeOptions;
-  let moduleContext = new ModuleContext(moduleName);
+  const targetRuntimeOptions = moduleContent ? runtimeOptions : {};
+  const targetModuleContent = moduleContent ? moduleContent : runtimeOptions;
+  const moduleContext = new ModuleContext(moduleName);
 
-  return describe(moduleName, { concurrency: true, ...targetRuntimeOptions }, function () {
-    let beforeHooks = [];
-    let afterHooks = [];
+  describe(moduleName, { concurrency: true, ...targetRuntimeOptions }, function () {
+    const beforeHooks = [];
+    const afterHooks = [];
 
     beforeAll(async function () {
       Object.assign(moduleContext.context, moduleContext.moduleChain.reduce((result, module) => {
@@ -24,7 +51,7 @@ export default function module(moduleName, runtimeOptions, moduleContent) {
         });
       }, { steps: [], expectedAssertionCount: undefined }));
 
-      for (let hook of beforeHooks) {
+      for (const hook of beforeHooks) {
         await hook.call(moduleContext.context, moduleContext.assert);
       }
 
@@ -41,7 +68,7 @@ export default function module(moduleName, runtimeOptions, moduleContent) {
         await assert.waitForAsyncOps();
       }
 
-      let targetContext = moduleContext.tests[moduleContext.tests.length - 1];
+      const targetContext = moduleContext.tests[moduleContext.tests.length - 1];
       for (let j = afterHooks.length - 1; j >= 0; j--) {
         await afterHooks[j].call(targetContext, targetContext.assert);
       }

package/shims/deno/test.js

@@ -2,29 +2,58 @@ import { it } from "jsr:@std/testing/bdd";
 import TestContext from '../shared/test-context.js';
 import ModuleContext from '../shared/module-context.js';
 
+/**
+ * Defines an individual test within a module for Deno's BDD test runner.
+ *
+ * Wraps `it()` from `@std/testing/bdd` and handles the full QUnit lifecycle:
+ * beforeEach/afterEach hooks, async assertion waiting, and step verification.
+ *
+ * Must be called inside a `module()` callback.
+ *
+ * @param {string} testName - Name of the test
+ * @param {object} [runtimeOptions] - Optional Deno BDD options forwarded to `it()`
+ *   (e.g. `{ concurrency: false }`, `{ sanitizeExit: false }`)
+ * @param {function} testContent - Test callback receiving `(assert, { testName, options })`
+ * @returns {void}
+ * @example
+ * ```js ignore
+ * import { module, test } from "qunitx";
+ *
+ * module("Math", () => {
+ *   test("addition", (assert) => {
+ *     assert.equal(1 + 1, 2);
+ *   });
+ *
+ *   test("async resolves correctly", async (assert) => {
+ *     const result = await Promise.resolve(42);
+ *     assert.strictEqual(result, 42);
+ *   });
+ * });
+ * ```
+ */
 export default function test(testName, runtimeOptions, testContent) {
-  let moduleContext = ModuleContext.lastModule;
+  const moduleContext = ModuleContext.lastModule;
   if (!moduleContext) {
     throw new Error(`Test '${testName}' called outside of module context.`);
   }
 
-  let targetRuntimeOptions = testContent ? runtimeOptions : {};
-  let targetTestContent = testContent ? testContent : runtimeOptions;
-  let context = new TestContext(testName, moduleContext);
+  const targetRuntimeOptions = testContent ? runtimeOptions : {};
+  const targetTestContent = testContent ? testContent : runtimeOptions;
+  const context = new TestContext(testName, moduleContext);
 
-  return it(testName, { concurrency: true, ...targetRuntimeOptions }, async function () {
-    for (let module of context.module.moduleChain) {
-      for (let hook of module.beforeEachHooks) {
+  it(testName, { concurrency: true, ...targetRuntimeOptions }, async function () {
+    for (const module of context.module.moduleChain) {
+      for (const hook of module.beforeEachHooks) {
         await hook.call(context, context.assert);
       }
     }
 
-    let result = await targetTestContent.call(context, context.assert, { testName, options: runtimeOptions });
+    const result = await targetTestContent.call(context, context.assert, { testName, options: runtimeOptions });
 
     await context.assert.waitForAsyncOps();
 
     for (let i = context.module.moduleChain.length - 1; i >= 0; i--) {
-      let module = context.module.moduleChain[i];
+      const module = context.module.moduleChain[i];
       for (let j = module.afterEachHooks.length - 1; j >= 0; j--) {
         await module.afterEachHooks[j].call(context, context.assert);
       }

package/shims/node/module.js

@@ -6,13 +6,13 @@ import ModuleContext from '../shared/module-context.js';
 // NOTE: after gets the last direct children test of the module, not last defined context of a module(last defined context is a module)
 
 export default function module(moduleName, runtimeOptions, moduleContent) {
-  let targetRuntimeOptions = moduleContent ? runtimeOptions : {};
-  let targetModuleContent = moduleContent ? moduleContent : runtimeOptions;
-  let moduleContext = new ModuleContext(moduleName);
+  const targetRuntimeOptions = moduleContent ? runtimeOptions : {};
+  const targetModuleContent = moduleContent ? moduleContent : runtimeOptions;
+  const moduleContext = new ModuleContext(moduleName);
 
-  return describe(moduleName, { concurrency: true, ...targetRuntimeOptions }, async function () {
-    let beforeHooks = [];
-    let afterHooks = [];
+  return describe(moduleName, { concurrency: true, ...targetRuntimeOptions }, function () {
+    const beforeHooks = [];
+    const afterHooks = [];
 
     beforeAll(async function () {
       Object.assign(moduleContext.context, moduleContext.moduleChain.reduce((result, module) => {
@@ -24,7 +24,7 @@ export default function module(moduleName, runtimeOptions, moduleContent) {
         });
       }, { steps: [], expectedAssertionCount: undefined }));
 
-      for (let hook of beforeHooks) {
+      for (const hook of beforeHooks) {
         await hook.call(moduleContext.context, moduleContext.assert);
       }
 
@@ -41,7 +41,7 @@ export default function module(moduleName, runtimeOptions, moduleContent) {
         await assert.waitForAsyncOps();
       }
 
-      let targetContext = moduleContext.tests[moduleContext.tests.length - 1];
+      const targetContext = moduleContext.tests[moduleContext.tests.length - 1];
       for (let j = afterHooks.length - 1; j >= 0; j--) {
         await afterHooks[j].call(targetContext, targetContext.assert);
       }

package/shims/node/test.js

@@ -3,28 +3,28 @@ import TestContext from '../shared/test-context.js';
 import ModuleContext from '../shared/module-context.js';
 
 export default function test(testName, runtimeOptions, testContent) {
-  let moduleContext = ModuleContext.lastModule;
+  const moduleContext = ModuleContext.lastModule;
   if (!moduleContext) {
     throw new Error(`Test '${testName}' called outside of module context.`);
   }
 
-  let targetRuntimeOptions = testContent ? runtimeOptions : {};
-  let targetTestContent = testContent ? testContent : runtimeOptions;
-  let context = new TestContext(testName, moduleContext);
+  const targetRuntimeOptions = testContent ? runtimeOptions : {};
+  const targetTestContent = testContent ? testContent : runtimeOptions;
+  const context = new TestContext(testName, moduleContext);
 
   return it(testName, { concurrency: true, ...targetRuntimeOptions }, async function () {
-    for (let module of context.module.moduleChain) {
-      for (let hook of module.beforeEachHooks) {
+    for (const module of context.module.moduleChain) {
+      for (const hook of module.beforeEachHooks) {
         await hook.call(context, context.assert);
       }
     }
 
-    let result = await targetTestContent.call(context, context.assert, { testName, options: runtimeOptions });
+    const result = await targetTestContent.call(context, context.assert, { testName, options: runtimeOptions });
 
     await context.assert.waitForAsyncOps();
 
     for (let i = context.module.moduleChain.length - 1; i >= 0; i--) {
-      let module = context.module.moduleChain[i];
+      const module = context.module.moduleChain[i];
       for (let j = module.afterEachHooks.length - 1; j >= 0; j--) {
         await module.afterEachHooks[j].call(context, context.assert);
       }

package/shims/shared/assert.js

@@ -55,13 +55,13 @@ export default class Assert {
   }
   async() {
     let resolveFn;
-    let done = new Promise(resolve => { resolveFn = resolve; });
+    const done = new Promise(resolve => { resolveFn = resolve; });
 
     this.test.asyncOps.push(done);
 
     return () => { resolveFn(); };
   }
-  async waitForAsyncOps() {
+  waitForAsyncOps() {
     return Promise.all(this.test.asyncOps);
   }
   pushResult(resultInfo = {}) {
@@ -147,8 +147,8 @@ export default class Assert {
   }
   propEqual(actual, expected, message) {
     this._incrementAssertionCount();
-    let targetActual = objectValues(actual);
-    let targetExpected = objectValues(expected);
+    const targetActual = objectValues(actual);
+    const targetExpected = objectValues(expected);
     if (!Assert.QUnit.equiv(targetActual, targetExpected)) {
       throw new Assert.AssertionError({
         actual: targetActual,
@@ -160,8 +160,8 @@ export default class Assert {
   }
   notPropEqual(actual, expected, message) {
     this._incrementAssertionCount();
-    let targetActual = objectValues(actual);
-    let targetExpected = objectValues(expected);
+    const targetActual = objectValues(actual);
+    const targetExpected = objectValues(expected);
     if (Assert.QUnit.equiv(targetActual, targetExpected)) {
       throw new Assert.AssertionError({
         actual: targetActual,
@@ -173,8 +173,8 @@ export default class Assert {
   }
   propContains(actual, expected, message) {
     this._incrementAssertionCount();
-    let targetActual = objectValuesSubset(actual, expected);
-    let targetExpected = objectValues(expected, false);
+    const targetActual = objectValuesSubset(actual, expected);
+    const targetExpected = objectValues(expected, false);
     if (!Assert.QUnit.equiv(targetActual, targetExpected)) {
       throw new Assert.AssertionError({
         actual: targetActual,
@@ -186,8 +186,8 @@ export default class Assert {
   }
   notPropContains(actual, expected, message) {
     this._incrementAssertionCount();
-    let targetActual = objectValuesSubset(actual, expected);
-    let targetExpected = objectValues(expected);
+    const targetActual = objectValuesSubset(actual, expected);
+    const targetExpected = objectValues(expected);
     if (Assert.QUnit.equiv(targetActual, targetExpected)) {
       throw new Assert.AssertionError({
         actual: targetActual,
@@ -247,7 +247,7 @@ export default class Assert {
   }
   throws(blockFn, expectedInput, assertionMessage) {
     this?._incrementAssertionCount();
-    let [expected, message] = validateExpectedExceptionArgs(expectedInput, assertionMessage, 'rejects');
+    const [expected, message] = validateExpectedExceptionArgs(expectedInput, assertionMessage, 'rejects');
     if (typeof blockFn !== 'function') {
       throw new Assert.AssertionError({
         actual: blockFn,
@@ -260,7 +260,7 @@ export default class Assert {
     try {
       blockFn();
     } catch (error) {
-      let validation = validateException(error, expected, message);
+      const validation = validateException(error, expected, message);
       if (validation.result === false) {
         throw new Assert.AssertionError({
           actual: validation.result,
@@ -282,8 +282,8 @@ export default class Assert {
   }
   async rejects(promise, expectedInput, assertionMessage) {
     this._incrementAssertionCount();
-    let [expected, message] = validateExpectedExceptionArgs(expectedInput, assertionMessage, 'rejects');
-    let then = promise && promise.then;
+    const [expected, message] = validateExpectedExceptionArgs(expectedInput, assertionMessage, 'rejects');
+    const then = promise && promise.then;
     if (typeof then !== 'function') {
       throw new Assert.AssertionError({
         actual: promise,
@@ -302,7 +302,7 @@ export default class Assert {
         stackStartFn: this.rejects,
       });
     } catch (error) {
-      let validation = validateException(error, expected, message);
+      const validation = validateException(error, expected, message);
       if (validation.result === false) {
         throw new Assert.AssertionError({
           actual: validation.result,

package/shims/shared/index.js

@@ -1,14 +1,8 @@
 const hasOwn = Object.prototype.hasOwnProperty
 
-function _typeof(obj) {
-  "@babel/helpers - typeof";
-
-  return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (obj) {
-    return typeof obj;
-  } : function (obj) {
-    return obj && "function" == typeof Symbol && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj;
-  }, _typeof(obj);
-}
+const _typeof = typeof Symbol === 'function' && typeof Symbol.iterator === 'symbol'
+  ? (obj) => typeof obj
+  : (obj) => obj && typeof Symbol === 'function' && obj.constructor === Symbol && obj !== Symbol.prototype ? 'symbol' : typeof obj;
 
 export function objectType(obj) {
   if (typeof obj === 'undefined') {
@@ -19,8 +13,8 @@ export function objectType(obj) {
   if (obj === null) {
     return 'null';
   }
-  var match = toString.call(obj).match(/^\[object\s(.*)\]$/);
-  var type = match && match[1];
+  const match = toString.call(obj).match(/^\[object\s(.*)\]$/);
+  const type = match && match[1];
   switch (type) {
     case 'Number':
       if (isNaN(obj)) {
@@ -47,12 +41,12 @@ function is(type, obj) {
 }
 
 export function objectValues(obj) {
-  let allowArray = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : true;
-  let vals = allowArray && is('array', obj) ? [] : {};
+  const allowArray = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : true;
+  const vals = allowArray && is('array', obj) ? [] : {};
 
-  for (var key in obj) {
+  for (const key in obj) {
     if (hasOwn.call(obj, key)) {
-      let val = obj[key];
+      const val = obj[key];
       vals[key] = val === Object(val) ? objectValues(val, allowArray) : val;
     }
   }
@@ -80,8 +74,8 @@ export function objectValuesSubset(obj, model) {
 
   // Unlike objectValues(), subset arrays to a plain objects as well.
   // This enables subsetting [20, 30] with {1: 30}.
-  var subset = {};
-  for (var key in model) {
+  const subset = {};
+  for (const key in model) {
     if (hasOwn.call(model, key) && hasOwn.call(obj, key)) {
       subset[key] = objectValuesSubset(obj[key], model[key]);
     }
@@ -90,7 +84,7 @@ export function objectValuesSubset(obj, model) {
 }
 
 export function validateExpectedExceptionArgs(expected, message, assertionMethod) {
-  var expectedType = objectType(expected);
+  const expectedType = objectType(expected);
 
   // 'expected' is optional unless doing string comparison
   if (expectedType === 'string') {
@@ -102,7 +96,7 @@ export function validateExpectedExceptionArgs(expected, message, assertionMethod
       throw new Error('assert.' + assertionMethod + ' does not accept a string value for the expected argument.\n' + 'Use a non-string object value (e.g. RegExp or validator function) ' + 'instead if necessary.');
     }
   }
-  var valid = !expected ||
+  const valid = !expected ||
   // TODO: be more explicit here
   expectedType === 'regexp' || expectedType === 'function' || expectedType === 'object';
   if (!valid) {
@@ -112,8 +106,8 @@ export function validateExpectedExceptionArgs(expected, message, assertionMethod
 }
 
 export function validateException(actual, expected, message) {
-  var result = false;
-  var expectedType = objectType(expected);
+  let result = false;
+  const expectedType = objectType(expected);
 
   // These branches should be exhaustive, based on validation done in validateExpectedException
 
@@ -157,7 +151,7 @@ export function validateException(actual, expected, message) {
 
 function errorString(error) {
   // Use String() instead of toString() to handle non-object values like undefined or null.
-  var resultErrorString = String(error);
+  const resultErrorString = String(error);
 
   // If the error wasn't a subclass of Error but something like
   // an object literal with name and message properties...

package/shims/shared/module-context.js

@@ -16,7 +16,7 @@ export default class ModuleContext {
   tests = [];
 
   constructor(name) {
-    let parentModule = ModuleContext.currentModuleChain[ModuleContext.currentModuleChain.length - 1];
+    const parentModule = ModuleContext.currentModuleChain[ModuleContext.currentModuleChain.length - 1];
 
     ModuleContext.currentModuleChain.push(this);
 

package/Makefile

@@ -1,28 +0,0 @@
-.PHONY: check test lint build release
-
-check: lint test
-
-lint:
-	npm run lint
-
-test:
-	npm test
-
-build:
-	npm run build
-
-# Lint, bump version, update changelog, commit, tag, push, publish to npm.
-# CI then creates the GitHub release.
-# Usage: make release          (defaults to patch)
-#        make release LEVEL=minor|major
-LEVEL ?= patch
-release:
-	@npm whoami 2>/dev/null || npm login
-	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