qunitx 1.0.3 → 1.1.0

package/README.md

@@ -170,16 +170,29 @@ import { module, test } from 'qunitx';
 
 ---
 
-## Concurrency options
+## QUnit compatibility
 
-`module()` and `test()` accept an optional options object forwarded directly to the underlying
-Node / Deno test runner:
+qunitx follows the same test-environment model as QUnit:
+
+- **Fresh context per test** — each test gets its own `this` object. Writes in one test never bleed into a sibling.
+- **Prototype-chain inheritance** — a parent module's `before()` hook sets properties on the module context. Each test inherits those properties, so reads work naturally (`this.x`) while writes stay local to the test.
+- **`before()` assertions** — attributed to the first test in the module (matching QUnit's attribution model).
+- **`after()` assertions** — attributed to the last test in the module.
+- **Hook ordering** — `before`/`beforeEach` run FIFO; `afterEach`/`after` run LIFO, exactly as in QUnit.
+
+> **Known difference:** In QUnit's browser runner, `before()` hook assertions are attributed to the first test in the *entire subtree* (including nested modules). In the Node/Deno adapters, they are attributed to the first *direct* test of the module. In the common case where direct tests appear before nested modules, the behavior is identical.
+
+---
+
+## Concurrency
+
+Tests run **sequentially by default** — matching QUnit's browser behavior where tests run one at a time. You can enable concurrency by passing options to the underlying Node / Deno runner:
 
 ```js
 import { module, test } from 'qunitx';
 
-// Run tests in this module serially
-module('Serial suite', { concurrency: false }, (hooks) => {
+// Enable parallel execution for this module (Node/Deno only)
+module('Parallel suite', { concurrency: true }, (hooks) => {
   test('first', (assert) => { assert.ok(true); });
   test('second', (assert) => { assert.ok(true); });
 });

package/dist/browser/index.d.ts

@@ -0,0 +1,31 @@
+import QUnit from '../../vendor/qunit.js';
+export declare const isLocal: boolean;
+export declare const on: (event: string, callback: (...args: unknown[]) => void) => void;
+export declare const test: (name: string, callback: (assert: unknown) => void | Promise<void>) => void;
+export declare const skip: (name: string, callback: (assert: unknown) => void) => void;
+export declare const start: (count?: number) => void;
+export declare const is: (type: string, obj: unknown) => boolean;
+export declare const extend: (target: object, source: object) => object;
+export declare const stack: (offset?: number) => string;
+export declare const onUnhandledRejection: (reason: unknown) => void;
+export declare const assert: unknown;
+export declare const dump: unknown;
+export declare const done: (callback: (...args: unknown[]) => void) => void;
+export declare const testStart: (callback: (...args: unknown[]) => void) => void;
+export declare const moduleStart: (callback: (...args: unknown[]) => void) => void;
+export declare const version: string;
+export declare const module: (name: string, callback: (hooks: unknown) => void) => void;
+export declare const todo: (name: string, callback: (assert: unknown) => void) => void;
+export declare const only: (name: string, callback: (assert: unknown) => void) => void;
+export declare const config: import("../../vendor/qunit.js").QUnitConfig;
+export declare const objectType: (obj: unknown) => string;
+export declare const load: () => void;
+export declare const onError: (callback: (...args: unknown[]) => void) => void;
+export declare const pushFailure: (message: string, source?: string, value?: unknown) => void;
+export declare const equiv: (a: unknown, b: unknown) => boolean;
+export declare const begin: (callback: (...args: unknown[]) => void) => void;
+export declare const log: (callback: (...args: unknown[]) => void) => void;
+export declare const testDone: (callback: (...args: unknown[]) => void) => void;
+export declare const moduleDone: (callback: (...args: unknown[]) => void) => void;
+export declare const diff: (a: unknown, b: unknown) => string;
+export default QUnit;

package/{shims → dist}/browser/index.js

@@ -1,7 +1,5 @@
 import QUnit from '../../vendor/qunit.js';
-
 QUnit.config.autostart = false;
-
 export const isLocal = QUnit.isLocal;
 export const on = QUnit.on;
 export const test = QUnit.test;
@@ -31,5 +29,4 @@ export const log = QUnit.log;
 export const testDone = QUnit.testDone;
 export const moduleDone = QUnit.moduleDone;
 export const diff = QUnit.diff;
-
 export default QUnit;

package/dist/node/index.d.ts

@@ -0,0 +1,11 @@
+import Module from './module.ts';
+import Test from './test.ts';
+export declare const module: typeof Module;
+export declare const test: typeof Test;
+declare const _default: {
+    AssertionError: import("../types.ts").AssertionErrorConstructor;
+    module: typeof Module;
+    test: typeof Test;
+    config: {};
+};
+export default _default;

package/{shims → dist}/node/index.js

@@ -1,22 +1,20 @@
+/// <reference types="node" />
 import { AssertionError } from 'node:assert';
+import { inspect } from 'node:util';
 import QUnit from '../../vendor/qunit.js';
-import Assert from '../shared/assert.js';
-import ModuleContext from '../shared/module-context.js';
-import TestContext from '../shared/test-context.js';
-import Module from './module.js';
-import Test from './test.js';
-
+import Assert from "../shared/assert.js";
+import ModuleContext from "../shared/module-context.js";
+import TestContext from "../shared/test-context.js";
+import Module from "./module.js";
+import Test from "./test.js";
 Assert.QUnit = QUnit;
 Assert.AssertionError = AssertionError;
-
+Assert.inspect = inspect;
 ModuleContext.Assert = Assert;
 TestContext.Assert = Assert;
-
 Object.freeze(Assert);
 Object.freeze(ModuleContext);
 Object.freeze(TestContext);
-
 export const module = Module;
 export const test = Test;
-
 export default { AssertionError: Assert.AssertionError, module, test, config: {} };

package/dist/node/module.d.ts

@@ -0,0 +1,6 @@
+import type Assert from '../shared/assert.ts';
+import type { HooksObject } from '../types.ts';
+export default function module(moduleName: string, runtimeOptions: object | ((hooks: HooksObject<Assert>) => void), moduleContent?: (hooks: HooksObject<Assert>, meta: {
+    moduleName: string;
+    options: unknown;
+}) => void): void;

package/dist/node/module.js

@@ -0,0 +1,49 @@
+import { describe, before as beforeAll, after as afterAll } from 'node:test';
+import ModuleContext from "../shared/module-context.js";
+export default function module(moduleName, runtimeOptions, moduleContent) {
+    const targetRuntimeOptions = moduleContent ? runtimeOptions : {};
+    const targetModuleContent = (moduleContent ? moduleContent : runtimeOptions);
+    const moduleContext = new ModuleContext(moduleName);
+    describe(moduleName, { ...targetRuntimeOptions }, function () {
+        const beforeHooks = [];
+        const afterHooks = [];
+        beforeAll(async function () {
+            // before() assertions are attributed to the first direct test only (matching QUnit's model).
+            // Tests inherit parent context via prototype chain, so no Object.assign needed.
+            const firstTest = moduleContext.tests[0];
+            const beforeAssert = firstTest ? firstTest.assert : moduleContext.assert;
+            for (const hook of beforeHooks) {
+                await hook.call(moduleContext.userContext, beforeAssert);
+            }
+        });
+        afterAll(async () => {
+            for (const testContext of moduleContext.tests) {
+                await testContext.assert.waitForAsyncOps();
+            }
+            const lastTest = moduleContext.tests[moduleContext.tests.length - 1];
+            if (lastTest) {
+                for (let j = afterHooks.length - 1; j >= 0; j--) {
+                    await afterHooks[j].call(lastTest.userContext, lastTest.assert);
+                }
+            }
+            for (let i = 0, len = moduleContext.tests.length; i < len; i++) {
+                moduleContext.tests[i].finish();
+            }
+        });
+        targetModuleContent.call(moduleContext.userContext, {
+            before(beforeFn) {
+                beforeHooks.push(beforeFn);
+            },
+            beforeEach(beforeEachFn) {
+                moduleContext.beforeEachHooks.push(beforeEachFn);
+            },
+            afterEach(afterEachFn) {
+                moduleContext.afterEachHooks.push(afterEachFn);
+            },
+            after(afterFn) {
+                afterHooks.push(afterFn);
+            }
+        }, { moduleName, options: runtimeOptions });
+        ModuleContext.currentModuleChain.pop();
+    });
+}

package/dist/node/test.d.ts

@@ -0,0 +1,8 @@
+import type Assert from '../shared/assert.ts';
+export default function test(testName: string, runtimeOptions: object | ((assert: Assert, meta: {
+    testName: string;
+    options: unknown;
+}) => void | Promise<void>), testContent?: (assert: Assert, meta: {
+    testName: string;
+    options: unknown;
+}) => void | Promise<void>): void;

package/dist/node/test.js

@@ -0,0 +1,33 @@
+import { it } from 'node:test';
+import TestContext from "../shared/test-context.js";
+import ModuleContext from "../shared/module-context.js";
+export default function test(testName, runtimeOptions, testContent) {
+    const moduleContext = ModuleContext.lastModule;
+    if (!moduleContext) {
+        throw new Error(`Test '${testName}' called outside of module context.`);
+    }
+    const targetRuntimeOptions = testContent ? runtimeOptions : {};
+    const targetTestContent = (testContent ? testContent : runtimeOptions);
+    const context = new TestContext(testName, moduleContext);
+    // Each test gets a fresh plain object inheriting from the module's user context.
+    // This matches QUnit's prototype-chain model: before() sets props on the module context,
+    // tests inherit them, and each test's own writes don't pollute sibling tests.
+    const userContext = Object.create(moduleContext.userContext);
+    context.userContext = userContext;
+    it(testName, { ...targetRuntimeOptions }, async function () {
+        for (const module of context.module.moduleChain) {
+            for (const hook of module.beforeEachHooks) {
+                await hook.call(userContext, context.assert);
+            }
+        }
+        const result = await targetTestContent.call(userContext, context.assert, { testName, options: runtimeOptions });
+        await context.assert.waitForAsyncOps();
+        for (let i = context.module.moduleChain.length - 1; i >= 0; i--) {
+            const module = context.module.moduleChain[i];
+            for (let j = module.afterEachHooks.length - 1; j >= 0; j--) {
+                await module.afterEachHooks[j].call(userContext, context.assert);
+            }
+        }
+        return result;
+    });
+}

package/dist/shared/assert.d.ts

@@ -0,0 +1,360 @@
+import '../../vendor/qunit.js';
+import type { QUnitObject, AssertionErrorConstructor, InspectFn, TestState, ModuleState, PushResultInfo } from '../types.ts';
+/**
+ * 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 {
+    /** @internal Set by each runtime shim before tests run. */
+    static QUnit: QUnitObject;
+    /** @internal Set by each runtime shim before tests run. */
+    static AssertionError: AssertionErrorConstructor;
+    /** @internal Set by each runtime shim before tests run. */
+    static inspect: InspectFn;
+    /** @internal Mutable test state written during the test run. */
+    test: TestState;
+    /** @internal */
+    constructor(module: ModuleState | null, test?: TestState);
+    /** @internal */
+    _incrementAssertionCount(): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string[], message?: string): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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(): () => void;
+    /** @internal Used by the test runner to wait for all async operations to complete. */
+    waitForAsyncOps(): Promise<void[]>;
+    /**
+     * 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?: PushResultInfo): 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: unknown, message?: string): void;
+    /**
+     * 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: unknown, message?: string): void;
+    /**
+     * 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: unknown, message?: string): void;
+    /**
+     * 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: unknown, message?: string): void;
+    /**
+     * 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: unknown, expected: unknown, message?: string): void;
+    /**
+     * 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: unknown, expected: unknown, message?: string): void;
+    /**
+     * 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: unknown, expected: unknown, message?: string): void;
+    /**
+     * 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: unknown, expected: unknown, message?: string): void;
+    /**
+     * 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: unknown, expected: unknown, message?: string): void;
+    /**
+     * 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: unknown, expected: unknown, message?: string): void;
+    /**
+     * 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: unknown, expected: unknown, message?: string): void;
+    /**
+     * 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: unknown, expected: unknown, message?: string): void;
+    /**
+     * 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: unknown, expected: unknown, message?: string): void;
+    /**
+     * 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: unknown, expected: unknown, message?: string): void;
+    /**
+     * 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: unknown, expectedInput?: unknown, assertionMessage?: string): void;
+    /**
+     * 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/);
+     * ```
+     */
+    rejects(promise: unknown, expectedInput?: unknown, assertionMessage?: string): Promise<void>;
+}