@w-lfpup/jackrabbit 0.1.0

package/core/dist/run_steps.js

@@ -0,0 +1,95 @@
+const TIMEOUT_INTERVAL_MS = 10000;
+function sleep(time) {
+    return new Promise((resolve) => {
+        setTimeout(() => {
+            resolve();
+        }, time);
+    });
+}
+async function createTimeout(timeoutMs = TIMEOUT_INTERVAL_MS) {
+    await sleep(timeoutMs);
+    return `timed out at ${performance.now()} after ${timeoutMs} ms.`;
+}
+async function execTest(testModules, logger, moduleId, testId) {
+    if (logger.cancelled)
+        return;
+    logger.log(testModules, {
+        type: "start_test",
+        moduleId,
+        testId,
+    });
+    const { tests, options } = testModules[moduleId];
+    const testFunc = tests[testId];
+    const startTime = performance.now();
+    const assertions = await Promise.race([
+        createTimeout(options.timeoutMs),
+        testFunc(),
+    ]);
+    if (logger.cancelled)
+        return;
+    const endTime = performance.now();
+    logger.log(testModules, {
+        type: "end_test",
+        assertions,
+        endTime,
+        moduleId,
+        startTime,
+        testId,
+    });
+}
+async function execCollection(testModules, logger, moduleId) {
+    if (logger.cancelled)
+        return;
+    const { tests } = testModules[moduleId];
+    const wrappedTests = [];
+    for (let [testID] of tests.entries()) {
+        wrappedTests.push(execTest(testModules, logger, moduleId, testID));
+    }
+    if (logger.cancelled)
+        return;
+    await Promise.all(wrappedTests);
+}
+async function execCollectionOrdered(testModules, logger, moduleId) {
+    const { tests } = testModules[moduleId];
+    for (let [testID] of tests.entries()) {
+        if (logger.cancelled)
+            return;
+        await execTest(testModules, logger, moduleId, testID);
+    }
+}
+export async function startRun(logger, testModules) {
+    logger.log(testModules, {
+        type: "start_run",
+        time: performance.now(),
+    });
+    for (let [moduleId, testModule] of testModules.entries()) {
+        if (logger.cancelled)
+            return;
+        logger.log(testModules, {
+            type: "start_module",
+            moduleId,
+        });
+        const { options } = testModule;
+        options?.runAsynchronously
+            ? await execCollection(testModules, logger, moduleId)
+            : await execCollectionOrdered(testModules, logger, moduleId);
+        if (logger.cancelled)
+            return;
+        logger.log(testModules, {
+            type: "end_module",
+            moduleId,
+        });
+    }
+    logger.log(testModules, {
+        type: "end_run",
+        time: performance.now(),
+    });
+}
+export function cancelRun(logger, testModules) {
+    if (logger.cancelled)
+        return;
+    logger.log(testModules, {
+        type: "cancel_run",
+        time: performance.now(),
+    });
+}

package/core/package.json

@@ -0,0 +1,8 @@
+{
+	"name": "core",
+	"type": "module",
+	"main": "dist/mod.js",
+	"scripts": {
+		"build": "npx tsc --build"
+	}
+}

package/core/src/jackrabbit_types.ts

@@ -0,0 +1,75 @@
+interface Stringable {
+	toString: Object["toString"];
+}
+
+export type Assertions = Stringable | Stringable[] | undefined;
+
+type SyncTest = () => Assertions;
+type AsyncTest = () => Promise<Assertions>;
+export type Test = SyncTest | AsyncTest;
+
+export interface Options {
+	title?: string;
+	runAsynchronously?: boolean;
+	timeoutMs?: number;
+}
+
+export interface TestModule {
+	tests: Test[];
+	options: Options;
+}
+
+interface StartRun {
+	type: "start_run";
+	time: number;
+}
+
+interface EndRun {
+	type: "end_run";
+	time: number;
+}
+
+interface CancelRun {
+	type: "cancel_run";
+	time: number;
+}
+
+interface StartModule {
+	type: "start_module";
+	moduleId: number;
+}
+
+interface EndModule {
+	type: "end_module";
+	moduleId: number;
+}
+
+interface StartTest {
+	type: "start_test";
+	testId: number;
+	moduleId: number;
+}
+
+interface EndTest {
+	type: "end_test";
+	testId: number;
+	moduleId: number;
+	startTime: number;
+	endTime: number;
+	assertions: Assertions;
+}
+
+export type LoggerAction =
+	| StartRun
+	| EndRun
+	| CancelRun
+	| StartModule
+	| EndModule
+	| StartTest
+	| EndTest;
+
+export interface LoggerInterface {
+	readonly failed: boolean;
+	readonly cancelled: boolean;
+	log(testModules: TestModule[], action: LoggerAction): void;
+}

package/core/src/mod.ts

@@ -0,0 +1,9 @@
+export type {
+	LoggerAction,
+	LoggerInterface,
+	Test,
+	Options,
+	TestModule,
+} from "./jackrabbit_types.ts";
+
+export { startRun, cancelRun } from "./run_steps.js";

package/core/src/run_steps.ts

@@ -0,0 +1,138 @@
+import type {
+	Assertions,
+	LoggerInterface,
+	TestModule,
+} from "./jackrabbit_types.ts";
+
+const TIMEOUT_INTERVAL_MS = 10000;
+
+function sleep(time: number): Promise<void> {
+	return new Promise((resolve) => {
+		setTimeout(() => {
+			resolve();
+		}, time);
+	});
+}
+
+async function createTimeout(
+	timeoutMs: number = TIMEOUT_INTERVAL_MS,
+): Promise<Assertions> {
+	await sleep(timeoutMs);
+
+	return `timed out at ${performance.now()} after ${timeoutMs} ms.`;
+}
+
+async function execTest(
+	testModules: TestModule[],
+	logger: LoggerInterface,
+	moduleId: number,
+	testId: number,
+) {
+	if (logger.cancelled) return;
+
+	logger.log(testModules, {
+		type: "start_test",
+		moduleId,
+		testId,
+	});
+
+	const { tests, options } = testModules[moduleId];
+
+	const testFunc = tests[testId];
+	const startTime = performance.now();
+	const assertions = await Promise.race([
+		createTimeout(options.timeoutMs),
+		testFunc(),
+	]);
+
+	if (logger.cancelled) return;
+
+	const endTime = performance.now();
+
+	logger.log(testModules, {
+		type: "end_test",
+		assertions,
+		endTime,
+		moduleId,
+		startTime,
+		testId,
+	});
+}
+
+async function execCollection(
+	testModules: TestModule[],
+	logger: LoggerInterface,
+	moduleId: number,
+) {
+	if (logger.cancelled) return;
+
+	const { tests } = testModules[moduleId];
+
+	const wrappedTests = [];
+	for (let [testID] of tests.entries()) {
+		wrappedTests.push(execTest(testModules, logger, moduleId, testID));
+	}
+
+	if (logger.cancelled) return;
+
+	await Promise.all(wrappedTests);
+}
+
+async function execCollectionOrdered(
+	testModules: TestModule[],
+	logger: LoggerInterface,
+	moduleId: number,
+) {
+	const { tests } = testModules[moduleId];
+
+	for (let [testID] of tests.entries()) {
+		if (logger.cancelled) return;
+
+		await execTest(testModules, logger, moduleId, testID);
+	}
+}
+
+export async function startRun(
+	logger: LoggerInterface,
+	testModules: TestModule[],
+) {
+	logger.log(testModules, {
+		type: "start_run",
+		time: performance.now(),
+	});
+
+	for (let [moduleId, testModule] of testModules.entries()) {
+		if (logger.cancelled) return;
+
+		logger.log(testModules, {
+			type: "start_module",
+			moduleId,
+		});
+
+		const { options } = testModule;
+		options?.runAsynchronously
+			? await execCollection(testModules, logger, moduleId)
+			: await execCollectionOrdered(testModules, logger, moduleId);
+
+		if (logger.cancelled) return;
+
+		logger.log(testModules, {
+			type: "end_module",
+			moduleId,
+		});
+	}
+
+	logger.log(testModules, {
+		type: "end_run",
+		time: performance.now(),
+	});
+}
+
+export function cancelRun(logger: LoggerInterface, testModules: TestModule[]) {
+	if (logger.cancelled) return;
+
+	logger.log(testModules, {
+		type: "cancel_run",
+		time: performance.now(),
+	});
+}

package/core/tsconfig.json

@@ -0,0 +1,7 @@
+{
+	"extends": "../tsconfig.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist"
+	}
+}

package/core/tsconfig.tsbuildinfo

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

package/examples/hello_world/goodbye_world.ts

@@ -0,0 +1,15 @@
+async function test_that_passes() {
+	return [];
+}
+
+async function test_that_fails() {
+	return ["this test will fail"];
+}
+
+export const tests = [test_that_passes, test_that_fails];
+
+export const options = {
+	title: import.meta.url,
+	runAsynchronously: true,
+	timeoutMs: 2000,
+};

package/examples/hello_world/hello_world.ts

@@ -0,0 +1,9 @@
+function test_will_pass() {
+	return;
+}
+
+function test_will_fail() {
+	return "this test will fail";
+}
+
+export const tests = [test_will_pass, test_will_fail];

package/examples/hello_world/mod.ts

@@ -0,0 +1,4 @@
+import * as hello_world from "./hello_world.js";
+import * as goodbye_world from "./goodbye_world.js";
+
+export const testModules = [hello_world, goodbye_world];

package/examples/package.json

@@ -0,0 +1,3 @@
+{
+	"type": "module"
+}

package/nodejs_cli/dist/mod.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/nodejs_cli/dist/mod.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { Config, Importer, Logger, run } from "../../cli/dist/mod.js";
+const config = new Config(process.argv.slice(2));
+const importer = new Importer(process.cwd());
+const logger = new Logger();
+let errored = false;
+try {
+    await run(config, importer, logger);
+}
+catch (e) {
+    errored = true;
+    console.log("Error:");
+    e instanceof Error
+        ? console.log(`
+${e.name}
+${e.message}
+${e.stack}`)
+        : console.log(e);
+}
+logger.failed || errored ? process.exit(1) : process.exit(0);

package/nodejs_cli/package.json

@@ -0,0 +1,8 @@
+{
+	"name": "nodejs_cli",
+	"type": "module",
+	"main": "dist/mod.js",
+	"scripts": {
+		"build": "npx tsc --build"
+	}
+}

package/nodejs_cli/src/mod.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { Config, Importer, Logger, run } from "../../cli/dist/mod.js";
+
+const config = new Config(process.argv.slice(2));
+const importer = new Importer(process.cwd());
+const logger = new Logger();
+
+let errored = false;
+
+try {
+	await run(config, importer, logger);
+} catch (e: unknown) {
+	errored = true;
+	console.log("Error:");
+
+	e instanceof Error
+		? console.log(`
+${e.name}
+${e.message}
+${e.stack}`)
+		: console.log(e);
+}
+
+logger.failed || errored ? process.exit(1) : process.exit(0);

package/nodejs_cli/tsconfig.json

@@ -0,0 +1,7 @@
+{
+	"extends": "../tsconfig.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist"
+	}
+}

package/nodejs_cli/tsconfig.tsbuildinfo

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

package/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "@w-lfpup/jackrabbit",
+	"description": "A test runner without dependencies",
+	"workspaces": [
+		"core",
+		"tests",
+		"cli",
+		"nodejs_cli"
+	],
+	"bin": {
+		"jackrabbit": "nodejs_cli/dist/mod.js"
+	},
+	"scripts": {
+		"prepare": "npm run build",
+		"build": "npm run --workspaces build",
+		"format": "npx prettier --write ./",
+		"test": "npx jackrabbit --file ./tests/dist/mod.js"
+	},
+	"version": "0.1.0",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/w-lfpup/jackarabbit-js.git"
+	},
+	"devDependencies": {
+		"@types/node": "^22.5.5",
+		"prettier": "^3.3.1",
+		"typescript": "^5.4.5"
+	}
+}

package/test_guide.md

@@ -0,0 +1,114 @@
+# Jackrabbit Tests
+
+For a quick visual reference, please refer to the [examples](./examples/).
+
+`Jackrabbit` leverages esmodules for a flat, concise testing experience. There are no assertion libraries, there are no wild BDD functions. Developers with javascript experience can immediately start testing with basically zero overhead.
+
+## Tests
+
+Tests are functions that return assertions.
+
+Tests `pass` when they return the `undefined` primitive or an empty array `[]`.
+
+```TS
+// my_library.tests.ts
+
+function testStuffAndPass() {
+	return;
+}
+
+async function testMoreStuffAndPass() {
+	return [];
+}
+```
+
+Any other value will cause a test to `fail`.
+
+So tests that `fail` look like:
+
+```TS
+// my_library.tests.ts
+
+function testStuffAndFail() {
+	return "this test failed!";
+}
+
+function testMoreStuffAndFail() {
+	return ["this test also failed!"];
+}
+```
+
+## Test Modules
+
+Test Modules are javascript `modules` that contain tests.
+
+### Export Tests
+
+Test Modules export their tests in an array called `tests`.
+
+```TS
+// my_library.tests.ts
+
+export const tests = [
+	testStuffAndPass,
+	testMoreStuffAndPass,
+	testStuffAndFail,
+	testMoreStuffAndFail,
+];
+```
+
+### Export Options
+
+Exporting an `options` pojo is not required.
+
+But exporting an `options` pojo with the following properties will affect test behavior:
+
+```TS
+export const options = {
+	title: import.meta.url,
+	runAsyncronously: true,
+	timeoutMs: 3000,
+}
+```
+
+All properteis are optional.
+
+Tests run sequentially unless the `runAsyncronously` property is set to `true`.
+
+```TS
+// my_library.tests.ts
+
+interface Options {
+  title?: string;
+  runAsynchronously?: boolean;
+  timeoutMs?: number;
+}
+```
+
+## 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_library.tests.ts";
+
+export const testModules = [
+	MyTests
+];
+```
+
+This gathers all tests into a single explicit location.
+
+## Run Test Collections
+
+Run the following command and Jackrabbit will log the results of `test collections`.
+
+```sh
+npx jackrabbit --file ./mod.test.ts
+```
+
+## License
+
+BSD 3-Clause License

package/tests/dist/mod.d.ts

@@ -0,0 +1,9 @@
+declare function testsFail(): Promise<"fail tests failed to fail" | undefined>;
+declare function testsPass(): Promise<"passing tests failed to pass" | undefined>;
+export declare const testModules: {
+    tests: (typeof testsFail | typeof testsPass)[];
+    options: {
+        title: string;
+    };
+}[];
+export {};

package/tests/dist/mod.js

@@ -0,0 +1,30 @@
+import * as FailTests from "./test_fail.test.js";
+import * as PassTests from "./test_pass.test.js";
+import { startRun } from "../../core/dist/mod.js";
+import { TestLogger } from "./test_logger.js";
+// Test pass and fail behavior
+const failTestModules = [FailTests];
+const passTestModules = [PassTests];
+// jackrabbit test run won't pass failing tests
+async function testsFail() {
+    let logger = new TestLogger();
+    await startRun(logger, failTestModules);
+    if (!logger.failed)
+        return "fail tests failed to fail";
+}
+// jackrabbit test run won't fail passing tests
+async function testsPass() {
+    let logger = new TestLogger();
+    await startRun(logger, passTestModules);
+    if (logger.failed)
+        return "passing tests failed to pass";
+}
+const tests = [testsFail, testsPass];
+const options = {
+    title: "Failures and Successes",
+};
+const testModule = {
+    tests,
+    options,
+};
+export const testModules = [testModule];

package/tests/dist/test_fail.test.d.ts

@@ -0,0 +1,9 @@
+declare function testStuffAndFail(): string;
+declare function testMoreStuffAndFail(): string[];
+declare function testStuffAndFailAsync(): Promise<string>;
+declare function testMoreStuffAndFailAsync(): Promise<string[]>;
+export declare const tests: (typeof testStuffAndFail | typeof testMoreStuffAndFail | typeof testStuffAndFailAsync | typeof testMoreStuffAndFailAsync)[];
+export declare const options: {
+    title: string;
+};
+export {};

package/tests/dist/test_fail.test.js

@@ -0,0 +1,23 @@
+function testStuffAndFail() {
+    return "this test failed!";
+}
+function testMoreStuffAndFail() {
+    return ["this test also failed!"];
+}
+async function testStuffAndFailAsync() {
+    return "this test failed!";
+}
+async function testMoreStuffAndFailAsync() {
+    return ["this test also failed!"];
+}
+// export tests
+export const tests = [
+    testStuffAndFail,
+    testMoreStuffAndFail,
+    testStuffAndFailAsync,
+    testMoreStuffAndFailAsync,
+];
+// export optional test details
+export const options = {
+    title: import.meta.url,
+};

package/tests/dist/test_logger.d.ts

@@ -0,0 +1,7 @@
+import type { LoggerAction, LoggerInterface, TestModule } from "../../core/dist/mod.ts";
+declare class TestLogger implements LoggerInterface {
+    cancelled: boolean;
+    failed: boolean;
+    log(_testModule: TestModule[], action: LoggerAction): void;
+}
+export { TestLogger };