feat: [deno-web-test] Add docs, meta-tests, and an ability to propagate console messages (#506)

jsantell · web-flow · commit 3ea707e73a4b · 2025-03-04T11:31:56.000-08:00
diff --git a/typescript/packages/common-identity/deno-web-test.config.ts b/typescript/packages/common-identity/deno-web-test.config.ts
@@ -1,8 +1,5 @@
 const ED25519_FLAG = "--enable-experimental-web-platform-features";
 export default {
-  astral: {
-    product: "chrome",
-    args: [ED25519_FLAG],
-    headless: true,
-  }
+  product: "chrome",
+  args: [ED25519_FLAG],
 };
diff --git a/typescript/packages/deno-web-test/README.md b/typescript/packages/deno-web-test/README.md
@@ -0,0 +1,56 @@
+# deno-web-test
+
+`deno-web-test` is a test runner for running Deno tests in a browser. This is
+used in code compatible with both Deno and browsers in order to test browser
+functionality.
+
+## Usage
+
+Write a test using `Deno.test`:
+
+```ts
+// add.test.ts
+import { assert } from "@std/assert";
+
+Deno.test("add", function () {
+  assert((5 + 5) === 10, "math checks out");
+});
+```
+
+Optionally add a `deno-web-test.config.ts` to the project root to configure the
+runner. See [config.ts](/typescript/packages/deno-web-test/config.ts) for all
+options.
+
+```ts
+export default {
+  headless: true,
+  devtools: false,
+  product: "chrome",
+  args: ["--enable-experimental-web-platform-features"],
+  pipeConsole: true,
+};
+```
+
+Finally, run `deno-web-test/cli.ts`, which takes a glob of files to test.
+
+```json
+{
+  "tasks": {
+    "test": "deno run -A deno-web-test/cli.ts *.test.ts"
+  }
+}
+```
+
+## Support
+
+Currently only the `Deno.test(string, fn)` signature works. Using other
+signatures, or the BDD framework in `@std/testing/bdd` is not yet supported.
+
+## Testing
+
+For testing `deno-web-test` itself, the test suites (running in Deno itself) run
+`deno-web-test` for subprojects to test features. Due to being in a workspace,
+and not wanting to clutter the workspace with these test directories, and Deno
+attempting to enforce this, the test packages are moved to a temporary directory
+and the test task rewritten to target the local `cli.ts` export. This could be
+relaxed if moved outside of the workspace.
diff --git a/typescript/packages/deno-web-test/browser.ts b/typescript/packages/deno-web-test/browser.ts
@@ -1,14 +1,16 @@
-import { Browser, launch, Page } from "jsr:@astral/astral";
+import { Browser, ConsoleEvent, launch, Page } from "jsr:@astral/astral";
 import { Manifest } from "./manifest.ts";
 import { tsToJs, wait } from "./utils.ts";
 import { TestResult } from "./interface.ts";
+import { extractAstralConfig } from "./config.ts";
 
-export class BrowserController {
+export class BrowserController extends EventTarget {
   private manifest: Manifest;
   private page: Page | null;
   private browser: Browser | null;
 
   constructor(manifest: Manifest) {
+    super();
     this.manifest = manifest;
     this.browser = null;
     this.page = null;
@@ -23,8 +25,18 @@ export class BrowserController {
     if (this.page) {
       await this.page.goto(testUrl);
     } else {
-      this.browser = await launch(config.astral ?? {});
+      this.browser = await launch(extractAstralConfig(config));
       this.page = await this.browser.newPage(testUrl);
+      this.page.addEventListener("console", (e) => {
+        // Not sure why this event needs reconstructed in order
+        // to re-fire, rather than just passing it into `dispatchEvent`.
+        this.dispatchEvent(
+          new ConsoleEvent({
+            type: e.detail.type,
+            text: e.detail.text,
+          }),
+        );
+      });
     }
     await this.waitUntilReady();
   }
diff --git a/typescript/packages/deno-web-test/cli.ts b/typescript/packages/deno-web-test/cli.ts
@@ -9,7 +9,7 @@ const manifest = await Manifest.create(Deno.cwd(), [...Deno.args]);
 await buildTestDir(manifest);
 
 const server = new TestServer(manifest);
-await server.start(manifest.port);
+server.start(manifest.port);
 
 const runner = new Runner(manifest);
 const success = await runner.run();
diff --git a/typescript/packages/deno-web-test/config.ts b/typescript/packages/deno-web-test/config.ts
@@ -0,0 +1,50 @@
+import { LaunchOptions } from "@astral/astral";
+import * as path from "@std/path";
+import { exists } from "@std/fs/exists";
+
+// These configurations can be applied
+// by placing a `deno-web-test.config.ts` in package root.
+export type Config = {
+  // Whether the test runner should run headlessly. Default: true.
+  headless?: boolean;
+  // Whether devtools should be enabled. Default: false.
+  devtools?: boolean;
+  // What browser to run.
+  product?: "chrome" | "firefox";
+  // Arguments to be passed into the browser.
+  args?: string[];
+  // Whether or not console commands should be propagated to the deno-web-test process.
+  pipeConsole?: boolean;
+};
+
+export const applyDefaults = (config: object): Config => {
+  return Object.assign({
+    headless: true,
+    devtools: false,
+  }, config);
+};
+
+export const extractAstralConfig = (config: Config): LaunchOptions => {
+  const astralConfig = {};
+  for (const prop of ["headless", "devtools", "product", "args"]) {
+    if (prop in config) {
+      astralConfig[prop] = config[prop];
+    }
+  }
+  return astralConfig;
+};
+
+export const getConfig = async (projectDir: string): Promise<Config> => {
+  const configPath = path.join(projectDir, "deno-web-test.config.ts");
+
+  if (await exists(configPath, { isFile: true })) {
+    // Try to evaluate it
+    try {
+      const config = (await import(configPath)).default;
+      return applyDefaults(config);
+    } catch (e) {
+      console.error(`Unable to execute deno-web-test.config.ts`);
+    }
+  }
+  return applyDefaults({});
+};
diff --git a/typescript/packages/deno-web-test/deno.json b/typescript/packages/deno-web-test/deno.json
@@ -1,7 +1,7 @@
 {
   "name": "@commontools/deno-web-test",
   "tasks": {
-    "test": "deno run --allow-env --allow-read --allow-write --allow-run --allow-net ./cli.ts test/*.test.ts"
+    "test": "deno test --allow-env --allow-read --allow-write --allow-run --allow-net test/*.test.ts"
   },
   "exports": {
     ".": "./mod.ts",
diff --git a/typescript/packages/deno-web-test/manifest.ts b/typescript/packages/deno-web-test/manifest.ts
@@ -1,5 +1,5 @@
 import * as path from "@std/path";
-import { Config } from "./interface.ts";
+import { Config, getConfig } from "./config.ts";
 import { exists } from "@std/fs/exists";
 
 export class Manifest {
@@ -30,22 +30,7 @@ export class Manifest {
 
   static async create(projectDir: string, tests: string[]): Promise<Manifest> {
     const serverDir = await Deno.makeTempDir();
-    const config = await Manifest.getConfig(projectDir);
+    const config = await getConfig(projectDir);
     return new Manifest(projectDir, tests, serverDir, config);
   }
-
-  static async getConfig(projectDir: string): Promise<Config> {
-    const configPath = path.join(projectDir, "deno-web-test.config.ts");
-    
-    if (await exists(configPath, { isFile: true })) {
-      // Try to evaluate it
-      try {
-        const config = (await import(configPath)).default;
-        return config as Config;
-      } catch (e) {
-        console.error(`Unable to execute deno-web-test.config.ts`);
-      }
-    }
-    return {} as Config;
-  }
 }
diff --git a/typescript/packages/deno-web-test/runner.ts b/typescript/packages/deno-web-test/runner.ts
@@ -13,8 +13,9 @@ export class Runner {
   constructor(manifest: Manifest) {
     this.manifest = manifest;
     this.reporter = new Reporter();
-    this.browser = new BrowserController(manifest);
     this.results = [];
+    this.browser = new BrowserController(manifest);
+    this.browser.addEventListener("console", (e) => this.onConsole(e));
   }
 
   // Runs all tests in the browser. Return value
@@ -57,4 +58,20 @@ export class Runner {
     await this.browser.close();
     return summary.failed.length === 0;
   }
+
+  onConsole(e: ConsoleEvent) {
+    if (this.manifest.config.pipeConsole) {
+      switch (e.detail.type) {
+        case "log":
+          console.log(`deno-web-test: ${e.detail.text}`);
+          break;
+        case "warn":
+          console.warn(`deno-web-test: ${e.detail.text}`);
+          break;
+        case "error":
+          console.error(`deno-web-test: ${e.detail.text}`);
+          break;
+      }
+    }
+  }
 }
diff --git a/typescript/packages/deno-web-test/server.ts b/typescript/packages/deno-web-test/server.ts
@@ -13,9 +13,9 @@ export class TestServer {
     this.manifest = manifest;
   }
 
-  async start(port: number) {
+  start(port: number) {
     this.server = Deno.serve(
-      { port, hostname: "127.0.0.1" },
+      { port, hostname: "127.0.0.1", onListen({ path }) {} },
       (req: Request) =>
         serveDir(req, {
           fsRoot: this.manifest.serverDir,
diff --git a/typescript/packages/deno-web-test/test/base.test.ts b/typescript/packages/deno-web-test/test/base.test.ts
@@ -1,5 +1,18 @@
 import { assert } from "@std/assert";
+import { decode, runDenoWebTest } from "./utils.ts";
 
-Deno.test("Base test", async function () {
-  assert(true, "This should be true");
+const dirname = import.meta.dirname as string;
+
+Deno.test("smoke test", async function () {
+  const { success, stdout, stderr } = await runDenoWebTest("success-project");
+  const stdoutText = decode(stdout);
+  const stderrText = decode(stderr);
+
+  assert(success, "test successful");
+  assert(/add-sync ... ok/.test(stdoutText), "test output ok");
+  assert(/add-async ... ok/.test(stdoutText), "test output ok");
+  assert(/ok | 2 passed | 0 failed/.test(stdoutText), "test output ok");
+  assert(/deno run/.test(stderrText), "stderr has deno task run");
+  assert(stderrText.split("\n").length === 2, "stderr has no other messages");
+  assert(stderrText.split("\n")[1] === "", "stderr has no other messages");
 });
diff --git a/typescript/packages/deno-web-test/test/bdd.t_e_s_t.ts b/typescript/packages/deno-web-test/test/bdd.t_e_s_t.ts
diff --git a/typescript/packages/deno-web-test/test/config.test.ts b/typescript/packages/deno-web-test/test/config.test.ts
@@ -0,0 +1,19 @@
+import { assert } from "@std/assert";
+import { decode, runDenoWebTest } from "./utils.ts";
+
+const dirname = import.meta.dirname as string;
+
+Deno.test("config is applied", async function () {
+  const { success, stdout, stderr } = await runDenoWebTest(
+    "project-with-config",
+  );
+  const stdoutText = decode(stdout);
+  const stderrText = decode(stderr);
+
+  assert(success, "test successfully ran, applying chrome flags");
+  assert(/LOG FROM TEST/.test(stdoutText), "console output propagated");
+
+  assert(/deno run/.test(stderrText), "stderr has deno task run");
+  assert(stderrText.split("\n").length === 2, "stderr has no other messages");
+  assert(stderrText.split("\n")[1] === "", "stderr has no other messages");
+});
diff --git a/typescript/packages/deno-web-test/test/project-with-config/deno-web-test.config.ts b/typescript/packages/deno-web-test/test/project-with-config/deno-web-test.config.ts
@@ -0,0 +1,6 @@
+const ED25519_FLAG = "--enable-experimental-web-platform-features";
+export default {
+  product: "chrome",
+  args: [ED25519_FLAG],
+  pipeConsole: true,
+};
diff --git a/typescript/packages/deno-web-test/test/project-with-config/deno.json b/typescript/packages/deno-web-test/test/project-with-config/deno.json
@@ -0,0 +1,9 @@
+{
+  "name": "deno-web-test-project-with-config",
+  "tasks": {
+    "test": "<@see deno-web-test/test/utils.ts#runDenoWebTest>"
+  },
+  "exports": {
+    ".": "./mod.ts"
+  }
+}
diff --git a/typescript/packages/deno-web-test/test/project-with-config/ed25519.test.ts b/typescript/packages/deno-web-test/test/project-with-config/ed25519.test.ts
@@ -0,0 +1,11 @@
+import { createEd25519Key } from "./mod.ts";
+
+Deno.test("create ed25519 key", async function () {
+  // We test that console log is propagated to test runner,
+  // so this console log is load bearing.
+  console.log("LOG FROM TEST");
+
+  // This will fail in Chrome unless experimental web feature
+  // flag was set.
+  await createEd25519Key();
+});
diff --git a/typescript/packages/deno-web-test/test/project-with-config/mod.ts b/typescript/packages/deno-web-test/test/project-with-config/mod.ts
@@ -0,0 +1,11 @@
+export const createEd25519Key = async (): CryptoKey => {
+  const dummyKey = new Uint8Array(32);
+
+  return await globalThis.crypto.subtle.importKey(
+    "raw",
+    dummyKey,
+    "ed25519",
+    false,
+    ["verify"],
+  );
+};
diff --git a/typescript/packages/deno-web-test/test/success-project/add.test.ts b/typescript/packages/deno-web-test/test/success-project/add.test.ts
@@ -0,0 +1,11 @@
+import { add } from "./mod.ts";
+import { assert } from "@std/assert";
+
+Deno.test("add-sync", function () {
+  assert(add(5, 10) === 15, "add(5, 10) should equal 15");
+});
+
+Deno.test("add-async", async function () {
+  await Promise.resolve();
+  assert(add(1, 2) === 3, "add(1, 2) should equal 3");
+});
diff --git a/typescript/packages/deno-web-test/test/success-project/add.ts b/typescript/packages/deno-web-test/test/success-project/add.ts
@@ -0,0 +1 @@
+export const add = (a: number, b: number): number => a + b;
diff --git a/typescript/packages/deno-web-test/test/success-project/deno.json b/typescript/packages/deno-web-test/test/success-project/deno.json
@@ -0,0 +1,13 @@
+{
+  "name": "deno-web-test-success-project",
+  "tasks": {
+    "test": "<@see deno-web-test/test/utils.ts#runDenoWebTest>"
+  },
+  "exports": {
+    ".": "./mod.ts"
+  },
+  "imports": {
+    "@std/assert": "jsr:@std/assert",
+    "@std/testing": "jsr:@std/testing"
+  }
+}
diff --git a/typescript/packages/deno-web-test/test/success-project/mod.ts b/typescript/packages/deno-web-test/test/success-project/mod.ts
@@ -0,0 +1 @@
+export { add } from "./add.ts";
diff --git a/typescript/packages/deno-web-test/test/utils.ts b/typescript/packages/deno-web-test/test/utils.ts
diff --git a/typescript/packages/scripts/test-all.ts b/typescript/packages/scripts/test-all.ts
diff --git a/typescript/packages/scripts/utils.ts b/typescript/packages/scripts/utils.ts

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@commontools/deno-web-test",`
`3`	`3`	`"tasks": {`
`4`		`- "test": "deno run --allow-env --allow-read --allow-write --allow-run --allow-net ./cli.ts test/*.test.ts"`
	`4`	`+ "test": "deno test --allow-env --allow-read --allow-write --allow-run --allow-net test/*.test.ts"`
`5`	`5`	`},`
`6`	`6`	`"exports": {`
`7`	`7`	`".": "./mod.ts",`