Merge pull request #57 from ClearCalcs/add-static-diagram-tester

Add static diagram tester

Author: michaellisitsa

.gitignore

@@ -6,4 +6,7 @@ output/
 .DS_Store
 *.log
 package-lock.json
-yarn.lock
+yarn.lock
+
+# Test files
+test/out/

Dockerfile

@@ -0,0 +1,17 @@
+FROM ubuntu:24.04
+
+ARG FUNCTION_DIR="/var/task"
+WORKDIR ${FUNCTION_DIR}
+RUN mkdir -p ${FUNCTION_DIR}
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && \
+    # NodeJS
+    apt-get install -y wget curl && \
+    (curl -fsSL https://deb.nodesource.com/setup_18.x | bash) && \
+    apt-get install -y nodejs
+
+COPY ./test ${FUNCTION_DIR}
+RUN npm install
+COPY ./output ${FUNCTION_DIR}/output

docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+    render:
+        build:
+            context: .
+        command: node -e 'import("./test.js").then(m => m.render())'
+        volumes:
+            - ./test/out:/var/task/out
+
+    params:
+        build:
+            context: .
+        command: node -e 'import("./test.js").then(m => m.params())'
+        volumes:
+            - ./test/out:/var/task/out

docs/_sidebar.md

@@ -9,8 +9,10 @@
     -   [Core](/interactive-diagram-core "Understand the underlying technology and API for rendering the interactive diagrams")
     -   [Rendering](/interactive-diagram-rendering "How interactive diagrams are rendered in the sheet")
     -   [Best Practices](/interactive-diagram-best-practices "Best Practices for using interactive diagram")
-    -   [Using Test Runner](/interactive-diagram-test-runner "How to use the test runner")
 -   Global
     -   [Global Capabilities](/global-capabilities "Time saving features")
+-   Testing
+    -   [Interactive](/interactive-diagram-test-runner "How to use the test runner")
+    -   [Static](/static-diagram-test-runner "How to use the test runner")
 -   Contributing
     -   [Add To Docs](/contributing-to-docs "How to contribute to docs")

docs/static-diagram-test-runner.md

@@ -0,0 +1,47 @@
+# Using Test Runner
+
+## Introduction
+
+The Test Runner allows visualisation of the custom static diagram and how it responds to each function that is user implemented such as `render`, `params`. It enables quick, iterative development of the custom diagram in an environment that mimics the ClearCalcs app for maximum compatibility when it is deployed in a real calculator.
+
+It allows this compatibility by running the diagram code within a fake Dockerfile that has the same capabilities and restrictions. The following diagram functionality may be tested:
+
+### Supported Features
+
+-   renders SVG with parameters
+-   returns params
+
+## Set up
+
+1. Install Docker https://www.docker.com/get-started/
+
+2. [Optional] Add params to `test/test.js`
+
+```javascript
+const inputParams = {
+    circleFill: "red",
+    rectFill: "blue",
+};
+const storedParams = {...}
+```
+
+3. Run Test Render and view output
+
+```bash
+npm run test-render
+cd test/out
+# Open diagram.svg
+```
+
+4. Run Test Params and view output
+
+```bash
+npm run test-params
+# stdout
+Params [
+  { key: 'circleFill', type: 'string' },
+  { key: 'rectFill', type: 'string' },
+  { key: 'triangleFill', type: 'string' }
+]
+# Or go to test/out/params.json
+```

package.json

@@ -32,7 +32,9 @@
         "docs": "cd docs && npm install && docsify serve -p 4444",
         "compile-static": "node static-build.js",
         "compile-static-fonts": "node svgdomPatches/scripts/compileFont.js",
-        "compile-interactive-example": "EXAMPLE_PATH=examples/${EXAMPLE}/interactive/interface.ts parcel build examples/${EXAMPLE}/interactive/**/index.html"
+        "compile-interactive-example": "EXAMPLE_PATH=examples/${EXAMPLE}/interactive/interface.ts parcel build examples/${EXAMPLE}/interactive/**/index.html",
+        "test-render": "npm run compile-static && docker compose build && docker compose up render",
+        "test-params": "npm run compile-static && docker compose build && docker compose up params"
     },
     "type": "module"
 }

test/index.js

@@ -0,0 +1,61 @@
+import { runInSandbox, UserError } from "./sandbox.js";
+import * as fs from "fs";
+
+export const params = withErrorHandling(async () => {
+    const userCode = fs.readFileSync("output/compiled.js", {
+        encoding: "utf8",
+        flag: "r",
+    });
+
+    return runInSandbox({
+        userCode,
+        resultCode: "return params()",
+        params: [],
+    });
+});
+
+export const render = withErrorHandling(async ({ params }) => {
+    const userCode = fs.readFileSync("output/compiled.js", {
+        encoding: "utf8",
+        flag: "r",
+    });
+    let storedParams, inParams;
+    try {
+        ({ storedParams, ...inParams } = params);
+    } catch (e) {
+        // User has called render with no params or not with an object
+        // We will pass down the original params and handle error in user code
+    }
+
+    return runInSandbox({
+        userCode,
+        resultCode: "return render($0,$1)",
+        params: inParams ? [inParams, storedParams] : [params, {}],
+    });
+});
+
+// Wrap result in object with {success: false/true}
+function withErrorHandling(fn) {
+    return async (...args) => {
+        try {
+            const result = await fn(...args);
+
+            return {
+                success: true,
+                result,
+            };
+        } catch (ex) {
+            if (ex instanceof UserError) {
+                return {
+                    success: false,
+                    error: {
+                        message: ex.message,
+                        stack: ex.userStack,
+                    },
+                };
+            } else {
+                throw ex;
+            }
+        }
+    };
+}

test/out/README.md

@@ -0,0 +1 @@
+Example render and params will be outputted here

test/package.json

@@ -0,0 +1,12 @@
+{
+    "name": "custom_diagram",
+    "version": "1.0.0",
+    "description": "",
+    "main": "index.js",
+    "author": "",
+    "license": "UNLICENSED",
+    "dependencies": {
+        "isolated-vm": "^5.0.3"
+    },
+    "type": "module"
+}

test/sandbox.js

@@ -0,0 +1,48 @@
+import pkg from "isolated-vm";
+const { Isolate } = pkg;
+
+const MEMORY_LIMIT_MB = 256;
+// Current svgdom bundle is large and slow, so we need to give it more time to solve
+// TODO: Reduce once performance improved
+const TIMEOUT_MS = 2000;
+
+export class UserError extends Error {
+    userStack = [];
+}
+
+export function runInSandbox({ userCode, resultCode, params }) {
+    const isolate = new Isolate({ memoryLimit: MEMORY_LIMIT_MB });
+    const context = isolate.createContextSync();
+    const jail = context.global;
+    jail.setSync("global", jail.derefInto());
+    // Example of exposing a custom function on the context's global:
+    /*
+    jail.setSync("log", function (...args) {
+        console.log(...args);
+    });
+    */
+
+    // Evaluate untrusted user code in isolated context
+    try {
+        context.evalSync(userCode, {
+            timeout: TIMEOUT_MS,
+            filename: "user.js",
+        });
+
+        return context.evalClosureSync(resultCode, params, {
+            timeout: TIMEOUT_MS,
+            arguments: { copy: true },
+            result: { copy: true },
+        });
+    } catch (ex) {
+        throw handleUserError(ex);
+    }
+}
+
+function handleUserError(ex) {
+    const userError = new UserError(`${ex.name}: ${ex.message}`);
+    if (ex.stack) {
+        userError.userStack = ex.stack.split("\n").filter((line) => line.match(/^    at .*user\.js/));
+    }
+    return userError;
+}

test/test.js

@@ -0,0 +1,37 @@
+import { writeFile } from "node:fs/promises";
+import { render as renderInternal, params as paramsInternal } from "./index.js";
+
+// EDIT YOUR PARAMS HERE
+const inputParams = {};
+
+// EDIT YOUR STORED PARAMS HERE
+const storedParams = {};
+
+export async function render() {
+    const response = await renderInternal({
+        params: { ...inputParams, storedParams },
+    });
+
+    if (!response.success || !response.result) {
+        // TODO: We do send back errors into the browser
+        // Look at what the index.js returns and you can capture these
+        console.log(response?.error?.message);
+        throw new Error(`Failed to render`);
+    }
+
+    await writeFile("out/diagram.svg", response.result);
+    console.log("Successfully written svg");
+}
+
+export async function params() {
+    const response = await paramsInternal();
+
+    if (!response.success || !response.result) {
+        // TODO: We do send back errors into the browser
+        // Look at what the index.js returns and you can capture these
+        throw new Error("Failed to render");
+    }
+
+    await writeFile("out/params.json", JSON.stringify(response.result));
+    console.log("Params", response.result);
+}