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

package/src/testing/failure-detail.ts

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import colors from "ansi-colors";
+
+export interface FailureDetail {
+    message: string;
+    stack?: string;
+    diff?: string;
+    logs?: string;
+    cause?: FailureDetail;
+    errors?: FailureDetail[];
+}
+
+export function FailureDetail(error: any, logs?: string[]) {
+    let diff: string | undefined;
+
+    const { message, stack, cause, errors } = parseError(error);
+
+    if (error.expected && error.actual) {
+        if (FailureDetail.diff === undefined) {
+            diff = "(no diff implementation installed)";
+        } else {
+            diff = FailureDetail.diff(error.actual.toString(), error.expected.toString());
+            diff = diff.trim().replace(/^ {6}/gms, "");
+        }
+    }
+
+    const result = { message } as FailureDetail;
+    if (diff) {
+        result.diff = diff;
+    }
+    if (stack) {
+        result.stack = stack;
+    }
+    if (logs?.length) {
+        result.logs = logs.join("\n");
+    }
+    if (cause) {
+        result.cause = cause;
+    }
+    if (errors) {
+        result.errors = errors;
+    }
+
+    return result;
+}
+
+export namespace FailureDetail {
+    export function dump(failure: FailureDetail, prefix: string = "") {
+        process.stdout.write(colors.redBright(`${prefix}${failure.message}\n\n`));
+
+        if (failure.diff) {
+            process.stdout.write(`${prefix}    ${failure.diff.replace(/\n/gm, "\n      ")}\n\n`);
+        }
+
+        if (failure.stack) {
+            process.stdout.write(`${prefix}${colors.dim(failure.stack.replace(/\n/gm, `\n${prefix}`))}\n\n`);
+        }
+
+        if (failure.cause) {
+            process.stdout.write(`${prefix}Caused by:\n\n`);
+            dump(failure.cause, prefix);
+        }
+
+        if (failure.errors?.length) {
+            let num = 0;
+            for (const cause of failure.errors) {
+                process.stdout.write(`${prefix}Cause #${++num}:\n\n`);
+                dump(cause, `${prefix}  `);
+            }
+        }
+
+        if (failure.logs) {
+            process.stdout.write(`  ${failure.logs.replace(/\n/gm, "\n  ")}\n\n`);
+        }
+    }
+
+    export let diff: undefined | ((actual: string, expected: string) => string);
+}
+
+function parseError(error: Error) {
+    let message, stack, cause: FailureDetail | undefined, errors: FailureDetail[] | undefined;
+
+    if (error === undefined || error === null) {
+        message = `(error is ${error})`;
+    } else {
+        message = error.message;
+    }
+
+    if (error.stack) {
+        let lines = error.stack.trim().split("\n");
+        if (!message) {
+            message = lines[0];
+        }
+        lines = lines.filter(line => line.match(/:\d+:\d+\)?/));
+        if (lines.length) {
+            stack = lines.map(line => line.trim()).join("\n");
+        }
+    } else if (error.message) {
+        message = error.message;
+    } else {
+        message = error.toString();
+    }
+
+    message = message.trim().replace(/Error: /, "");
+
+    if (message.endsWith(":")) {
+        message = message.slice(0, message.length - 1);
+    }
+
+    const errorCause = error.cause;
+    if (errorCause) {
+        cause = FailureDetail(errorCause);
+    }
+
+    const errorErrors = (error as AggregateError).errors;
+    if (Array.isArray(errorErrors)) {
+        errors = errorErrors.map(e => FailureDetail(e));
+    }
+
+    return { message, stack, cause, errors };
+}

package/src/testing/files.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { existsSync, statSync } from "fs";
+import { Package } from "../util/package.js";
+
+export function listSupportFiles(format = "cjs") {
+    const files = Array<string>();
+
+    // Always load tooling code in ESM format as tooling globals load as ESM
+    files.push(Package.tools.resolve("dist/esm/testing/global-definitions.js"));
+    files.push(Package.tools.resolve("dist/esm/testing/mocks/index.js"));
+
+    // Package code should load in the format being tested
+    const config = new Package().resolve(`build/${format}/test/test.config.js`);
+    if (existsSync(config)) {
+        files.push(config);
+    }
+
+    return files;
+}
+
+export function maybeStatSync(path: string) {
+    try {
+        return statSync(path);
+    } catch (e) {
+        if (typeof e === "object" && e !== null && "code" in e && (e.code === "ENOENT" || e.code === "ENOTDIR")) {
+            return;
+        }
+        throw e;
+    }
+}

package/src/testing/global-declarations.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type Chai from "chai";
+import "chai-as-promised";
+import type { MockLogger } from "./mocks/logging.js";
+import type { MockTime } from "./mocks/time.js";
+
+declare global {
+    // Expose Chai globally
+    const expect: typeof Chai.expect;
+
+    // Expose API for controlling time
+    let MockTime: MockTime;
+
+    // Expose API for controlling logging
+    let MockLogger: MockLogger;
+
+    /**
+     * If present, the following hooks are engaged by matter.js packages to
+     * enable mocking.  We use globals rather than imports so we can hook the
+     * modules regardless of whether they're loaded as CommonJS or ESM.
+     */
+    let MatterHooks:
+        | undefined
+        | {
+              /**
+               * Configure time.
+               */
+              timeSetup?: (Time: any) => void;
+
+              /**
+               * Configure logging.
+               */
+              loggerSetup?: (Logger: any) => void;
+
+              /**
+               * Configure crypto.
+               */
+              cryptoSetup?: (Crypto: any) => void;
+
+              /**
+               * Receive intercepted log messages.  The logging mocks
+               */
+              loggerSink?: (level: number, message: string) => void;
+          };
+}

package/src/testing/global-definitions.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Note - we don't import mocha here because in the browser we load their standard browser bundle which is different
+// from the Node version
+
+import Chai from "chai";
+import ChaiAsPromised from "chai-as-promised";
+import { browserSetup, generalSetup } from "./mocha.js";
+import { cryptoSetup } from "./mocks/crypto.js";
+import { TheMockLogger, loggerSetup } from "./mocks/logging.js";
+import { timeSetup } from "./mocks/time.js";
+
+Chai.config.truncateThreshold = 200;
+Chai.use(ChaiAsPromised);
+
+Object.assign(globalThis, {
+    expect: Chai.expect,
+
+    MatterHooks: {
+        loggerSetup,
+        timeSetup,
+        cryptoSetup,
+    },
+
+    MockLogger: TheMockLogger,
+});
+
+if (typeof window === "object" && globalThis === window) {
+    generalSetup(mocha);
+    browserSetup(mocha);
+}

package/src/testing/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Matter.js Web Testing</title>
+    <link rel="stylesheet" href="mocha/mocha.css">
+  </head>
+  <body>
+    <div id="mocha"></div>
+    <script src="mocha/mocha.js"></script>
+    <script src="tests.js"></script>
+    <script>
+      mocha.setup("bdd");
+      mocha.run();
+    </script>
+  </body>
+</html>

package/src/testing/mocha.ts

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Can't import Mocha in the browser so just import type here
+import type MochaType from "mocha";
+import { wtf } from "../util/wtf.js";
+import { FailureDetail } from "./failure-detail.js";
+import { LoggerHooks } from "./mocks/logging.js";
+import { TestOptions } from "./options.js";
+import { ConsoleProxyReporter, Reporter } from "./reporter.js";
+
+export function generalSetup(mocha: MochaType) {
+    const Base = (mocha.constructor as typeof MochaType).reporters.Base;
+
+    // White text, 16-bit and 256-bit green background
+    Base.colors["diff added inline"] = "97;42;48;5;22" as any;
+
+    // White text, 16-bit and 256-bit red background
+    Base.colors["diff removed inline"] = "97;41;48;5;52" as any;
+
+    // Some of our test suites have setup/teardown logic that logs profusely. Hide these logs unless something goes
+    // wrong
+    async function onlyLogFailure(fn: () => any) {
+        if (!MatterHooks) {
+            throw new Error("Matter hooks not loaded");
+        }
+
+        const logs = Array<string>();
+        const existingSink = MatterHooks.loggerSink;
+        try {
+            MatterHooks.loggerSink = (_, message) => {
+                logs.push(message);
+            };
+            return await fn();
+        } catch (e) {
+            process.stdout.write(logs.join("\n"));
+            throw e;
+        } finally {
+            MatterHooks.loggerSink = existingSink;
+        }
+    }
+
+    function filterLogs(hook: "beforeAll" | "afterAll" | "beforeEach" | "afterEach") {
+        const actual = mocha.suite[hook] as (this: any, fn: Mocha.Func) => any;
+        mocha.suite[hook] = function (this: any, fn: Mocha.Func) {
+            return actual.call(this, async function (this: any, ...args: any) {
+                return await onlyLogFailure(() => fn.apply(this, args));
+            });
+        } as any;
+    }
+
+    filterLogs("beforeAll");
+    filterLogs("afterAll");
+    filterLogs("beforeEach");
+    filterLogs("afterEach");
+
+    // Reset mocks before each suite.  Suites could conceivably have callbacks that occur across tests.  If individual
+    // tests need a reset the suite needs to handle itself.
+    const actualBeforeAll = mocha.suite.beforeAll;
+    mocha.suite.beforeAll = function (this: Mocha.Context, ...args: any) {
+        MockTime.reset();
+        return actualBeforeAll.apply(this, args);
+    };
+
+    mocha.suite.beforeEach(() => {
+        for (const hook of LoggerHooks.beforeEach) {
+            hook(mocha);
+        }
+    });
+
+    mocha.suite.afterEach(() => {
+        for (const hook of LoggerHooks.afterEach) {
+            hook(mocha);
+        }
+    });
+
+    FailureDetail.diff = Base.generateDiff.bind(Base);
+}
+
+export function adaptReporter(Mocha: typeof MochaType, title: string, reporter: Reporter) {
+    const RUNNER = Mocha.Runner.constants;
+
+    let logs = Array<string>();
+
+    class MochaReporter extends Mocha.reporters.Base {
+        constructor(runner: Mocha.Runner) {
+            super(runner);
+
+            runner.once(RUNNER.EVENT_RUN_BEGIN, () => {
+                if (!MatterHooks) {
+                    throw new Error("Matter hooks not loaded");
+                }
+                MatterHooks.loggerSink = (_, message) => {
+                    logs.push(message);
+                };
+                reporter.beginRun(title, this.translatedStats);
+            });
+
+            runner.on(RUNNER.EVENT_SUITE_BEGIN, suite => {
+                reporter.beginSuite(suite.titlePath(), this.translatedStats);
+            });
+
+            runner.on(RUNNER.EVENT_TEST_BEGIN, test => {
+                logs = (test as any).logs = [];
+                reporter.beginTest(test.title, this.translatedStats);
+            });
+
+            runner.on(RUNNER.EVENT_TEST_FAIL, (test, error) => {
+                const logs = (test as any).logs as string[];
+                reporter.failTest(test.title, FailureDetail(error, logs));
+                wtf.dump();
+            });
+
+            runner.once(RUNNER.EVENT_RUN_END, () => {
+                if (!MatterHooks) {
+                    throw new Error("Matter hooks not loaded");
+                }
+                MatterHooks.loggerSink = undefined;
+                reporter.endRun(this.translatedStats);
+                wtf.dump();
+            });
+        }
+
+        get translatedStats() {
+            return {
+                total: this.runner.total,
+                complete: this.stats.tests,
+                failures: this.stats.failures,
+            };
+        }
+    }
+
+    return MochaReporter;
+}
+
+export function browserSetup(mocha: BrowserMocha) {
+    mocha.setup("bdd");
+
+    (globalThis as any).MatterTest = {
+        // Starts Mocha (called by clicking link)
+        start: () => {
+            const root = document.querySelector("#mocha");
+            if (root) {
+                root.innerHTML = "";
+            }
+            return mocha.run();
+        },
+
+        // Start Mocha, proxying reporting through console to Playwright and completing once Mocha has finished
+        auto: async function (options: TestOptions) {
+            TestOptions.apply(mocha, options);
+            mocha.reporter(adaptReporter(Mocha, "Web", new ConsoleProxyReporter()));
+            return new Promise<void>(accept => {
+                const runner = this.start();
+                runner.on("end", accept);
+            });
+        },
+    };
+}

package/src/testing/mocharc.cjs

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// This file configures mocha for "buildless" dev execution.  May be useful for running tests in IDE with Mocha support.
+// Utilize by importing into .mocharc.cjs as a sibling of package.json in the package to test
+
+// Required for Node < 19 (see node-shims.ts)
+const webcrypto = require("node:crypto").webcrypto;
+if (globalThis.crypto === undefined) {
+    Object.assign(globalThis, { crypto: webcrypto });
+}
+
+function mocharc(format = "cjs") {
+    const { resolve } = require("path");
+    const cli = require("mocha/lib/cli/cli");
+    const listSupportFiles = require("./files.js").listSupportFiles;
+
+    const TOOLS = resolve(__dirname, "../../..");
+
+    const testJs = `build/${format}/test`;
+    const defaultSpec = `${testJs}/**/*Test.js`;
+
+    // Build.  Ideally we'd import build code but it's asynchronous so instead
+    // build in a separate process
+    const spawnSync = require("child_process").spawnSync;
+    const result = spawnSync(`${TOOLS}/bin/build.js`, [format], { stdio: "inherit" });
+    if (result.error) {
+        console.error(result.error);
+        process.exit(-1);
+    }
+
+    // Hook Mocha so we can futz with args
+    const main = cli.main;
+    cli.main = function (argv, args) {
+        const spec = args._;
+
+        // Remove wildcard test selection if there's an input file
+        if (spec.length > 1 && spec[spec.length - 1] === defaultSpec) {
+            spec.length = spec.length - 1;
+        }
+
+        // Map input files to the compiled test
+        for (let i = 0; i < spec.length; i++) {
+            let path = spec[i];
+
+            // Convenience - map src/ file to test equivalent
+            path = path.replace(/src\/(.*)(\.[jt]s)/, "test/$1Test$2");
+
+            // Map ts files to compiled equivalent
+            path = path.replace(/test\/(.*)\.ts/, `${testJs}/$1.js`);
+
+            spec[i] = path;
+        }
+
+        main.call(this, argv, args);
+    };
+
+    return {
+        inlineDiffs: true,
+        file: listSupportFiles(format),
+        spec: [defaultSpec],
+    };
+}
+
+module.exports.mocharc = mocharc;

package/src/testing/mocharc.d.cts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export function mocharc(): any;

package/src/testing/mocks/crypto.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const subtle = globalThis.crypto.subtle;
+
+/**
+ * An extremely minimal Crypto mock.
+ *
+ * Only supports those subsets of crypto required to complete matter.js tests.
+ */
+const TheCrypto = {
+    getRandomData: (length: number) => {
+        // Make random data deterministic
+        const bytes = new Uint8Array(length);
+
+        return bytes;
+    },
+
+    async pbkdf2(secret: Uint8Array, salt: Uint8Array, iteration: number, keyLength: number) {
+        const key = await subtle.importKey("raw", secret, "PBKDF2", false, ["deriveBits"]);
+        const bits = await subtle.deriveBits(
+            {
+                name: "PBKDF2",
+                hash: "SHA-256",
+                salt: salt,
+                iterations: iteration,
+            },
+            key,
+            keyLength * 8,
+        );
+        return new Uint8Array(bits);
+    },
+
+    async hkdf(secret: Uint8Array, salt: Uint8Array, info: Uint8Array, length: number = 16) {
+        const key = await subtle.importKey("raw", secret, "HKDF", false, ["deriveBits"]);
+        return new Uint8Array(
+            await subtle.deriveBits(
+                {
+                    name: "HKDF",
+                    hash: "SHA-256",
+                    salt: salt,
+                    info: info,
+                },
+                key,
+                length,
+            ),
+        );
+    },
+
+    verify() {
+        // We do not really verify anything
+        return;
+    },
+
+    mock: true,
+};
+
+export function cryptoSetup(Crypto: any) {
+    try {
+        Crypto.get();
+    } catch (e) {
+        if ((e as Error).constructor.name !== "NoProviderError") {
+            throw e;
+        }
+        Crypto.get = () => TheCrypto;
+    }
+}

package/src/testing/mocks/environment.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// TODO

package/src/testing/mocks/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import "./environment.js";
+import "./logging.js";
+export * from "./crypto.js";
+export * from "./time.js";

package/src/testing/mocks/logging.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import colors from "ansi-colors";
+
+interface LoggerLike {
+    format: string;
+    log(level: number, message: string): void;
+}
+
+export interface MockLogger {
+    emitAll: boolean;
+    injectExternalMessage: (source: string, text: string) => void;
+}
+
+export const TheMockLogger: MockLogger = {
+    emitAll: false,
+    injectExternalMessage: (source: string, text: string) => console.log(formatExternalMessage(source, text)),
+};
+
+function formatExternalMessage(source: string, text: string) {
+    return `    ${colors.bgCyan.black.bold(` ${source} `)} ${colors.dim(text)}`;
+}
+
+/**
+ * These functions are invoked by beforeEach/afterEach handlers in generalSetup for Mocha.
+ *
+ * We place them in an array here rather than calling the global hook functions so that load order doesn't matter.  We
+ * use an array so that if multiple Logger classes are created (e.g. one for CJS and one for ESM) we don't have to worry
+ * about which logger is doing the logging.
+ */
+export const LoggerHooks = {
+    beforeEach: Array<(mocha: Mocha) => void>(),
+    afterEach: Array<(mocha: Mocha) => void>(),
+};
+
+export function loggerSetup(Logger: LoggerLike) {
+    // Currently everywhere we run tests supports ANSI escape codes for
+    // colorization.  This includes:
+    //
+    // - Node console
+    // - Github actions
+    // - Headless browser -> node console
+    // - VS code/webstorm terminal
+    //
+    // Should this become a PITA we can add an option to disable
+    Logger.format = "ansi";
+
+    let messageBuffer: [number, string][] | undefined;
+
+    const defaultLog = Logger.log;
+
+    function passMessage(args: [number, string]) {
+        defaultLog.apply(Logger, args);
+    }
+
+    function interceptingLogger(...args: [number, string]) {
+        let emitAll = TheMockLogger.emitAll;
+        if (MatterHooks?.loggerSink) {
+            MatterHooks.loggerSink(...args);
+        } else if (!emitAll) {
+            if (messageBuffer) {
+                messageBuffer.push(args);
+            } else {
+                emitAll = true;
+            }
+        }
+
+        if (emitAll) {
+            passMessage(args);
+        }
+    }
+
+    TheMockLogger.injectExternalMessage = (source, text) => interceptingLogger(0, formatExternalMessage(source, text));
+
+    Logger.log = interceptingLogger;
+
+    // Divert log messages for test duration
+    LoggerHooks.beforeEach.push(function () {
+        if (!TheMockLogger.emitAll) {
+            messageBuffer = [];
+        }
+    });
+
+    // Emit log messages only if the test fails
+    LoggerHooks.afterEach.push(mocha => {
+        if (messageBuffer?.length) {
+            if (mocha.suite.ctx.currentTest?.isFailed()) {
+                for (const args of messageBuffer) {
+                    passMessage(args);
+                }
+            }
+            messageBuffer = undefined;
+        }
+    });
+}