qunitx 0.12.2 → 0.12.5

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.5",
   "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/index.js

@@ -1,3 +1,29 @@
+/**
+ * QUnitX — universal test library that runs the same test file in Node.js, Deno, and browser.
+ *
+ * Wraps QUnit's assertion API over each runtime's native BDD test runner so you only
+ * write your tests once.
+ *
+ * @example
+ * ```js
+ * import { module, test } from "qunitx";
+ *
+ * module("Math", (hooks) => {
+ *   hooks.before((assert) => assert.step("setup"));
+ *
+ *   test("addition", (assert) => {
+ *     assert.equal(1 + 1, 2);
+ *   });
+ *
+ *   test("async", async (assert) => {
+ *     const n = await Promise.resolve(42);
+ *     assert.strictEqual(n, 42);
+ *   });
+ * });
+ * ```
+ *
+ * @module
+ */
 import { AssertionError as DenoAssertionError } from "jsr:@std/assert";
 import '../../vendor/qunit.js';
 import Assert from '../shared/assert.js';
@@ -6,6 +32,24 @@ import TestContext from '../shared/test-context.js';
 import Module from './module.js';
 import Test from './test.js';
 
+/**
+ * Thrown when an assertion fails. Extends Deno's built-in `AssertionError`
+ * so it integrates cleanly with Deno's test runner output.
+ *
+ * You rarely construct this directly — assertion methods on {@linkcode Assert}
+ * throw it automatically on failure.
+ *
+ * @example
+ * ```js
+ * import { AssertionError } from "qunitx";
+ *
+ * try {
+ *   throw new AssertionError({ message: "something went wrong" });
+ * } catch (e) {
+ *   console.log(e instanceof AssertionError); // true
+ * }
+ * ```
+ */
 export class AssertionError extends DenoAssertionError {
   constructor(object) {
     super(object.message);
@@ -21,7 +65,103 @@ Object.freeze(Assert);
 Object.freeze(ModuleContext);
 Object.freeze(TestContext);
 
+export { Assert };
+
+/**
+ * Defines a test module (suite). Wraps Deno's `describe()` and sets up the
+ * QUnit lifecycle — `before`, `beforeEach`, `afterEach`, and `after` hooks,
+ * assertion counting, and step tracking.
+ *
+ * Each {@linkcode test} inside the callback receives an {@linkcode Assert} instance.
+ * Modules can be nested by calling `module()` inside another module's callback.
+ *
+ * @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.
+ *   Receives `(hooks, { moduleName, options })` where `hooks` exposes
+ *   `before`, `beforeEach`, `afterEach`, and `after`.
+ * @example
+ * ```js
+ * import { module, test } from "qunitx";
+ *
+ * module("Math", (hooks) => {
+ *   hooks.before((assert) => {
+ *     assert.step("before hook ran");
+ *   });
+ *
+ *   test("addition", (assert) => {
+ *     assert.equal(2 + 2, 4);
+ *   });
+ * });
+ * ```
+ * @example
+ * ```js
+ * // Nested modules
+ * module("Outer", () => {
+ *   module("Inner", () => {
+ *     test("nested test", (assert) => {
+ *       assert.ok(true);
+ *     });
+ *   });
+ * });
+ * ```
+ */
 export const module = Module;
+
+/**
+ * Defines an individual test. Wraps Deno's `it()` and handles the full QUnit
+ * lifecycle: `beforeEach`/`afterEach` hooks, async assertion waiting, and step
+ * verification. Must be called inside a {@linkcode module} callback.
+ *
+ * The test callback receives `(assert, { testName, options })` where `assert`
+ * is an {@linkcode Assert} instance.
+ *
+ * @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 })`.
+ * @example
+ * ```js
+ * 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 const test = Test;
 
+/**
+ * The default export provides the full QUnitX API as a single object.
+ *
+ * @example
+ * ```js
+ * import qunitx from "qunitx";
+ *
+ * qunitx.module("Math", () => {
+ *   qunitx.test("addition", (assert) => {
+ *     assert.equal(1 + 1, 2);
+ *   });
+ * });
+ * ```
+ *
+ * @property {Function} module - Defines a test suite. Wraps Deno's `describe()` with
+ *   QUnit lifecycle hooks (`before`, `beforeEach`, `afterEach`, `after`).
+ *   See the named {@linkcode module} export for full parameter documentation.
+ * @property {Function} test - Defines an individual test inside a `module()` callback.
+ *   Receives an {@linkcode Assert} instance as its first argument.
+ *   See the named {@linkcode test} export for full parameter documentation.
+ * @property {typeof AssertionError} AssertionError - The error class thrown when an
+ *   assertion fails. Extends Deno's built-in `AssertionError`.
+ * @property {object} config - Runtime configuration object (currently unused; reserved
+ *   for future QUnit config compatibility).
+ */
 export default { AssertionError: Assert.AssertionError, module, test, config: {} };

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

@@ -6,6 +6,25 @@ import util from 'node:util';
 // NOTE: Another approach for a global report Make this._assertions.set(this.currentTest, (this._assertions.get(this.currentTest) || 0) + 1); for pushResult
 // NOTE: This should *always* be a singleton(?), passed around as an argument for hooks. Seems difficult with concurrency. Singleton needs to be a concurrent data structure.
 
+/**
+ * The assertion object passed to every test callback and lifecycle hook.
+ *
+ * Every {@linkcode test} callback receives an instance of `Assert` as its first argument.
+ * All assertion methods throw an {@linkcode AssertionError} on failure, which the test
+ * runner catches and reports.
+ *
+ * @example
+ * ```js
+ * import { module, test } from "qunitx";
+ *
+ * module("Math", () => {
+ *   test("addition", (assert) => {
+ *     assert.equal(1 + 1, 2);
+ *     assert.strictEqual(typeof 42, "number");
+ *   });
+ * });
+ * ```
+ */
 export default class Assert {
   static QUnit;
   static AssertionError;
@@ -17,6 +36,20 @@ export default class Assert {
   _incrementAssertionCount() {
     this.test.totalExecutedAssertions++;
   }
+
+  /**
+   * Sets the number of milliseconds after which the current test will fail if not yet complete.
+   *
+   * @param {number} number - Timeout in milliseconds (positive integer).
+   * @example
+   * ```js
+   * test("slow async operation", async (assert) => {
+   *   assert.timeout(500);
+   *   await somethingAsync();
+   *   assert.ok(true);
+   * });
+   * ```
+   */
   timeout(number) {
     if (!Number.isInteger(number) || number < 0) {
       throw new Error('assert.timeout() expects a positive integer.');
@@ -24,6 +57,22 @@ export default class Assert {
 
     this.test.timeout = number;
   }
+
+  /**
+   * Records a named step. Use with {@linkcode Assert.prototype.verifySteps} to assert that
+   * a sequence of steps occurred in the right order.
+   *
+   * @param {string} message - The step label to record.
+   * @example
+   * ```js
+   * test("event order", (assert) => {
+   *   assert.expect(3);
+   *   assert.step("step one");
+   *   assert.step("step two");
+   *   assert.verifySteps(["step one", "step two"]);
+   * });
+   * ```
+   */
   step(message) {
     let assertionMessage = message;
     let result = !!message;
@@ -42,10 +91,41 @@ export default class Assert {
       message: assertionMessage
     });
   }
+
+  /**
+   * Asserts that the steps recorded via {@linkcode Assert.prototype.step} match the given array,
+   * then clears the recorded steps.
+   *
+   * @param {string[]} steps - Expected array of step labels in order.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * test("lifecycle order", (assert) => {
+   *   assert.step("init");
+   *   assert.step("run");
+   *   assert.verifySteps(["init", "run"]);
+   * });
+   * ```
+   */
   verifySteps(steps, message = 'Verify steps failed!') {
     this.deepEqual(this.test.steps, steps, message);
     this.test.steps.length = 0;
   }
+
+  /**
+   * Sets the number of assertions expected to run in the current test.
+   * The test fails if a different number of assertions actually ran.
+   *
+   * @param {number} number - Expected assertion count (non-negative integer).
+   * @example
+   * ```js
+   * test("exactly two assertions", (assert) => {
+   *   assert.expect(2);
+   *   assert.ok(true);
+   *   assert.ok(true);
+   * });
+   * ```
+   */
   expect(number) {
     if (!Number.isInteger(number) || number < 0) {
       throw new Error('assert.expect() expects a positive integer.');
@@ -53,17 +133,57 @@ export default class Assert {
 
     this.test.expectedAssertionCount = number;
   }
+
+  /**
+   * Returns a `done` callback for callback-style async tests. The test will not
+   * finish until every `done` callback returned by `async()` has been called.
+   *
+   * For `async/await` tests prefer `async (assert) => { ... }` directly.
+   *
+   * @returns {function} A callback to invoke when the async work finishes.
+   * @example
+   * ```js
+   * test("async callback style", (assert) => {
+   *   const done = assert.async();
+   *   setTimeout(() => {
+   *     assert.ok(true, "async callback ran");
+   *     done();
+   *   }, 10);
+   * });
+   * ```
+   */
   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);
   }
+
+  /**
+   * Pushes a custom assertion result. Fails the test if `resultInfo.result` is falsy.
+   * Throws an {@linkcode AssertionError} on failure.
+   *
+   * Useful for building custom assertion helpers.
+   *
+   * @param {{ result: boolean, actual?: unknown, expected?: unknown, message?: string }} resultInfo
+   * @example
+   * ```js
+   * test("custom assertion", (assert) => {
+   *   assert.pushResult({
+   *     result: 1 + 1 === 2,
+   *     actual: 2,
+   *     expected: 2,
+   *     message: "custom math check",
+   *   });
+   * });
+   * ```
+   */
   pushResult(resultInfo = {}) {
     this._incrementAssertionCount();
     if (!resultInfo.result) {
@@ -77,6 +197,19 @@ export default class Assert {
 
     return this;
   }
+
+  /**
+   * Asserts that `state` is truthy.
+   *
+   * @param {unknown} state - The value to test.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.ok(true);
+   * assert.ok(1, "non-zero is truthy");
+   * assert.ok("hello");
+   * ```
+   */
   ok(state, message) {
     this._incrementAssertionCount();
     if (!state) {
@@ -88,6 +221,19 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `state` is falsy.
+   *
+   * @param {unknown} state - The value to test.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.notOk(false);
+   * assert.notOk(0, "zero is falsy");
+   * assert.notOk(null);
+   * ```
+   */
   notOk(state, message) {
     this._incrementAssertionCount();
     if (state) {
@@ -99,6 +245,18 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `state === true` (strict boolean true).
+   *
+   * @param {unknown} state - The value to test.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.true(1 === 1);
+   * assert.true(Array.isArray([]), "arrays are arrays");
+   * ```
+   */
   true(state, message) {
     this._incrementAssertionCount();
     if (state !== true) {
@@ -110,6 +268,18 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `state === false` (strict boolean false).
+   *
+   * @param {unknown} state - The value to test.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.false(1 === 2);
+   * assert.false(Number.isNaN(42), "42 is not NaN");
+   * ```
+   */
   false(state, message) {
     this._incrementAssertionCount();
     if (state !== false) {
@@ -121,6 +291,22 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `actual == expected` (loose equality, allows type coercion).
+   *
+   * Prefer {@linkcode Assert.prototype.strictEqual} for most comparisons. Use {@linkcode Assert.prototype.notEqual}
+   * for the inverse.
+   *
+   * @param {unknown} actual - The value produced by the code under test.
+   * @param {unknown} expected - The expected value.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.equal(1, 1);
+   * assert.equal("1", 1, "loose equality allows coercion");
+   * ```
+   */
   equal(actual, expected, message) {
     this._incrementAssertionCount();
     if (actual != expected) {
@@ -133,6 +319,19 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `actual != expected` (loose inequality). Inverse of {@linkcode Assert.prototype.equal}.
+   *
+   * @param {unknown} actual - The actual value.
+   * @param {unknown} expected - The value it should not loosely equal.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.notEqual(1, 2);
+   * assert.notEqual("hello", "world");
+   * ```
+   */
   notEqual(actual, expected, message) {
     this._incrementAssertionCount();
     if (actual == expected) {
@@ -145,10 +344,27 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `actual` and `expected` have the same own enumerable properties
+   * and values. Prototype methods are ignored; only own properties are compared.
+   *
+   * @param {object} actual - The actual object.
+   * @param {object} expected - The expected object.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.propEqual({ a: 1, b: 2 }, { a: 1, b: 2 });
+   *
+   * // Ignores prototype methods — only own properties matter:
+   * function Point(x, y) { this.x = x; this.y = y; }
+   * assert.propEqual(new Point(1, 2), { x: 1, y: 2 });
+   * ```
+   */
   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,
@@ -158,10 +374,24 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `actual` and `expected` do NOT have the same own enumerable
+   * properties and values. Inverse of {@linkcode Assert.prototype.propEqual}.
+   *
+   * @param {object} actual - The actual object.
+   * @param {object} expected - The value it should not propEqual.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.notPropEqual({ a: 1 }, { a: 2 });
+   * assert.notPropEqual({ a: 1, b: 2 }, { a: 1 }); // extra key makes them unequal
+   * ```
+   */
   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,
@@ -171,10 +401,24 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `actual` contains all own enumerable properties from `expected`
+   * with matching values. Extra properties on `actual` are allowed and ignored.
+   *
+   * @param {object} actual - The actual object (may have extra keys).
+   * @param {object} expected - The subset of key/value pairs that must be present.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.propContains({ a: 1, b: 2, c: 3 }, { a: 1, b: 2 });
+   * assert.propContains(user, { role: "admin" });
+   * ```
+   */
   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,
@@ -184,10 +428,24 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `actual` does NOT contain all own enumerable properties
+   * from `expected` with matching values. Inverse of {@linkcode Assert.prototype.propContains}.
+   *
+   * @param {object} actual - The actual object.
+   * @param {object} expected - The subset of properties that must NOT all match.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.notPropContains({ a: 1, b: 2 }, { a: 9 });
+   * assert.notPropContains(user, { role: "banned" });
+   * ```
+   */
   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,
@@ -197,6 +455,20 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts deep equality between `actual` and `expected` using recursive structural
+   * comparison. Handles nested objects, arrays, `Date`, `RegExp`, and more.
+   *
+   * @param {unknown} actual - The actual value.
+   * @param {unknown} expected - The expected value.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.deepEqual([1, { a: 2 }], [1, { a: 2 }]);
+   * assert.deepEqual(new Date("2024-01-01"), new Date("2024-01-01"));
+   * ```
+   */
   deepEqual(actual, expected, message) {
     this._incrementAssertionCount();
     if (!Assert.QUnit.equiv(actual, expected)) {
@@ -209,6 +481,19 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `actual` and `expected` are NOT deeply equal. Inverse of {@linkcode Assert.prototype.deepEqual}.
+   *
+   * @param {unknown} actual - The actual value.
+   * @param {unknown} expected - The value it should not deepEqual.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.notDeepEqual([1, 2], [1, 3]);
+   * assert.notDeepEqual({ a: 1 }, { a: 2 });
+   * ```
+   */
   notDeepEqual(actual, expected, message) {
     this._incrementAssertionCount();
     if (Assert.QUnit.equiv(actual, expected)) {
@@ -221,6 +506,19 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `actual === expected` (strict equality, no type coercion).
+   *
+   * @param {unknown} actual - The actual value.
+   * @param {unknown} expected - The expected value.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.strictEqual(1 + 1, 2);
+   * assert.strictEqual(typeof "hello", "string");
+   * ```
+   */
   strictEqual(actual, expected, message) {
     this._incrementAssertionCount();
     if (actual !== expected) {
@@ -233,6 +531,19 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `actual !== expected` (strict inequality). Inverse of {@linkcode Assert.prototype.strictEqual}.
+   *
+   * @param {unknown} actual - The actual value.
+   * @param {unknown} expected - The value it should not strictly equal.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.notStrictEqual(1, "1", "different types");
+   * assert.notStrictEqual({}, {}, "different object references");
+   * ```
+   */
   notStrictEqual(actual, expected, message) {
     this._incrementAssertionCount();
     if (actual === expected) {
@@ -245,9 +556,25 @@ export default class Assert {
       });
     }
   }
+
+  /**
+   * Asserts that `blockFn` throws an exception. Optionally validates the thrown
+   * error against a string (message substring), RegExp (message pattern),
+   * or constructor (`instanceof` check). For async functions use {@linkcode Assert.prototype.rejects}.
+   *
+   * @param {function} blockFn - A synchronous function expected to throw.
+   * @param {string|RegExp|function} [expected] - Optional matcher for the thrown error.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * assert.throws(() => { throw new Error("boom"); });
+   * assert.throws(() => JSON.parse("{bad}"), SyntaxError);
+   * assert.throws(() => { throw new Error("bad input"); }, /bad input/);
+   * ```
+   */
   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 +587,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,
@@ -280,10 +607,26 @@ export default class Assert {
       stackStartFn: this.throws,
     });
   }
+
+  /**
+   * Asserts that a promise rejects. Optionally validates the rejection reason
+   * against a string (message substring), RegExp (message pattern),
+   * or constructor (`instanceof` check). For synchronous throws use {@linkcode Assert.prototype.throws}.
+   *
+   * @param {Promise<unknown>} promise - A promise expected to reject.
+   * @param {string|RegExp|function} [expected] - Optional matcher for the rejection reason.
+   * @param {string} [message] - Optional failure message.
+   * @example
+   * ```js
+   * await assert.rejects(Promise.reject(new Error("oops")));
+   * await assert.rejects(fetch("/bad-url"), TypeError);
+   * await assert.rejects(Promise.reject(new Error("timeout")), /timeout/);
+   * ```
+   */
   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 +645,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