qunitx 1.0.3 → 1.1.0

package/dist/shared/index.js

@@ -0,0 +1,154 @@
+const hasOwn = Object.prototype.hasOwnProperty;
+export function objectType(obj) {
+    if (typeof obj === 'undefined') {
+        return 'undefined';
+    }
+    // Consider: typeof null === object
+    if (obj === null) {
+        return 'null';
+    }
+    // slice(8, -1) extracts the type name from "[object Foo]" without a regex
+    const type = Object.prototype.toString.call(obj).slice(8, -1);
+    switch (type) {
+        case 'Number':
+            if (isNaN(obj)) {
+                return 'nan';
+            }
+            return 'number';
+        case 'String':
+        case 'Boolean':
+        case 'Array':
+        case 'Set':
+        case 'Map':
+        case 'Date':
+        case 'RegExp':
+        case 'Function':
+        case 'Symbol':
+            return type.toLowerCase();
+        default:
+            return typeof obj;
+    }
+}
+function is(type, obj) {
+    return objectType(obj) === type;
+}
+export function objectValues(obj, allowArray = true) {
+    const vals = allowArray && is('array', obj) ? [] : {};
+    for (const key in obj) {
+        if (hasOwn.call(obj, key)) {
+            const val = obj[key];
+            vals[key] = val === Object(val) ? objectValues(val, allowArray) : val;
+        }
+    }
+    return vals;
+}
+/**
+ *
+ * Recursively clone an object into a plain object, taking only the
+ * subset of own enumerable properties that exist a given model.
+ *
+ * @param {any} obj
+ * @param {any} model
+ * @return {Object}
+ */
+export function objectValuesSubset(obj, model) {
+    // Return primitive values unchanged to avoid false positives or confusing
+    // results from assert.propContains().
+    // E.g. an actual null or false wrongly equaling an empty object,
+    // or an actual string being reported as object not matching a partial object.
+    if (obj !== Object(obj)) {
+        return obj;
+    }
+    // Unlike objectValues(), subset arrays to a plain objects as well.
+    // This enables subsetting [20, 30] with {1: 30}.
+    const subset = {};
+    for (const key in model) {
+        if (hasOwn.call(model, key) && hasOwn.call(obj, key)) {
+            subset[key] = objectValuesSubset(obj[key], model[key]);
+        }
+    }
+    return subset;
+}
+export function validateExpectedExceptionArgs(expected, message, assertionMethod) {
+    const expectedType = objectType(expected);
+    // 'expected' is optional unless doing string comparison
+    if (expectedType === 'string') {
+        if (message === undefined) {
+            message = expected;
+            expected = undefined;
+            return [expected, message];
+        }
+        else {
+            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.');
+        }
+    }
+    const valid = !expected ||
+        // TODO: be more explicit here
+        expectedType === 'regexp' || expectedType === 'function' || expectedType === 'object';
+    if (!valid) {
+        throw new Error('Invalid expected value type (' + expectedType + ') ' + 'provided to assert.' + assertionMethod + '.');
+    }
+    return [expected, message];
+}
+export function validateException(actual, expected, message) {
+    let result = false;
+    const expectedType = objectType(expected);
+    // These branches should be exhaustive, based on validation done in validateExpectedException
+    // We don't want to validate
+    if (!expected) {
+        result = true;
+        // Expected is a regexp
+    }
+    else if (expectedType === 'regexp') {
+        result = expected.test(errorString(actual));
+        // Log the string form of the regexp
+        expected = String(expected);
+        // Expected is a constructor, maybe an Error constructor.
+        // Note the extra check on its prototype - this is an implicit
+        // requirement of "instanceof", else it will throw a TypeError.
+    }
+    else if (expectedType === 'function' &&
+        expected.prototype !== undefined &&
+        actual instanceof expected) {
+        result = true;
+        // Expected is an Error object
+    }
+    else if (expectedType === 'object') {
+        result =
+            actual instanceof expected.constructor &&
+                actual.name === expected.name &&
+                actual.message === expected.message;
+        // Log the string form of the Error object
+        expected = errorString(expected);
+        // Expected is a validation function which returns true if validation passed
+    }
+    else if (expectedType === 'function') {
+        // protect against accidental semantics which could hard error in the test
+        try {
+            result = expected.call({}, actual) === true;
+            expected = null;
+        }
+        catch (e) {
+            // assign the "expected" to a nice error string to communicate the local failure to the user
+            expected = errorString(e);
+        }
+    }
+    return [result, expected, message];
+}
+function errorString(error) {
+    // Use String() instead of toString() to handle non-object values like undefined or null.
+    const resultErrorString = String(error);
+    // If the error wasn't a subclass of Error but something like
+    // an object literal with name and message properties...
+    if (resultErrorString.slice(0, 7) === '[object') {
+        // Based on https://es5.github.io/#x15.11.4.4
+        return ((error.name || 'Error') +
+            (error.message
+                ? ': '.concat(error.message)
+                : ''));
+    }
+    else {
+        return resultErrorString;
+    }
+}
+export default { objectValues, objectValuesSubset, validateExpectedExceptionArgs, validateException };

package/dist/shared/module-context.d.ts

@@ -0,0 +1,17 @@
+import type Assert from './assert.ts';
+import type { HookFn } from '../types.ts';
+import TestContext from './test-context.ts';
+export default class ModuleContext {
+    static Assert: typeof Assert;
+    static currentModuleChain: ModuleContext[];
+    static get lastModule(): ModuleContext;
+    name: string;
+    assert: Assert;
+    userContext: object;
+    context: TestContext;
+    moduleChain: ModuleContext[];
+    beforeEachHooks: HookFn<Assert>[];
+    afterEachHooks: HookFn<Assert>[];
+    tests: TestContext[];
+    constructor(name: string);
+}

package/dist/shared/module-context.js

@@ -0,0 +1,28 @@
+import TestContext from "./test-context.js";
+export default class ModuleContext {
+    static Assert;
+    static currentModuleChain = [];
+    static get lastModule() {
+        return this.currentModuleChain[this.currentModuleChain.length - 1];
+    }
+    name;
+    assert;
+    userContext;
+    // Internal fallback assert for modules with no direct tests
+    context = new TestContext();
+    moduleChain = [];
+    beforeEachHooks = [];
+    afterEachHooks = [];
+    tests = [];
+    constructor(name) {
+        const parentModule = ModuleContext.currentModuleChain[ModuleContext.currentModuleChain.length - 1];
+        ModuleContext.currentModuleChain.push(this);
+        this.moduleChain = ModuleContext.currentModuleChain.slice(0);
+        this.name = parentModule ? `${parentModule.name} > ${name}` : name;
+        this.assert = new ModuleContext.Assert(this);
+        // User context uses prototype chain from parent module for proper QUnit-style inheritance:
+        // parent before() sets props on parent userContext, child tests inherit via prototype.
+        this.userContext = parentModule ? Object.create(parentModule.userContext) : Object.create(null);
+        return Object.freeze(this);
+    }
+}

package/dist/shared/test-context.d.ts

@@ -0,0 +1,25 @@
+import type Assert from './assert.ts';
+import type ModuleContext from './module-context.ts';
+export default class TestContext {
+    #private;
+    static Assert: typeof Assert;
+    get name(): string | undefined;
+    set name(value: string | undefined);
+    get module(): ModuleContext | undefined;
+    set module(value: ModuleContext | undefined);
+    get asyncOps(): Promise<void>[];
+    set asyncOps(value: Promise<void>[]);
+    get assert(): Assert | undefined;
+    set assert(value: Assert | undefined);
+    get timeout(): number | undefined;
+    set timeout(value: number | undefined);
+    get steps(): string[];
+    set steps(value: string[]);
+    get expectedAssertionCount(): number | undefined;
+    set expectedAssertionCount(value: number | undefined);
+    get totalExecutedAssertions(): number;
+    set totalExecutedAssertions(value: number);
+    userContext: object;
+    constructor(name?: string, moduleContext?: ModuleContext);
+    finish(): void;
+}

package/dist/shared/test-context.js

@@ -0,0 +1,94 @@
+export default class TestContext {
+    static Assert;
+    #name;
+    get name() {
+        return this.#name;
+    }
+    set name(value) {
+        this.#name = value;
+    }
+    #module;
+    get module() {
+        return this.#module;
+    }
+    set module(value) {
+        this.#module = value;
+    }
+    #asyncOps = [];
+    get asyncOps() {
+        return this.#asyncOps;
+    }
+    set asyncOps(value) {
+        this.#asyncOps = value;
+    }
+    #assert;
+    get assert() {
+        return this.#assert;
+    }
+    set assert(value) {
+        this.#assert = value;
+    }
+    #timeout;
+    get timeout() {
+        return this.#timeout;
+    }
+    set timeout(value) {
+        this.#timeout = value;
+    }
+    #steps = [];
+    get steps() {
+        return this.#steps;
+    }
+    set steps(value) {
+        this.#steps = value;
+    }
+    #expectedAssertionCount;
+    get expectedAssertionCount() {
+        return this.#expectedAssertionCount;
+    }
+    set expectedAssertionCount(value) {
+        this.#expectedAssertionCount = value;
+    }
+    #totalExecutedAssertions = 0;
+    get totalExecutedAssertions() {
+        return this.#totalExecutedAssertions;
+    }
+    set totalExecutedAssertions(value) {
+        this.#totalExecutedAssertions = value;
+    }
+    userContext = {};
+    constructor(name, moduleContext) {
+        if (moduleContext) {
+            this.name = `${moduleContext.name} | ${name}`;
+            this.module = moduleContext;
+            this.module.tests.push(this);
+            this.assert = new TestContext.Assert(moduleContext, this);
+        }
+    }
+    finish() {
+        if (this.totalExecutedAssertions === 0) {
+            this.assert.pushResult({
+                result: false,
+                actual: this.totalExecutedAssertions,
+                expected: '> 0',
+                message: `Expected at least one assertion to be run for test: ${this.name}`,
+            });
+        }
+        else if (this.steps.length > 0) {
+            this.assert.pushResult({
+                result: false,
+                actual: this.steps,
+                expected: [],
+                message: `Expected assert.verifySteps() to be called before end of test after using assert.step(). Unverified steps: ${this.steps.join(', ')}`,
+            });
+        }
+        else if (this.expectedAssertionCount && this.expectedAssertionCount !== this.totalExecutedAssertions) {
+            this.assert.pushResult({
+                result: false,
+                actual: this.totalExecutedAssertions,
+                expected: this.expectedAssertionCount,
+                message: `Expected ${this.expectedAssertionCount} assertions, but ${this.totalExecutedAssertions} were run for test: ${this.name}`,
+            });
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+export interface AssertionErrorOptions {
+    message?: string;
+    actual?: unknown;
+    expected?: unknown;
+    operator?: string;
+    stackStartFn?: (...args: never[]) => unknown;
+}
+export type InspectFn = (value: unknown, options?: {
+    depth?: number;
+    colors?: boolean;
+    compact?: boolean | number;
+}) => string;
+export interface AssertionErrorConstructor {
+    new (options: AssertionErrorOptions): Error;
+}
+/** Result object passed to {@linkcode Assert.prototype.pushResult}. */
+export interface PushResultInfo {
+    /** Whether the assertion passed (`true`) or failed (`false`). */
+    result?: boolean;
+    /** The actual value produced by the code under test. */
+    actual?: unknown;
+    /** The expected value. */
+    expected?: unknown;
+    /** Human-readable description of the assertion. */
+    message?: string;
+}
+export interface QUnitObject {
+    equiv(a: unknown, b: unknown): boolean;
+    config: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Minimal assertion-tracking state that Assert reads/writes per test. */
+export interface TestState {
+    totalExecutedAssertions: number;
+    steps: string[];
+    asyncOps: Promise<void>[];
+    timeout?: number;
+    expectedAssertionCount?: number;
+    userContext?: object;
+    module?: {
+        name: string;
+    };
+}
+/** Minimal module shape that Assert needs to resolve a fallback test context. */
+export interface ModuleState {
+    context: TestState;
+}
+/** A lifecycle hook callback that receives an {@linkcode Assert} instance. */
+export type HookFn<A = unknown> = (assert: A) => void | Promise<void>;
+export type TestFn<A = unknown> = (assert: A, meta: {
+    testName: string;
+    options: unknown;
+}) => void | Promise<unknown>;
+/** Lifecycle hooks available inside a `module()` callback. */
+export interface HooksObject<A = unknown> {
+    /** Runs once before the first test in the module. */
+    before(fn: HookFn<A>): void;
+    /** Runs before each test in the module. */
+    beforeEach(fn: HookFn<A>): void;
+    /** Runs after each test in the module. */
+    afterEach(fn: HookFn<A>): void;
+    /** Runs once after the last test in the module. */
+    after(fn: HookFn<A>): void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "qunitx",
   "type": "module",
-  "version": "1.0.3",
+  "version": "1.1.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",
@@ -48,51 +48,62 @@
   },
   "imports": {
     "qunitx": {
-      "node": "./shims/node/index.js",
-      "deno": "./shims/deno/index.js",
-      "default": "./shims/browser/index.js"
+      "types": "./dist/node/index.d.ts",
+      "node": "./dist/node/index.js",
+      "deno": "./shims/deno/index.ts",
+      "default": "./dist/browser/index.js"
     }
   },
   "exports": {
-    "node": "./shims/node/index.js",
-    "deno": "./shims/deno/index.js",
-    "default": "./shims/browser/index.js"
+    "types": "./dist/node/index.d.ts",
+    "node": "./dist/node/index.js",
+    "deno": "./shims/deno/index.ts",
+    "default": "./dist/browser/index.js"
   },
+  "files": [
+    "dist/",
+    "shims/deno/",
+    "shims/shared/",
+    "shims/types.ts",
+    "vendor/"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/izelnakri/qunitx.git"
   },
   "scripts": {
-    "format": "prettier --check \"test/**/*.js\" \"*.js\" \"package.json\"",
-    "format:fix": "prettier --write \"test/**/*.js\" \"*.js\" \"package.json\"",
+    "format": "prettier --check \"test/**/*.ts\" \"*.ts\" \"package.json\"",
+    "format:fix": "prettier --write \"test/**/*.ts\" \"*.ts\" \"package.json\"",
     "lint": "deno lint shims/",
-    "lint:docs": "deno doc --lint shims/deno/module.js shims/deno/test.js",
-    "build": "node build.js",
+    "lint:docs": "deno doc --lint shims/deno/module.ts shims/deno/test.ts",
+    "build": "node --experimental-strip-types build.ts",
+    "pretest": "node --experimental-strip-types build.ts",
     "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",
-    "run:deno": "deno test test/helpers/passing-tests.js && deno test test/helpers/failing-tests.js",
+    "run:node": "node --experimental-strip-types --test test/helpers/passing-tests.ts && node --experimental-strip-types --test test/helpers/failing-tests.ts",
+    "run:deno": "deno test test/helpers/passing-tests.ts && deno test test/helpers/failing-tests.ts",
     "changelog:unreleased": "git-cliff --unreleased --strip all",
     "changelog:preview": "git-cliff",
     "changelog:update": "git-cliff --output CHANGELOG.md",
-    "prepack": "npm run build",
+    "prepare": "npm run build",
     "test": "npm run test:browser && npm run test:node && npm run test:deno",
     "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: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",
+    "test:browser": "qunitx test/index.ts --debug",
+    "test:deno": "deno test --allow-read --allow-env --allow-run test/index.ts",
+    "test:doctests": "deno test --doc --allow-env --allow-read shims/deno/module.ts shims/deno/test.ts",
+    "test:node": "node --experimental-strip-types --test test/index.ts",
+    "coverage": "deno test --coverage=tmp/coverage --allow-read --allow-env --allow-run test/index.ts && deno coverage --lcov --output=tmp/coverage/lcov.info --include='shims/' tmp/coverage && node --experimental-strip-types scripts/check-coverage.ts",
     "coverage:report": "npm run coverage && deno coverage --html --include='shims/' tmp/coverage",
     "bench": "deno task bench",
     "bench:check": "deno task bench:check",
     "bench:update": "deno task bench:update",
-    "docs": "deno doc --html --name=\"QUnitX\" --output=docs/src shims/deno/index.js"
+    "docs": "deno doc --html --name=\"QUnitX\" --output=docs/src shims/deno/index.ts"
   },
   "devDependencies": {
     "prettier": "^3.8.1",
     "qunit": "^2.25.0",
-    "qunitx": "^0.9.3",
-    "qunitx-cli": "^0.5.0"
+    "qunitx": "^1.0.3",
+    "qunitx-cli": "^0.5.3",
+    "typescript": "^6.0.2"
   },
   "volta": {
     "node": "24.14.0"

package/shims/deno/{index.js → index.ts}

@@ -25,12 +25,13 @@
  * @module
  */
 import { AssertionError as DenoAssertionError } from "jsr:@std/assert";
+import type { AssertionErrorOptions } from "../types.ts";
 import '../../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.ts';
+import ModuleContext from '../shared/module-context.ts';
+import TestContext from '../shared/test-context.ts';
+import Module from './module.ts';
+import Test from './test.ts';
 
 /**
  * Thrown when an assertion fails. Extends Deno's built-in `AssertionError`
@@ -51,13 +52,14 @@ import Test from './test.js';
  * ```
  */
 export class AssertionError extends DenoAssertionError {
-  constructor(object) {
-    super(object.message);
+  constructor(object: AssertionErrorOptions) {
+    super(object.message ?? 'Assertion failed');
   }
 }
 
-Assert.QUnit = globalThis.QUnit;
+Assert.QUnit = (globalThis as typeof globalThis & { QUnit: typeof Assert.QUnit }).QUnit;
 Assert.AssertionError = AssertionError;
+Assert.inspect = Deno.inspect;
 ModuleContext.Assert = Assert;
 TestContext.Assert = Assert;
 

package/shims/deno/module.ts

@@ -0,0 +1,93 @@
+import { describe, beforeAll, afterAll } from "jsr:@std/testing/bdd";
+import type Assert from '../shared/assert.ts';
+import type { HooksObject } from '../types.ts';
+import ModuleContext from '../shared/module-context.ts';
+export type { Assert };
+export type { HookFn, HooksObject, PushResultInfo } from '../types.ts';
+
+/**
+ * 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: string,
+  runtimeOptions: object | ((hooks: HooksObject<Assert>) => void),
+  moduleContent?: (hooks: HooksObject<Assert>, meta: { moduleName: string; options: unknown }) => void,
+): void {
+  const targetRuntimeOptions = moduleContent ? runtimeOptions as object : {};
+  const targetModuleContent = (moduleContent ? moduleContent : runtimeOptions) as (hooks: HooksObject<Assert>, meta: { moduleName: string; options: unknown }) => void;
+  const moduleContext = new ModuleContext(moduleName);
+
+  describe(moduleName, { ...targetRuntimeOptions }, function () {
+    const beforeHooks: ((assert: Assert) => void | Promise<void>)[] = [];
+    const afterHooks: ((assert: Assert) => void | Promise<void>)[] = [];
+
+    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();
+  });
+}