@matter/tools 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/testing/mocks/time.ts

@@ -0,0 +1,294 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+type TimerCallback = () => any;
+
+type MockTimeLike = typeof MockTime;
+export interface MockTime extends MockTimeLike {}
+
+// Must match matter.js Timer interface
+class MockTimer {
+    name = "Test";
+    systemId = 0;
+    intervalMs = 0;
+    isPeriodic = false;
+
+    isRunning = false;
+    private readonly callback: TimerCallback;
+
+    constructor(
+        private readonly mockTime: MockTime,
+        private readonly durationMs: number,
+        callback: TimerCallback,
+    ) {
+        if (this instanceof MockInterval) {
+            this.callback = callback;
+        } else {
+            this.callback = () => {
+                this.isRunning = false;
+                callback();
+            };
+        }
+    }
+
+    start() {
+        this.mockTime.callbackAtTime(this.mockTime.nowMs() + this.durationMs, this.callback);
+        this.isRunning = true;
+        return this;
+    }
+
+    stop() {
+        this.mockTime.removeCallback(this.callback);
+        this.isRunning = false;
+        return this;
+    }
+}
+
+class MockInterval extends MockTimer {
+    constructor(mockTime: MockTime, durationMs: number, callback: TimerCallback) {
+        const intervalCallback = async () => {
+            mockTime.callbackAtTime(mockTime.nowMs() + durationMs, intervalCallback);
+            await callback();
+        };
+        super(mockTime, durationMs, intervalCallback);
+    }
+}
+
+type InterceptResult<T> =
+    T extends Promise<T>
+        ? { resolve: Awaited<T>; reject?: undefined } | { resolve?: undefined; reject: {} }
+        : { resolve: T; reject?: undefined } | { resolve?: void; reject: {} };
+
+function isAsync(fn: (...args: any) => any): fn is (...args: any) => Promise<any> {
+    return fn.constructor.name === "AsyncFunction";
+}
+
+let callbacks = new Array<{ atMs: number; callback: TimerCallback }>();
+let nowMs = 0;
+let real = undefined as unknown;
+let enabled = true;
+
+// Must match matter.js Time interface
+export const MockTime = {
+    get activeImplementation(): unknown {
+        return enabled ? this : (real ?? this);
+    },
+
+    disable() {
+        enabled = false;
+        reinstallTime?.();
+    },
+
+    enable() {
+        enabled = true;
+        reinstallTime?.();
+    },
+
+    reset(time = 0) {
+        callbacks = [];
+        nowMs = time;
+
+        // Ensure time reverts to correct implementation across suites
+        reinstallTime?.();
+    },
+
+    now(): Date {
+        return new Date(nowMs);
+    },
+
+    nowMs() {
+        return nowMs;
+    },
+
+    getTimer(_name: string, durationMs: number, callback: TimerCallback): MockTimer {
+        return new MockTimer(this, durationMs, callback);
+    },
+
+    getPeriodicTimer(_name: string, intervalMs: number, callback: TimerCallback): MockTimer {
+        return new MockInterval(this, intervalMs, callback);
+    },
+
+    /**
+     * Resolve a promise with time dependency.
+     *
+     * Moves time forward until the promise resolves.
+     */
+    async resolve<T>(promise: PromiseLike<T>) {
+        let resolved = false;
+        let result: T | undefined;
+        let error: any;
+
+        promise.then(
+            r => {
+                resolved = true;
+                result = r;
+            },
+            e => {
+                resolved = true;
+                error = e;
+            },
+        );
+
+        let timeAdvanced = 0;
+        while (!resolved) {
+            // Interestingly, a Time.yield() works in almost every case.  However, on Node SubtleCrypto.deriveBits hangs
+            // if you only yield via microtask.  It seems to require yielding via macrotask.  So we use setTimeout here.
+            // Probably related to entropy collection but I think it's safe to classify as a Node bug.  Tested on
+            // version 20.11.0
+            await new Promise<void>(resolve => setTimeout(() => resolve(), 0));
+
+            if (resolved) {
+                break;
+            }
+
+            // If we've advanced more than one hour, assume we've hung
+            if (timeAdvanced > 60 * 60 * 1000) {
+                throw new Error(
+                    "Mock timeout: Promise did not resolve within one (virtual) hour, probably not going to happen",
+                );
+            }
+
+            // Advance time exponentially, trying for granularity but also OK performance.  Note that we are not only
+            // advancing time but also yielding event loop.  So it's possible if we run out of time it's just because
+            // there were too few yields in one virtual hour.  As designed currently it's 360 macrotasks and 360
+            // microtasks (360 loops w/ 1 macro- and 1 micro-yield)
+            await this.advance(1000);
+            timeAdvanced += 1000;
+
+            if (resolved) {
+                break;
+            }
+
+            await this.yield();
+        }
+
+        if (error !== undefined) {
+            throw error;
+        }
+
+        return result as T;
+    },
+
+    /**
+     * Move time forward.  Runs tasks scheduled during this interval.
+     */
+    async advance(ms: number) {
+        const newTimeMs = nowMs + ms;
+
+        while (true) {
+            if (callbacks.length === 0) break;
+            const { atMs, callback } = callbacks[0];
+            if (atMs > newTimeMs) break;
+            callbacks.shift();
+            nowMs = atMs;
+            await callback();
+        }
+
+        nowMs = newTimeMs;
+    },
+
+    /**
+     * Yield to scheduled microtasks.  This means that all code paths waiting
+     * on resolved promises (including await) will proceed before this method
+     * returns.
+     */
+    async yield() {
+        await Promise.resolve();
+    },
+
+    /**
+     * Due to its implementation, an older version of yield() would actually
+     * yield to microtasks three times.  Our tests then depended on this
+     * functionality -- one yield could trigger up to three nested awaits.
+     *
+     * To make this clear, the version of yield() that emulates old behavior
+     * is called "yield3".
+     */
+    async yield3() {
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+    },
+
+    /**
+     * Hook a method and invoke a callback just before the method completes.
+     * Unhooks after completion.
+     *
+     * Handles both synchronous and asynchronous methods.  The interceptor
+     * should match the async-ness of the intercepted method.
+     *
+     * The interceptor can optionally access and/or replace the resolve/reject
+     * value.
+     */
+    interceptOnce<NameT extends string, ReturnT, ObjT extends { [N in NameT]: (...args: any) => ReturnT }>(
+        obj: ObjT,
+        method: NameT,
+        interceptor: (
+            result: InterceptResult<ReturnT>,
+        ) => void | InterceptResult<ReturnT> | Promise<void> | Promise<InterceptResult<ReturnT>>,
+    ) {
+        const original = obj[method];
+        if (!original) {
+            throw new Error(`Interception method ${method} is not present`);
+        }
+        let result: InterceptResult<ReturnT>;
+        if (isAsync(interceptor)) {
+            obj[method] = async function (this: any, ...args: any): Promise<any> {
+                try {
+                    // eslint-disable-next-line @typescript-eslint/await-thenable
+                    const resolve = await original.apply(this, args);
+                    result = { resolve } as any;
+                } catch (reject) {
+                    result = { reject } as any;
+                } finally {
+                    obj[method] = original;
+                }
+                result = (await interceptor(result)) ?? result;
+                if (result.reject) {
+                    throw result.reject;
+                }
+                return result.resolve;
+            } as any;
+        } else {
+            obj[method] = function (this: any, ...args: any): any {
+                try {
+                    const resolve = original.apply(this, args);
+                    result = { resolve } as any;
+                } catch (reject) {
+                    result = { reject } as any;
+                } finally {
+                    obj[method] = original;
+                }
+                result = (interceptor(result) as any) ?? result;
+                if (result.reject) {
+                    throw result.reject;
+                }
+                return result.resolve;
+            } as any;
+        }
+    },
+
+    callbackAtTime(atMs: number, callback: TimerCallback) {
+        callbacks.push({ atMs, callback });
+        callbacks.sort(({ atMs: atMsA }, { atMs: atMsB }) => atMsA - atMsB);
+    },
+
+    removeCallback(callbackToRemove: TimerCallback) {
+        const index = callbacks.findIndex(({ callback }) => callbackToRemove === callback);
+        if (index === -1) return;
+        callbacks.splice(index, 1);
+    },
+};
+
+let reinstallTime: undefined | (() => void);
+
+export function timeSetup(Time: { get(): unknown }) {
+    real = Time.get();
+    reinstallTime = () => (Time.get = () => MockTime.activeImplementation);
+    reinstallTime();
+}
+
+Object.assign(globalThis, { MockTime });

package/src/testing/node.ts

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { mkdir, writeFile } from "fs/promises";
+import Mocha from "mocha";
+import { relative } from "path";
+import { adaptReporter, generalSetup } from "./mocha.js";
+import { TestOptions } from "./options.js";
+import type { TestRunner } from "./runner.js";
+
+// Load globals so settings get applied
+import { FailureDetail } from "./failure-detail.js";
+import "./global-definitions.js";
+
+export async function testNode(runner: TestRunner, format: "cjs" | "esm") {
+    // Grr Mocha (as of 10.2.0) classifies certain unhandled rejections as "mocha".  For others, it uninstalls its
+    // unhandled rejection handler and re-emits the "unhandledRejection" event.  But since it already handled the event,
+    // Node knows nothing about this and the event disappears silently.
+    //
+    // So we must add our own unhandledRejection handler, but only process exceptions if Mocha's handler is not
+    // installed, because the code that Mocha uses to determine if an error is a "mocha" error is not exported.
+    process.on("unhandledRejection", e => {
+        if (process.listenerCount("unhandledRejection") === 1) {
+            const error = new Error("Unhandled rejection (ignored by mocha)");
+            error.cause = e;
+            runner.reporter.failRun(FailureDetail(error));
+        }
+    });
+
+    const mocha = new Mocha({
+        inlineDiffs: true,
+        reporter: adaptReporter(Mocha, format.toUpperCase(), runner.reporter),
+    });
+
+    generalSetup(mocha);
+
+    TestOptions.apply(mocha, runner.options);
+
+    const files = runner.loadFiles(format);
+    files.forEach(path => {
+        path = relative(process.cwd(), path);
+        if (path[0] !== ".") {
+            path = `./${path}`;
+        }
+        mocha.addFile(path);
+    });
+
+    await mocha.loadFilesAsync();
+
+    const profiler = new Profiler();
+    if (runner.options.profile) {
+        await profiler.start();
+    }
+
+    await new Promise<Mocha.Runner>(resolve => {
+        const runner = mocha.run(() => resolve(runner));
+    });
+
+    if (runner.options.profile) {
+        await profiler.stop(runner.pkg.resolve("build/profiles"));
+    }
+}
+
+// We use string concatenation to prevent TS from trying to find profiler library types.  It doesn't build on all
+// platforms we support and doesn't provide type declarations when it doesn't build
+//
+// This interface acts as a replacement for proper types
+export interface Profilerish {
+    setGenerateType(value: number): void;
+    startProfiling(): void;
+    stopProfiling(): {
+        export(callback: (error: any, result: string) => any): void;
+    };
+}
+
+// v8-profiler-next doesn't manage switching node versions well.  Load dynamically so it doesn't interfere if it's not
+// built and we're not profiling
+class Profiler {
+    #profiler?: Profilerish;
+
+    async start() {
+        this.#profiler = (await import("" + "v8-profiler-next")).default as Profilerish;
+        this.#profiler.setGenerateType(1);
+        this.#profiler.startProfiling();
+    }
+
+    async stop(outputDir: string) {
+        if (!this.#profiler) {
+            return;
+        }
+
+        const profile = this.#profiler.stopProfiling();
+
+        const result = await new Promise<string>((accept, reject) =>
+            profile.export((error, result) => {
+                if (error) {
+                    reject(error);
+                } else if (!result) {
+                    reject(new Error("No profile error or result"));
+                } else {
+                    accept(result);
+                }
+            }),
+        );
+
+        await mkdir(outputDir, { recursive: true });
+        await writeFile(`${outputDir}/test-${new Date().toISOString().slice(0, 19)}.cpuprofile`, result);
+
+        this.#profiler = undefined;
+    }
+}

package/src/testing/options.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export type TestOptions = {
+    spec?: string | string[];
+    profile?: boolean;
+    grep?: string;
+    fgrep?: string;
+    invert?: boolean;
+    allLogs?: boolean;
+    wtf?: boolean;
+    debug?: boolean;
+};
+
+function option<T extends keyof TestOptions>(options: TestOptions, name: T) {
+    if (options[name] !== undefined && options[name] !== null) {
+        return options[name];
+    }
+
+    // Support both node and browser
+    if (typeof process === "undefined") {
+        return;
+    }
+
+    return process.env?.[
+        "MATTER_" +
+            name
+                .match(/(.[^A-Z]+)/g)
+                ?.map(s => s.toUpperCase())
+                .join("_")
+    ];
+}
+
+export namespace TestOptions {
+    export function apply(mocha: Mocha, options: TestOptions) {
+        const grep = option(options, "grep");
+        if (grep) {
+            mocha.grep(grep);
+        }
+        const fgrep = option(options, "fgrep");
+        if (fgrep) {
+            mocha.fgrep(fgrep);
+        }
+        const invert = option(options, "invert");
+        if (invert) {
+            mocha.invert();
+        }
+        const allLogs = option(options, "allLogs");
+        if (allLogs) {
+            if (typeof MockLogger !== "undefined") {
+                MockLogger.emitAll = true;
+            }
+        }
+    }
+}

package/src/testing/reporter.ts

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import colors from "ansi-colors";
+import { Progress } from "../util/progress.js";
+import { FailureDetail } from "./failure-detail.js";
+
+export type Stats = {
+    total: number;
+    complete: number;
+    failures: number;
+};
+
+export interface Reporter {
+    beginRun(name: string, stats?: Stats, supportsSuites?: boolean): void;
+    beginSuite(name: string[], stats?: Stats): void;
+    beginTest(name: string, stats?: Stats): void;
+    failTest(name: string, detail: FailureDetail): void;
+    endRun(stats?: Stats): void;
+    failRun(detail: FailureDetail): void;
+}
+
+export interface Failure {
+    suite: string[];
+    test: string;
+    detail: FailureDetail;
+}
+
+export abstract class ProgressReporter implements Reporter {
+    private run = "";
+    private suite = Array<string>();
+    private failures = Array<Failure>();
+    private lastTitle?: string;
+
+    constructor(private progress: Progress) {}
+
+    beginRun(name: string, stats: Stats | undefined, supportsSuites = true): void {
+        this.run = name;
+        this.suite = [];
+        this.failures = [];
+        if (!supportsSuites) {
+            this.progress.update(this.#summarize(stats));
+        }
+    }
+
+    beginSuite(name: string[]): void {
+        this.suite = name;
+    }
+
+    beginTest(name: string, stats?: Stats): void {
+        // If not a TTY, only update once per suite to keep the line count down for e.g. GH action logs
+        const title = process.stdout.isTTY ? this.#formatName(this.suite, name) : this.suite[0];
+        if (this.lastTitle !== title) {
+            this.lastTitle = title;
+            this.progress.update(this.#summarize(stats), title);
+        }
+    }
+
+    failTest(name: string, detail: FailureDetail) {
+        this.failures.push({
+            suite: this.suite,
+            test: name,
+            detail,
+        });
+    }
+
+    abstract failRun(detail: FailureDetail): void;
+
+    endRun(stats?: Stats): void {
+        if (this.failures.length) {
+            this.progress.failure(this.#summarize(stats));
+            this.#dumpFailures();
+        } else if (stats && !stats.complete) {
+            this.progress.failure("No tests found");
+        } else {
+            this.progress.success(this.#summarize(stats));
+        }
+    }
+
+    #summarize(stats?: Stats) {
+        let statStr;
+        if (stats) {
+            const complete = colors.dim(`${stats.complete}/${stats.total}`);
+            const failures = stats.failures ? colors.redBright(` ${stats.failures.toString()} failed`) : "";
+            statStr = ` ${complete}${failures}`;
+        } else {
+            statStr = "";
+        }
+
+        return `${colors.bold(this.run)}${statStr}`;
+    }
+
+    #dumpFailures() {
+        for (let i = 0; i < this.failures.length; i++) {
+            const failure = this.failures[i];
+            const index = `Failure ${colors.bold((i + 1).toString())} of ${this.failures.length}`;
+            process.stdout.write(`\n${index} ${this.#formatName(failure.suite, failure.test)}\n\n`);
+
+            FailureDetail.dump(failure.detail, "  ");
+        }
+    }
+
+    #formatName(suite: string[], test: string) {
+        return `${suite.join(" ➡ ")} ➡ ${colors.bold(test)}`;
+    }
+}
+
+const actualConsole = console;
+const actualLog = actualConsole.log;
+
+function proxy(...args: any[]) {
+    actualLog.call(actualConsole, `${ConsoleProxyReporter.FLAG}${JSON.stringify(args)}`);
+}
+
+export class ConsoleProxyReporter implements Reporter {
+    static FLAG = "<<REPORT>> ";
+
+    beginRun(name: string, stats?: Stats) {
+        proxy("beginRun", name, stats);
+    }
+
+    beginSuite(name: string[], stats?: Stats) {
+        proxy("beginSuite", name, stats);
+    }
+
+    beginTest(name: string, stats?: Stats) {
+        proxy("beginTest", name, stats);
+    }
+
+    endRun(stats?: Stats) {
+        proxy("endRun", stats);
+    }
+
+    failTest(name: string, detail: FailureDetail) {
+        proxy("failTest", name, detail);
+    }
+
+    failRun(detail: FailureDetail) {
+        proxy("failRun", detail);
+    }
+}

package/src/testing/runner.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import colors from "ansi-colors";
+import debug from "debug";
+import { glob } from "glob";
+import { relative } from "path";
+import { Package } from "../util/package.js";
+import { Progress } from "../util/progress.js";
+import { Chip } from "./chip.js";
+import { FailureDetail } from "./failure-detail.js";
+import { listSupportFiles } from "./files.js";
+import { testNode } from "./node.js";
+import { TestOptions } from "./options.js";
+import { ProgressReporter, Reporter } from "./reporter.js";
+import { testWeb } from "./web.js";
+
+export class TestRunner {
+    readonly reporter: Reporter;
+    private spec = Array<string>();
+
+    constructor(
+        readonly pkg: Package,
+        readonly progress: Progress,
+        readonly options: TestOptions,
+    ) {
+        Chip.config = { runner: this };
+
+        this.reporter = new (class extends ProgressReporter {
+            constructor() {
+                super(progress);
+            }
+            override failRun(detail: FailureDetail) {
+                process.stdout.write("\n");
+                FailureDetail.dump(detail);
+                process.exit(1);
+            }
+        })();
+
+        if (options.spec === undefined) {
+            this.spec = ["test/**/*Test.ts"];
+        } else if (Array.isArray(options.spec)) {
+            this.spec = options.spec;
+        } else {
+            this.spec = [options.spec];
+        }
+
+        if (options.debug) {
+            debug.enable("mocha:*");
+        }
+    }
+
+    async runNode(format: "esm" | "cjs" = "esm") {
+        await this.run(this.progress, () => testNode(this, format));
+    }
+
+    async runWeb(manual = false) {
+        await this.run(this.progress, () => testWeb(this, manual));
+    }
+
+    loadFiles(format: "esm" | "cjs") {
+        const tests = [];
+        for (let spec of this.spec) {
+            spec = spec.replace(/\.ts$/, ".js");
+            spec = relative(this.pkg.path, spec);
+            if (!spec.startsWith(".") && !spec.startsWith("build/") && !spec.startsWith("dist/")) {
+                spec = `build/${format}/${spec}`;
+            }
+            spec = this.pkg.resolve(spec);
+
+            // Glob only understands forward-slash as separator because reasons
+            spec = spec.replace(/\\/g, "/");
+
+            tests.push(...glob.sync(spec));
+        }
+
+        if (!tests.length) {
+            fatal(`No files match ${this.spec.join(", ")}`);
+        }
+
+        return [...listSupportFiles(format), ...tests];
+    }
+
+    private async run(progress: Progress, runner: () => Promise<void>) {
+        await runner();
+        if (progress.status !== Progress.Status.Success) {
+            fatal(`Test ${progress.status.toLowerCase()}, aborting`);
+        }
+    }
+}
+
+function fatal(message: string) {
+    process.stderr.write(colors.redBright(`\n${message}\n\n`));
+    process.exit(1);
+}