qunitx 0.12.4 → 1.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "qunitx",
   "type": "module",
-  "version": "0.12.4",
+  "version": "1.0.0",
   "description": "A universal test framework for testing any js file on node.js, browser or deno with QUnit API",
   "author": "Izel Nakri",
   "license": "MIT",

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/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,6 +133,25 @@ 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;
     const done = new Promise(resolve => { resolveFn = resolve; });
@@ -61,9 +160,30 @@ export default class Assert {
 
     return () => { resolveFn(); };
   }
+
   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,6 +344,23 @@ 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();
     const targetActual = objectValues(actual);
@@ -158,6 +374,20 @@ 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();
     const targetActual = objectValues(actual);
@@ -171,6 +401,20 @@ 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();
     const targetActual = objectValuesSubset(actual, expected);
@@ -184,6 +428,20 @@ 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();
     const targetActual = objectValuesSubset(actual, expected);
@@ -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,6 +556,22 @@ 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();
     const [expected, message] = validateExpectedExceptionArgs(expectedInput, assertionMessage, 'rejects');
@@ -280,6 +607,22 @@ 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();
     const [expected, message] = validateExpectedExceptionArgs(expectedInput, assertionMessage, 'rejects');