@w-lfpup/jackrabbit 0.1.0 → 0.3.0

package/.github/workflows/browsers.json

@@ -0,0 +1,45 @@
+{
+	"host_and_port": "http://127.0.0.1:4000",
+	"runAsynchronusly": false,
+	"webdrivers": [
+		{
+			"command": "$GECKOWEBDRIVER/geckodriver -p 4001",
+			"title": "Firefox",
+			"timeout_ms": 30000,
+			"url": "http://localhost:4001",
+			"capabilities": {
+				"alwaysMatch": {
+					"moz:firefoxOptions": {
+						"args": ["-headless"]
+					}
+				}
+			}
+		},
+		{
+			"command": "$CHROMEWEBDRIVER/chromedriver --port=4005",
+			"title": "Chrome",
+			"timeout_ms": 30000,
+			"url": "http://localhost:4005",
+			"capabilities": {
+				"alwaysMatch": {
+					"goog:chromeOptions": {
+						"args": ["--headless"]
+					}
+				}
+			}
+		},
+		{
+			"command": "$EDGEWEBDRIVER/msedgedriver --port=4010",
+			"title": "Edge",
+			"timeout_ms": 30000,
+			"url": "http://localhost:4010",
+			"capabilities": {
+				"alwaysMatch": {
+					"ms:edgeOptions": {
+						"args": ["--headless", "--disable-dev-shm-usage"]
+					}
+				}
+			}
+		}
+	]
+}

package/.github/workflows/browsers.macos.json

@@ -0,0 +1,51 @@
+{
+	"host_and_port": "http://127.0.0.1:4000",
+	"runAsynchronusly": false,
+	"webdrivers": [
+		{
+			"command": "safaridriver -p 4001",
+			"title": "Safari",
+			"timeout_ms": 30000,
+			"url": "http://localhost:4001"
+		},
+		{
+			"command": "$GECKOWEBDRIVER/geckodriver -p 4001",
+			"title": "Firefox",
+			"timeout_ms": 30000,
+			"url": "http://127.0.0.1:4001",
+			"capabilities": {
+				"alwaysMatch": {
+					"moz:firefoxOptions": {
+						"args": ["-headless"]
+					}
+				}
+			}
+		},
+		{
+			"command": "$CHROMEWEBDRIVER/chromedriver --port=4001",
+			"title": "Chrome",
+			"timeout_ms": 30000,
+			"url": "http://localhost:4001",
+			"capabilities": {
+				"alwaysMatch": {
+					"goog:chromeOptions": {
+						"args": ["--headless"]
+					}
+				}
+			}
+		},
+		{
+			"command": "$EDGEWEBDRIVER/msedgedriver --port=4001",
+			"title": "Edge",
+			"timeout_ms": 30000,
+			"url": "http://localhost:4001",
+			"capabilities": {
+				"alwaysMatch": {
+					"ms:edgeOptions": {
+						"args": ["--headless"]
+					}
+				}
+			}
+		}
+	]
+}

package/.github/workflows/browsers.windows.json

@@ -0,0 +1,19 @@
+{
+	"host_and_port": "http://127.0.0.1:4000",
+	"runAsynchronusly": false,
+	"webdrivers": [
+		{
+			"command": "$Env:GECKOWEBDRIVER\\geckodriver.exe -p 4001",
+			"title": "Firefox",
+			"timeout_ms": 20000,
+			"url": "http://127.0.0.1:4001",
+			"capabilities": {
+				"alwaysMatch": {
+					"moz:firefoxOptions": {
+						"args": ["-headless"]
+					}
+				}
+			}
+		}
+	]
+}

package/.github/workflows/tests.yml

@@ -0,0 +1,42 @@
+name: Tests
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  build_and_test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+      - name: Install
+        run: npm ci
+      - name: Test
+        run: npm run test
+      - name: Test browsers
+        run: npx jackrabbit_webdriver .github/workflows/browsers.json ./tests/dist/mod.js
+  build_and_test_macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+      - name: Install
+        run: npm ci
+      - name: Test
+        run: npm run test
+      - name: Test browsers
+        run: npx jackrabbit_webdriver .github/workflows/browsers.macos.json ./tests/dist/mod.js
+  # build_and_test_windows:
+  #   runs-on: windows-latest
+  #   steps:
+  #     - uses: actions/checkout@v6
+  #     - uses: actions/setup-node@v6
+  #     - name: Install
+  #       run: npm ci
+  #     - name: Test
+  #       run: npm run test
+  #     - name: Test browsers
+  #       run: npx jackrabbit_webdriver .github/workflows/browsers.windows.json ./tests/dist/mod.js

package/README.md

@@ -2,13 +2,9 @@
 
 Write tests without dependencies (including jackrabbit itself).
 
-## Tests
-
-Read [this guide](./test_guide.md) to create jackrabbit tests.
+[![Tests](https://github.com/w-lfpup/jackrabbit-js/actions/workflows/tests.yml/badge.svg)](https://github.com/w-lfpup/jackrabbit-js/actions/workflows/tests.yml)
 
-## Nodejs
-
-### Install
+## Install
 
 Install jackrabbit with npm.
 
@@ -22,10 +18,157 @@ Or Install jackrabbit directly from github.
 npm install --save-dev https://github.com/w-lfpup/jackrabbit-js
 ```
 
-### Run Test Collections
+# Tests
+
+For a quick visual reference, please refer to the [examples](./examples/).
+
+Developers with javascript experience can immediately start testing with basically zero overhead.
+
+## Tests
+
+Tests are functions or promises that return assertions.
+
+Tests `pass` when they return the `undefined` primitive or an empty array `[]`.
+
+```TS
+// my.tests.ts
+
+function testStuffAndPass() {
+	return;
+}
+
+function testMoreStuffAndPass() {
+	return [];
+}
+```
+
+Any other value will cause a test to `fail`.
+
+So tests that `fail` look like:
+
+```TS
+// my.tests.ts
+
+function testStuffAndFail() {
+	return "this test failed!";
+}
+
+function testMoreStuffAndFail() {
+	return ["this test also failed!"];
+}
+```
+
+## Test Modules
+
+Test Modules are javascript `modules` that export two values: `tests` and `options`.
+
+### Export Tests
+
+Test Modules export their tests in an array called `tests`.
+
+```TS
+// my.tests.ts
+
+export const tests = [
+	testStuffAndPass,
+	testMoreStuffAndPass,
+	testStuffAndFail,
+	testMoreStuffAndFail,
+];
+```
+
+### Export Options
+
+Export a parameter object named `options` to affect test behaviors in the current module:
+
+```TS
+// my.tests.ts
+
+interface Options {
+  runAsynchronously?: boolean;
+  timeoutMs?: number;
+  title?: string;
+}
+
+...
+
+export const options = {
+	runAsyncronously: true,
+	timeoutMs: 3000,
+	title: import.meta.url,
+}
+```
+
+All properties are optional and exporting an `options` pojo is not required.
+
+Tests run sequentially unless the `runAsyncronously` property is set to `true`.
+
+## Test Collections
+
+A `test collection` is a javascript module that exports a list test modules called `testModules`.
+
+```TS
+// mod.test.ts
+
+import * as MyTests from "./my.tests.ts";
+
+export const testModules = [
+	MyTests
+];
+```
+
+## Run Test Collections
+
+### NodeJS
+
+Run the following command to log the results of a test collection in nodejs.
+
+```sh
+npx jackrabbit ./mod.tests.ts
+```
+
+To run multiple test collections, add more filepaths as commandline arguments:
+
+```sh
+npx jackrabbit ./mod.tests.ts ./another_mod.tests.ts
+```
+
+### Webdrivers
+
+Run the following command to log the results of a test collection from a browser.
 
 ```sh
-npx jackrabbit --file ./path/to/test/collection.ts
+npx jackrabbit_webdriver ./config.json ./mod.tests.ts
+```
+
+To run multiple test collections, add more filepaths as commandline arguments:
+
+```sh
+npx jackrabbit_webdriver ./config.json ./mod.tests.ts ./another_mod.tests.ts
+```
+
+An example `jackrabbit_webdriver` config is as follows:
+
+```JSON
+{
+	"host_and_port": "http://localhost:4000",
+	"run_asynchronously": false,
+	"webdrivers": [
+		{
+			"title": "Firefox",
+			"command": "geckodriver -p 4001",
+			"timeout_ms": 20000,
+			"url": "http://localhost:4001",
+			"capabilities": {
+				"alwaysMatch": {
+					"moz:firefoxOptions": {
+						"args": ["-headless"]
+					}
+				}
+			}
+		}
+	]
+}
 ```
 
 ## License

package/browser/dist/logger.js

@@ -0,0 +1,43 @@
+export class Logger {
+    #fetchQueue = new FetchQueue();
+    #cancelled = false;
+    get cancelled() {
+        return this.#cancelled;
+    }
+    log(action) {
+        this.#fetchQueue.enqueue(function () {
+            return fetch(`/log/${action.type}`, {
+                body: JSON.stringify(action),
+                headers: new Headers([["Content-Type", "application/json"]]),
+                method: "POST",
+            });
+        });
+    }
+}
+class FetchQueue {
+    #inbound = [];
+    #outbound = [];
+    #inRoute;
+    enqueue(queueable) {
+        this.#inbound.push(queueable);
+        if (!this.#inRoute)
+            this.#queueAtom();
+    }
+    #queueAtom() {
+        if (!this.#outbound.length) {
+            while (this.#inbound.length) {
+                let pip = this.#inbound.pop();
+                if (pip)
+                    this.#outbound.push(pip);
+            }
+        }
+        this.#inRoute = this.#outbound.pop();
+        this.#execAtom();
+    }
+    async #execAtom() {
+        if (this.#inRoute) {
+            await this.#inRoute();
+            this.#queueAtom();
+        }
+    }
+}

package/browser/dist/mod.js

@@ -0,0 +1,26 @@
+import { Logger } from "./logger.js";
+import { run } from "./runner.js";
+let logger = new Logger();
+try {
+    let jackrabbitMap = document.querySelector("script[type=jackrabbit_config]");
+    if (null === jackrabbitMap)
+        throw new Error("Failed to query jackrabbit_config script");
+    // should be it's own verification and then throw
+    let config = JSON.parse(jackrabbitMap.textContent);
+    logger.log({
+        type: "start_run",
+        time: performance.now(),
+        expected_collection_count: config?.test_collections?.length ?? 0,
+    });
+    await run(logger, config.test_collections, config.jackrabbit_url);
+    logger.log({
+        type: "end_run",
+        time: performance.now(),
+    });
+}
+catch (e) {
+    logger.log({
+        type: "run_error",
+        error: e?.toString() ?? "wild horses error",
+    });
+}

package/browser/dist/queue.js

@@ -0,0 +1,27 @@
+export class FetchQueue {
+    #inbound = [];
+    #outbound = [];
+    #inRoute;
+    enqueue(queueable) {
+        this.#inbound.push(queueable);
+        if (!this.#inRoute)
+            this.#queueAtom();
+    }
+    #queueAtom() {
+        if (!this.#outbound.length) {
+            while (this.#inbound.length) {
+                let pip = this.#inbound.pop();
+                if (pip)
+                    this.#outbound.push(pip);
+            }
+        }
+        this.#inRoute = this.#outbound.pop();
+        this.#execAtom();
+    }
+    async #execAtom() {
+        if (this.#inRoute) {
+            await this.#inRoute();
+            this.#queueAtom();
+        }
+    }
+}

package/browser/dist/runner.js

@@ -0,0 +1,20 @@
+import { runCollection } from "jackrabbit/core/dist/mod.js";
+export async function run(logger, files, baseUrl) {
+    for (const [collection_id, url] of files.entries()) {
+        try {
+            let filepath = URL.parse(url, baseUrl);
+            if (null === filepath)
+                throw new Error("Failed to import url: " + url);
+            let filepathStr = filepath.toString();
+            const { testModules } = await import(filepath.toString());
+            await runCollection(logger, testModules, collection_id, filepathStr);
+        }
+        catch (e) {
+            logger.log({
+                type: "collection_error",
+                collection_id,
+                error: e?.toString() ?? "wild horses error",
+            });
+        }
+    }
+}

package/{cli → browser}/package.json

@@ -1,5 +1,5 @@
 {
-	"name": "cli",
+	"name": "browser",
 	"type": "module",
 	"main": "dist/mod.js",
 	"scripts": {

package/browser/src/logger.ts

@@ -0,0 +1,57 @@
+import type {
+	LoggerAction,
+	LoggerInterface,
+} from "jackrabbit/core/dist/mod.js";
+
+interface Queueable {
+	(): Promise<unknown>;
+}
+
+export class Logger implements LoggerInterface {
+	#fetchQueue = new FetchQueue();
+	#cancelled = false;
+
+	get cancelled() {
+		return this.#cancelled;
+	}
+
+	log(action: LoggerAction) {
+		this.#fetchQueue.enqueue(function () {
+			return fetch(`/log/${action.type}`, {
+				body: JSON.stringify(action),
+				headers: new Headers([["Content-Type", "application/json"]]),
+				method: "POST",
+			});
+		});
+	}
+}
+
+class FetchQueue {
+	#inbound: Queueable[] = [];
+	#outbound: Queueable[] = [];
+	#inRoute: Queueable | undefined;
+
+	enqueue(queueable: Queueable) {
+		this.#inbound.push(queueable);
+		if (!this.#inRoute) this.#queueAtom();
+	}
+
+	#queueAtom() {
+		if (!this.#outbound.length) {
+			while (this.#inbound.length) {
+				let pip = this.#inbound.pop();
+				if (pip) this.#outbound.push(pip);
+			}
+		}
+
+		this.#inRoute = this.#outbound.pop();
+		this.#execAtom();
+	}
+
+	async #execAtom() {
+		if (this.#inRoute) {
+			await this.#inRoute();
+			this.#queueAtom();
+		}
+	}
+}

package/browser/src/mod.ts

@@ -0,0 +1,30 @@
+import { Logger } from "./logger.js";
+import { run } from "./runner.js";
+
+let logger = new Logger();
+
+try {
+	let jackrabbitMap = document.querySelector("script[type=jackrabbit_config]");
+	if (null === jackrabbitMap)
+		throw new Error("Failed to query jackrabbit_config script");
+
+	// should be it's own verification and then throw
+	let config = JSON.parse(jackrabbitMap.textContent);
+
+	logger.log({
+		type: "start_run",
+		time: performance.now(),
+		expected_collection_count: config?.test_collections?.length ?? 0,
+	});
+
+	await run(logger, config.test_collections, config.jackrabbit_url);
+	logger.log({
+		type: "end_run",
+		time: performance.now(),
+	});
+} catch (e: unknown) {
+	logger.log({
+		type: "run_error",
+		error: e?.toString() ?? "wild horses error",
+	});
+}

package/browser/src/runner.ts

@@ -0,0 +1,22 @@
+import type { Logger } from "./logger.js";
+
+import { runCollection } from "jackrabbit/core/dist/mod.js";
+
+export async function run(logger: Logger, files: string[], baseUrl: string) {
+	for (const [collection_id, url] of files.entries()) {
+		try {
+			let filepath = URL.parse(url, baseUrl);
+			if (null === filepath) throw new Error("Failed to import url: " + url);
+
+			let filepathStr = filepath.toString();
+			const { testModules } = await import(filepath.toString());
+			await runCollection(logger, testModules, collection_id, filepathStr);
+		} catch (e: unknown) {
+			logger.log({
+				type: "collection_error",
+				collection_id,
+				error: e?.toString() ?? "wild horses error",
+			});
+		}
+	}
+}

package/browser/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"extends": "../tsconfig.json",
+	"compilerOptions": {
+		"declaration": false,
+		"rootDir": "./src",
+		"outDir": "./dist",
+		"paths": {
+			"jackrabbit/core/*": ["../core/*"]
+		}
+	}
+}

package/browser/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/logger.ts","./src/mod.ts","./src/runner.ts"],"version":"5.9.3"}

package/browsers.json

@@ -0,0 +1,38 @@
+{
+	"host_and_port": "http://localhost:4000",
+	"run_asynchronously": false,
+	"webdrivers": [
+		{
+			"command": "safaridriver -p 4001",
+			"title": "Safari",
+			"timeout_ms": 20000,
+			"url": "http://localhost:4001"
+		},
+		{
+			"command": "geckodriver -p 4001",
+			"title": "Firefox",
+			"timeout_ms": 20000,
+			"url": "http://localhost:4001",
+			"capabilities": {
+				"alwaysMatch": {
+					"moz:firefoxOptions": {
+						"args": ["-headless"]
+					}
+				}
+			}
+		},
+		{
+			"command": "/Users/taylor/workspace/chromedriver-mac-arm64/chromedriver --port=4001",
+			"title": "Chrome",
+			"timeout_ms": 20000,
+			"url": "http://localhost:4001",
+			"capabilities": {
+				"alwaysMatch": {
+					"goog:chromeOptions": {
+						"args": ["--headless"]
+					}
+				}
+			}
+		}
+	]
+}