@matter/testing 0.11.0-alpha.0-20241027-de3c9d280

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/files.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Package } from "#tools";
+import { existsSync } from "fs";
+
+export function listSupportFiles(format = "cjs") {
+    const files = Array<string>();
+
+    // Always load tooling code in ESM format as tooling globals load as ESM
+    const testing = Package.tools.findPackage("@matter/testing");
+    files.push(testing.resolve("dist/esm/global-definitions.js"));
+    files.push(testing.resolve("dist/esm/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;
+}

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 });
+}

package/src/util/trace-unhandled.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const traceUnhandled = {
+    async initialize() {
+        // We process args and environment manually so we don't need dependencies and can install as early as possible
+        if (!process.argv.includes("--trace-unhandled") && !process.env.MATTER_TRACE_UNHANDLED) {
+            return;
+        }
+
+        const { register } = await import("trace-unhandled");
+        register();
+    },
+};

package/src/util/wtf.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const wtf = {
+    async initialize() {
+        // This will only work under actual Node.js
+        if (typeof process !== "object" || process?.release?.name !== "node") {
+            return;
+        }
+
+        // We process args and environment manually so we don't need dependencies and can install wtfnode as early as
+        // possible
+        if (!process.argv.includes("--wtf") && !process.env.MATTER_WTF) {
+            return;
+        }
+
+        const { dump } = await import("wtfnode");
+        this.dump = () => dump();
+    },
+
+    dump() {},
+};

package/src/web.ts

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Package } from "#tools";
+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 { 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 = await 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/test/mocks/MockTimeTest.ts

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const FAKE_TIME = 36000000;
+
+describe("MockTime", () => {
+    beforeEach(() => MockTime.reset(FAKE_TIME));
+
+    describe("now", () => {
+        it("returns the fake date", () => {
+            const result = MockTime.now();
+
+            expect(result.getTime()).equal(FAKE_TIME);
+        });
+    });
+
+    describe("nowMs", () => {
+        it("returns the fake time", () => {
+            const result = MockTime.nowMs();
+
+            expect(result).equal(FAKE_TIME);
+        });
+    });
+
+    describe("advanceTime", () => {
+        it("advances the time by the duration specified", async () => {
+            await MockTime.advance(45);
+
+            expect(MockTime.nowMs()).equal(FAKE_TIME + 45);
+        });
+    });
+
+    describe("getPeriodicTimer", () => {
+        it("returns a periodic timer that will call a callback periodically", async () => {
+            let firedTime;
+
+            const result = MockTime.getPeriodicTimer("Test periodic", 30, () => (firedTime = MockTime.nowMs()));
+            expect(result.isRunning).equal(false);
+
+            result.start();
+
+            expect(result.isRunning).equal(true);
+            expect(firedTime).equal(undefined);
+
+            await MockTime.advance(45);
+
+            expect(firedTime).equal(FAKE_TIME + 30);
+
+            await MockTime.advance(20);
+
+            expect(firedTime).equal(FAKE_TIME + 60);
+
+            expect(result.isRunning).equal(true);
+
+            result.stop();
+            expect(result.isRunning).equal(false);
+        });
+
+        it("returns a periodic timer that can be stopped", async () => {
+            let firedTime;
+
+            const result = MockTime.getPeriodicTimer("Test periodic", 30, () => (firedTime = MockTime.nowMs()));
+            result.start();
+            result.stop();
+
+            expect(firedTime).equal(undefined);
+
+            await MockTime.advance(45);
+
+            expect(firedTime).equal(undefined);
+            expect(result.isRunning).equal(false);
+        });
+    });
+
+    describe("getTimer", () => {
+        it("returns a timer that will call a callback in the future", async () => {
+            let firedTime;
+
+            const result = MockTime.getTimer("Test", 30, () => (firedTime = MockTime.nowMs()));
+            expect(result.isRunning).equal(false);
+            result.start();
+            expect(result.isRunning).equal(true);
+
+            expect(firedTime).equal(undefined);
+
+            await MockTime.advance(45);
+
+            expect(firedTime).equal(FAKE_TIME + 30);
+            expect(result.isRunning).equal(false);
+        });
+
+        it("returns a timer that can be stopped", async () => {
+            let firedTime;
+
+            const result = MockTime.getTimer("Test", 30, () => (firedTime = MockTime.nowMs()));
+            expect(result.isRunning).equal(false);
+            result.start();
+            expect(result.isRunning).equal(true);
+            result.stop();
+            expect(result.isRunning).equal(false);
+
+            expect(firedTime).equal(undefined);
+
+            await MockTime.advance(45);
+
+            expect(firedTime).equal(undefined);
+            expect(result.isRunning).equal(false);
+        });
+    });
+});

package/test/tsconfig.json

@@ -0,0 +1,18 @@
+{
+    "extends": "../../tools/tsc/tsconfig.test.json",
+    "compilerOptions": {
+        "types": [
+            "node",
+            "mocha",
+            "@matter/testing"
+        ]
+    },
+    "references": [
+        {
+            "path": "../../tools/src"
+        },
+        {
+            "path": "../src"
+        }
+    ]
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+    "compilerOptions": { "composite": true },
+    "files": [],
+    "references": [{ "path": "src" }, { "path": "test" }]
+}