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

package/src/testing/web.ts

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { build } from "esbuild";
+import express from "express";
+import { writeFile } from "fs/promises";
+import http from "http";
+import { AddressInfo } from "net";
+import { relative } from "path";
+import { Browser, chromium, ConsoleMessage, Page } from "playwright";
+import { Package } from "../util/package.js";
+import { TestOptions } from "./options.js";
+import { ConsoleProxyReporter, Reporter } from "./reporter.js";
+import type { TestRunner } from "./runner.js";
+
+export async function testWeb(runner: TestRunner, manual: boolean) {
+    const files = runner.loadFiles("esm");
+    const bundlePath = await bundle(files, runner.pkg);
+
+    const server = await new Promise<http.Server>((resolve, reject) => {
+        try {
+            const server = express()
+                .use(express.static(Package.workspace.resolve("node_modules")))
+                .use(express.static(Package.workspace.path))
+                .get("/", (_, res) => res.send(buildIndex(bundlePath)))
+                .listen(0, "localhost", () => resolve(server));
+        } catch (e) {
+            reject(e);
+        }
+    });
+
+    const addr = server.address() as AddressInfo;
+    let ip = addr.address;
+    if (ip.indexOf(":") !== -1) {
+        ip = `[${ip}]`;
+    }
+    const url = `http://${ip}:${addr.port}/`;
+
+    await new Promise<void>((resolve, reject) => {
+        server.on("error", reject);
+        server.on("close", resolve);
+
+        if (manual) {
+            console.log(`Run tests manually at ${url}`);
+        } else {
+            testInBrowser(url, runner.reporter, runner.options)
+                .then(() => {
+                    server.close(() => {
+                        // Hmm the close event above doesn't fire
+                        resolve();
+                    });
+                })
+                .catch(error => {
+                    reject(error);
+                });
+        }
+    });
+}
+
+async function testInBrowser(url: string, reporter: Reporter, options: TestOptions) {
+    async function setup() {
+        const browser = await chromium.launch();
+        const page = await browser.newPage();
+        return { browser, page };
+    }
+
+    async function run({ browser, page }: { browser: Browser; page: Page }) {
+        await page.goto(url);
+        await page.evaluate(options => (globalThis as any).MatterTest.auto(options), options);
+        await browser.close();
+    }
+
+    await new Promise<void>((resolve, reject) => {
+        setup()
+            .then(cx => {
+                cx.page.on("console", consoleHandler(reporter));
+                cx.page.on("pageerror", error => reject(error));
+                return cx;
+            })
+            .then(run)
+            .then(resolve)
+            .catch(reject);
+    });
+}
+
+function consoleHandler(reporter: Reporter) {
+    return (message: ConsoleMessage) => {
+        const type = message.type();
+        switch (type) {
+            case "log":
+            case "debug":
+            case "info":
+            case "error":
+            case "warn":
+            case "trace":
+                break;
+
+            default:
+                return;
+        }
+
+        const text = message.text();
+
+        // If it's not an encoded reporter update, write to normal console
+        if (type !== "log" || !text.startsWith(ConsoleProxyReporter.FLAG)) {
+            console[type](text);
+            return;
+        }
+
+        // Invoke reporter
+        const args: string[] = JSON.parse(text.slice(ConsoleProxyReporter.FLAG.length));
+        const method = (reporter as any)[args[0]];
+        if (typeof method !== "function") {
+            throw new Error(`Invalid encoded reporter update method ${args[0]}`);
+        }
+        method.call(reporter, ...args.slice(1));
+    };
+}
+
+function buildIndex(bundlePath: string) {
+    return `<!DOCTYPE html>
+<html>
+<head>
+    <title>Matter.js Web Testing</title>
+    <link rel="stylesheet" href="mocha/mocha.css">
+</head>
+<body>
+    <div id="mocha"><h1><a href="javascript:MatterTest.start()">run tests</a></h1></div>
+    <script src="mocha/mocha.js"></script>
+    <script src="${bundlePath}" type="module"></script>
+</body>
+</html>`;
+}
+
+async function bundle(files: string[], pkg: Package) {
+    const entrypointPath = pkg.resolve("build/esm/test-entrypoint.js");
+    const bundlePath = pkg.resolve("build/cjs/test-bundle.js");
+
+    const entrypoint = files
+        .map(path => {
+            path = relative(pkg.resolve("build/esm"), path).replace(/\\/g, "/");
+            if (!path.startsWith(".")) {
+                path = `./${path}`;
+            }
+            return `import ${JSON.stringify(path)}`;
+        })
+        .join("\n");
+
+    // I was unable to get esbuild to resolve the entrypoint using the "stdin" and "absWorkingDir" options.  So we just
+    // write to disk
+    await writeFile(pkg.resolve("build/esm/test-entrypoint.js"), entrypoint);
+
+    await build({
+        entryPoints: [entrypointPath],
+        bundle: true,
+        format: "cjs",
+        outfile: bundlePath,
+        external: ["wtfnode"],
+        keepNames: true,
+
+        // This doesn't work...
+        // logOverride: {
+        //     "direct-eval": "silent",
+        // },
+
+        // ...so we do this:
+        logLevel: "error",
+    });
+
+    return pkg.workspace.relative(bundlePath);
+}

package/src/tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "extends": "../tsc/tsconfig.lib.json",
+    "compilerOptions": {
+        "types": [
+            "node"
+        ]
+    },
+    "include": [
+        "**/*.ts",
+        "testing/mocharc.cjs",
+        "util/tools-path.d.cts"
+    ],
+    "references": []
+}

package/src/util/bootstrap.mjs

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Bootstrap tooling code.  Libraries are unavailable here; we may only use 3rd party modules.
+//
+// Also do not use TS as it would require the code invoking bootstrap to do a meta-bootstrap. 🙄
+
+import { spawn } from "child_process";
+import { cp, stat } from "fs/promises";
+import { platform } from "os";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+function fatal(why, error) {
+    console.error(`Cannot bootstrap matter.js tooling because ${why}.`);
+    if (error) {
+        console.error(error);
+    }
+    process.exit(1);
+}
+
+async function findFile(name) {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const path = resolve(dir, name);
+        try {
+            await stat(path);
+            return path;
+        } catch (e) {
+            if (e.code !== "ENOENT") {
+                fatal("there was an unexpected error searching the filesystem", e);
+            }
+        }
+
+        const nextDir = dirname(dir);
+        if (nextDir === dir) {
+            break;
+        }
+
+        dir = nextDir;
+    }
+}
+
+async function bootstrap() {
+    try {
+        const pkg = await findFile("package.json");
+        if (pkg === undefined) {
+            fatal("the bootstrap script does not appear to be installed in a package");
+        }
+
+        const path = dirname(pkg);
+
+        const options = {
+            stdio: "inherit",
+            cwd: path,
+        };
+
+        if (platform() === "win32") {
+            options.shell = true;
+        }
+
+        let esbuild = await findFile("node_modules/.bin/esbuild");
+        if (esbuild === undefined) {
+            // As a last resort, attempt to rely on the system PATH
+            esbuild = "esbuild";
+        }
+
+        await new Promise(resolve => {
+            const proc = spawn(
+                esbuild,
+                ["src/**/*.ts", "--outdir=dist/esm", "--format=esm", "--log-level=warning", "--sourcemap=inline"],
+                options,
+            );
+
+            proc.on("error", e => {
+                if (e.code === "ENOENT") {
+                    fatal(
+                        'esbuild is not found.\nYou probably need to run "npm install" in the root of the repository',
+                    );
+                }
+                fatal("an unexpected error occurred running esbuild", e);
+            });
+
+            proc.on("close", code => {
+                if (code === 0) {
+                    resolve();
+                } else {
+                    fatal(`esbuild existing with code ${code}`);
+                }
+            });
+        });
+
+        await cp(resolve(path, "src/util/tools-path.cjs"), resolve(path, "dist/esm/util/tools-path.cjs"));
+    } catch (e) {
+        fatal("an unexpected error occurred", e);
+    }
+}
+
+// If installed then we assume we're compiled and boostrap is a no-op
+if (!import.meta.url.match(/[\\/]node_modules[\\/]/)) {
+    await bootstrap();
+}

package/src/util/docker.ts

@@ -0,0 +1,176 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { readdir } from "fs/promises";
+import { Writable } from "stream";
+
+import Dockerode from "dockerode";
+
+/**
+ * A high-level docker control API specialized for our purposes.
+ */
+export class Docker {
+    #intf = new Dockerode();
+
+    async *run(imageName: string, options?: Docker.RunOptions) {
+        const { args, createOptions } = configureRun(options);
+
+        let resolve: undefined | ((text?: string) => void);
+        let reject: undefined | ((error: Error) => void);
+        let signal: undefined | Promise<string | undefined>;
+
+        function newSignal() {
+            signal = new Promise((newResolve, newReject) => {
+                resolve = text => {
+                    newResolve(text);
+                    newSignal();
+                };
+                reject = newReject;
+            });
+        }
+
+        newSignal();
+
+        const output = new Writable();
+        output._write = (chunk, _encoding, done) => {
+            resolve!(chunk.toString("utf-8"));
+            newSignal();
+            done();
+        };
+
+        this.#intf.run(imageName, args, output, createOptions).then(
+            result => {
+                const statusCode = result?.[0]?.StatusCode;
+                if (typeof statusCode !== "number") {
+                    throw new Error(`Process exit status "${statusCode}" is non-numeric`);
+                }
+                if (statusCode === 0) {
+                    resolve!(undefined);
+                } else {
+                    reject!(new Error(`Process exited with error status "${statusCode}"`));
+                }
+            },
+            error => reject!(error),
+        );
+
+        while (true) {
+            const value = await signal;
+            if (value === undefined) {
+                break;
+            }
+            yield value;
+        }
+    }
+
+    async readFileFromImage(imageName: string, pathInImage: string) {
+        const output = Array<string>();
+
+        for await (const chunk of this.run(imageName, {
+            entrypoint: "/usr/bin/cat",
+            args: [pathInImage],
+        })) {
+            output.push(chunk);
+        }
+
+        return output.join("").replace(/\r\n/g, "\n");
+    }
+
+    async resolveGlobFromImage(imageName: string, glob: string) {
+        const output = Array<string>();
+
+        for await (const chunk of this.run(imageName, {
+            entrypoint: ["/bin/bash", "-c"],
+            args: `ls ${glob}`,
+        })) {
+            output.push(chunk);
+        }
+
+        return output
+            .join("")
+            .split(/\r?\n/)
+            .filter(line => line !== "");
+    }
+
+    async buildImage(name: string, path: string) {
+        const files = await readdir(path);
+
+        const stream = await this.#intf.buildImage(
+            {
+                context: path,
+                src: files,
+            },
+            {
+                t: name,
+            },
+        );
+
+        await new Promise<void>((resolve, reject) => {
+            this.#intf.modem.followProgress(stream, (error, result) => {
+                if (error) {
+                    reject(error);
+                }
+
+                const finalMessage = result[result.length - 1];
+                const errorMessage = finalMessage?.error ?? finalMessage?.errorDetail?.message;
+                if (errorMessage) {
+                    reject(new Error(errorMessage));
+                }
+
+                resolve();
+            });
+        });
+    }
+}
+
+namespace Docker {
+    export interface RunOptions {
+        entrypoint?: string | string[];
+        args?: string | string[];
+        env?: Record<string, string>;
+        privileged?: boolean;
+        binds?: Record<string, string>;
+        network?: "host";
+    }
+}
+
+function configureRun(options?: Docker.RunOptions) {
+    if (options === undefined) {
+        options = {};
+    }
+
+    let { args } = options;
+    if (args === undefined) {
+        args = [];
+    } else if (typeof args === "string") {
+        args = [args];
+    }
+
+    const createOptions = {
+        HostConfig: {
+            AutoRemove: true,
+        },
+    } as Dockerode.ContainerCreateOptions;
+
+    const { entrypoint, env, binds, network } = options ?? {};
+
+    if (entrypoint !== undefined) {
+        createOptions.Entrypoint = entrypoint;
+    }
+
+    if (env) {
+        createOptions.Env = Object.entries(env).map(([k, v]) => `${k}=${v}`);
+    }
+
+    if (binds) {
+        createOptions.HostConfig!.Binds = Object.entries(binds).map(([k, v]) => `${k}:${v}`);
+    }
+
+    if (network) {
+        createOptions.HostConfig!.NetworkMode = network;
+    }
+
+    return { args, createOptions };
+}

package/src/util/errors.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function notCode(code: string | string[], cause: any) {
+    const causeCode = cause?.code;
+    if (typeof code === "string") {
+        return code !== causeCode;
+    }
+    return !code.includes(causeCode);
+}
+
+export async function ignoreError<T>(code: string | string[], fn: () => Promise<T>): Promise<T | undefined> {
+    try {
+        return await fn();
+    } catch (e) {
+        if (notCode(code, e)) {
+            throw e;
+        }
+    }
+}
+
+export function ignoreErrorSync<T>(code: string | string[], fn: () => T): T | undefined {
+    try {
+        return fn();
+    } catch (e) {
+        if (notCode(code, e)) {
+            throw e;
+        }
+    }
+}

package/src/util/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./errors.js";
+export * from "./package.js";

package/src/util/node-shims.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import "mocha";
+import { webcrypto } from "node:crypto";
+
+// Required for Node < 19
+if (globalThis.crypto === undefined) {
+    Object.assign(globalThis, { crypto: webcrypto });
+}