@mantaq/test 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anders Can
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# @mantaq/test
+
+Test harness and assertion utilities for verifying
+[@mantaq/core](https://www.npmjs.com/package/@mantaq/core) actor behavior.
+
+Drive actors through event sequences, advance the virtual clock
+deterministically, and assert on coverage of states and transitions
+(see [@mantaq/traversal](https://www.npmjs.com/package/@mantaq/traversal)).

package/dist/index.d.mts

@@ -0,0 +1,76 @@
+import { ActorGraph, History } from "@mantaq/traversal";
+import { AnyActor, Snapshot } from "@mantaq/core";
+//#region src/types.d.ts
+interface CoverageReport {
+  states: {
+    total: number;
+    visited: number;
+    uncovered: string[];
+  };
+  transitions: {
+    total: number;
+    visited: number;
+    uncovered: Array<{
+      from: string;
+      event: string;
+    }>;
+  };
+  effects: {
+    total: number;
+    ran: number;
+    unexecuted: string[];
+  };
+  percent: {
+    states: number;
+    transitions: number;
+    effects: number;
+  };
+}
+interface TestHarness {
+  actor: AnyActor;
+  graph: ActorGraph;
+  history: History;
+  coverage: () => CoverageReport;
+  send(event: {
+    id: string;
+  } & Record<string, unknown>): void;
+  state: AnyActor["state"];
+  snapshot(): Snapshot;
+  context: Record<string, unknown> | undefined;
+  assertAllStatesVisited(): void;
+  assertAllTransitionsVisited(): void;
+  assertStateVisited(stateName: string): void;
+  assertStateNeverVisited(stateName: string): void;
+  assertTransitionVisited(from: string, event: string): void;
+  assertTransitionNeverVisited(from: string, event: string): void;
+  assertContextNever(predicate: (ctx: unknown) => boolean): void;
+  assertEffectRan(stateName: string): void;
+  assertEffectNeverRan(stateName: string): void;
+  assertReachedState(stateName: string): void;
+  assertNeverReachedState(stateName: string): void;
+  wasStateVisited(stateName: string): boolean;
+  wasTransitionVisited(from: string, event: string): boolean;
+  wasEffectRun(stateName: string): boolean;
+  reset(): void;
+}
+//#endregion
+//#region src/harness.d.ts
+declare function createTestHarness(actor: AnyActor): TestHarness;
+//#endregion
+//#region src/coverage.d.ts
+declare function computeCoverage(graph: ActorGraph, history: History): CoverageReport;
+//#endregion
+//#region src/assertions.d.ts
+declare function assertAllStatesVisited(graph: ActorGraph, history: History): void;
+declare function assertAllTransitionsVisited(graph: ActorGraph, history: History): void;
+declare function assertStateVisited(history: History, stateName: string): void;
+declare function assertStateNeverVisited(history: History, stateName: string): void;
+declare function assertTransitionVisited(history: History, from: string, event: string): void;
+declare function assertTransitionNeverVisited(history: History, from: string, event: string): void;
+declare function assertContextNever(actor: AnyActor, predicate: (ctx: unknown) => boolean): void;
+declare function assertEffectRan(history: History, stateName: string): void;
+declare function assertEffectNeverRan(history: History, stateName: string): void;
+declare function assertReachedState(history: History, stateName: string): void;
+declare function assertNeverReachedState(history: History, stateName: string): void;
+//#endregion
+export { type CoverageReport, type TestHarness, assertAllStatesVisited, assertAllTransitionsVisited, assertContextNever, assertEffectNeverRan, assertEffectRan, assertNeverReachedState, assertReachedState, assertStateNeverVisited, assertStateVisited, assertTransitionNeverVisited, assertTransitionVisited, computeCoverage, createTestHarness };

package/dist/index.mjs

@@ -0,0 +1,128 @@
+import { buildGraph, instrument } from "@mantaq/traversal";
+//#region src/coverage.ts
+function computeCoverage(graph, history) {
+	const visitedStates = history.visitedStates();
+	const firedTransitions = history.firedTransitions();
+	const effects = history.effects();
+	const graphNodes = graph.nodes.filter((n) => n.id !== "__initial__");
+	const graphEdges = graph.edges.filter((e) => e.source !== "__initial__" && e.target !== "__initial__" && !e.isUndetermined && !e.isInternal);
+	const statesTotal = graphNodes.length;
+	const statesVisited = graphNodes.filter((n) => visitedStates.has(n.label)).length;
+	const statesUncovered = graphNodes.filter((n) => !visitedStates.has(n.label)).map((n) => n.label);
+	const transitionsTotal = graphEdges.length;
+	const transitionsVisited = graphEdges.filter((e) => firedTransitions.has(`${e.source}:${e.label}`)).length;
+	const transitionsUncovered = graphEdges.filter((e) => !firedTransitions.has(`${e.source}:${e.label}`)).map((e) => ({
+		from: e.source,
+		event: e.label
+	}));
+	const effectEdges = graph.edges.filter((e) => e.isInternal && e.source === e.target && e.label.startsWith("effect:"));
+	const effectStatesFromGraph = new Set(effectEdges.map((e) => e.source));
+	const effectsRan = new Set(effects.map((e) => e.stateName));
+	const effectsUnexecuted = [...effectStatesFromGraph].filter((s) => !effectsRan.has(s));
+	return {
+		states: {
+			total: statesTotal,
+			visited: statesVisited,
+			uncovered: statesUncovered
+		},
+		transitions: {
+			total: transitionsTotal,
+			visited: transitionsVisited,
+			uncovered: transitionsUncovered
+		},
+		effects: {
+			total: effectStatesFromGraph.size,
+			ran: effectsRan.size,
+			unexecuted: effectsUnexecuted
+		},
+		percent: {
+			states: statesTotal === 0 ? 0 : statesVisited / statesTotal * 100,
+			transitions: transitionsTotal === 0 ? 0 : transitionsVisited / transitionsTotal * 100,
+			effects: effectStatesFromGraph.size === 0 ? 0 : effectsRan.size / effectStatesFromGraph.size * 100
+		}
+	};
+}
+//#endregion
+//#region src/assertions.ts
+function assertAllStatesVisited(graph, history) {
+	const visited = history.visitedStates();
+	const missing = graph.nodes.filter((n) => n.id !== "__initial__").filter((n) => !visited.has(n.label)).map((n) => n.label);
+	if (missing.length > 0) throw new Error(`assertAllStatesVisited failed: states not visited: ${missing.join(", ")}`);
+}
+function assertAllTransitionsVisited(graph, history) {
+	const fired = history.firedTransitions();
+	const missing = graph.edges.filter((e) => e.source !== "__initial__" && e.target !== "__initial__" && !e.isUndetermined && !e.isInternal).filter((e) => !fired.has(`${e.source}:${e.label}`));
+	if (missing.length > 0) {
+		const list = missing.map((e) => `${e.source}:${e.label}`).join(", ");
+		throw new Error(`assertAllTransitionsVisited failed: transitions not visited: ${list}`);
+	}
+}
+function assertStateVisited(history, stateName) {
+	if (!history.visitedStates().has(stateName)) throw new Error(`assertStateVisited failed: state "${stateName}" was not visited`);
+}
+function assertStateNeverVisited(history, stateName) {
+	if (history.visitedStates().has(stateName)) throw new Error(`assertStateNeverVisited failed: state "${stateName}" was visited`);
+}
+function assertTransitionVisited(history, from, event) {
+	if (!history.firedTransitions().has(`${from}:${event}`)) throw new Error(`assertTransitionVisited failed: transition "${from}:${event}" was not visited`);
+}
+function assertTransitionNeverVisited(history, from, event) {
+	if (history.firedTransitions().has(`${from}:${event}`)) throw new Error(`assertTransitionNeverVisited failed: transition "${from}:${event}" was visited`);
+}
+function assertContextNever(actor, predicate) {
+	if (predicate(actor.context)) throw new Error("assertContextNever failed: predicate matched current context");
+}
+function assertEffectRan(history, stateName) {
+	if (!history.effects().some((e) => e.stateName === stateName)) throw new Error(`assertEffectRan failed: effect for state "${stateName}" did not run`);
+}
+function assertEffectNeverRan(history, stateName) {
+	if (history.effects().some((e) => e.stateName === stateName)) throw new Error(`assertEffectNeverRan failed: effect for state "${stateName}" ran`);
+}
+function assertReachedState(history, stateName) {
+	assertStateVisited(history, stateName);
+}
+function assertNeverReachedState(history, stateName) {
+	assertStateNeverVisited(history, stateName);
+}
+//#endregion
+//#region src/harness.ts
+function createTestHarness(actor) {
+	const instrumented = instrument(actor);
+	const internalIds = new Set((actor.options?.internal ?? []).map((e) => e.id));
+	const graph = buildGraph(actor, { internalIds });
+	return {
+		actor: instrumented,
+		graph,
+		history: instrumented.history,
+		coverage: () => computeCoverage(graph, instrumented.history),
+		send(event) {
+			instrumented.send(event);
+		},
+		get state() {
+			return instrumented.state;
+		},
+		snapshot() {
+			return instrumented.snapshot();
+		},
+		get context() {
+			return instrumented.context;
+		},
+		assertAllStatesVisited: () => assertAllStatesVisited(graph, instrumented.history),
+		assertAllTransitionsVisited: () => assertAllTransitionsVisited(graph, instrumented.history),
+		assertStateVisited: (name) => assertStateVisited(instrumented.history, name),
+		assertStateNeverVisited: (name) => assertStateNeverVisited(instrumented.history, name),
+		assertTransitionVisited: (from, event) => assertTransitionVisited(instrumented.history, from, event),
+		assertTransitionNeverVisited: (from, event) => assertTransitionNeverVisited(instrumented.history, from, event),
+		assertContextNever: (predicate) => assertContextNever(instrumented, predicate),
+		assertEffectRan: (name) => assertEffectRan(instrumented.history, name),
+		assertEffectNeverRan: (name) => assertEffectNeverRan(instrumented.history, name),
+		assertReachedState: (name) => assertReachedState(instrumented.history, name),
+		assertNeverReachedState: (name) => assertNeverReachedState(instrumented.history, name),
+		wasStateVisited: (name) => instrumented.history.visitedStates().has(name),
+		wasTransitionVisited: (from, event) => instrumented.history.firedTransitions().has(`${from}:${event}`),
+		wasEffectRun: (name) => instrumented.history.effects().some((e) => e.stateName === name),
+		reset: () => instrumented.history.reset()
+	};
+}
+//#endregion
+export { assertAllStatesVisited, assertAllTransitionsVisited, assertContextNever, assertEffectNeverRan, assertEffectRan, assertNeverReachedState, assertReachedState, assertStateNeverVisited, assertStateVisited, assertTransitionNeverVisited, assertTransitionVisited, computeCoverage, createTestHarness };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mantaq/test",
+  "version": "0.0.1",
+  "description": "Test harness and assertion utilities for verifying mantaq actor behavior.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AndersCan/mantaq",
+    "directory": "packages/test"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mantaq/core": "0.0.1",
+    "@mantaq/traversal": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@vitest/coverage-v8": "4.1.10",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
+    "vite-plus": "0.2.8"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "coverage": "vp test run --coverage"
+  }
+}