automategraph 1.5.1 → 1.5.3

package/tests/harness.ts

@@ -0,0 +1,291 @@
+/* ============================================================
+ * Minimal zero-dependency test harness
+ * ------------------------------------------------------------
+ * - deterministic, sequential execution (isolation per test)
+ * - per-test timeout
+ * - per-test log capture (surfaced in the web report)
+ * - findings tagging (documents observed engine semantics)
+ * ============================================================ */
+
+export const TEST_KINDS = [
+  "unit",
+  "integration",
+  "async",
+  "upgrade",
+  "conformance",
+  "lint",
+  "edges",
+  "registry",
+  "graphjson",
+  "scripts"
+] as const;
+
+export type TestKind = (typeof TEST_KINDS)[number];
+
+export interface KindTotals {
+  total: number;
+  passed: number;
+  failed: number;
+}
+
+export interface TestContext {
+  /** Free-form observation log, rendered in the web report. */
+  log(message: string, ...values: unknown[]): void;
+}
+
+export interface TestCase {
+  readonly id: string;
+  readonly kind: TestKind;
+  readonly category: string;
+  readonly name: string;
+  /** Non-empty => this test documents a noteworthy engine semantic. */
+  readonly finding?: string;
+  readonly timeoutMs: number;
+  readonly fn: (ctx: TestContext) => unknown | Promise<unknown>;
+}
+
+export interface TestResultRecord {
+  id: string;
+  kind: TestKind;
+  category: string;
+  name: string;
+  finding?: string;
+  status: "passed" | "failed";
+  durationMs: number;
+  logs: string[];
+  error?: { name: string; message: string; stack?: string };
+}
+
+const registry: TestCase[] = [];
+
+let counters: Record<string, number> = { unit: 0, integration: 0, async: 0, upgrade: 0, conformance: 0, lint: 0, edges: 0, registry: 0, graphjson: 0, scripts: 0 };
+
+export function suite(kind: TestKind, category: string) {
+  return {
+    /**
+     * Register a test case.
+     */
+    t(
+      name: string,
+      fn: TestCase["fn"],
+      options: { timeoutMs?: number; finding?: string } = {}
+    ): void {
+      counters[kind] += 1;
+      registry.push({
+        id: `${kind[0].toUpperCase()}${counters[kind]}`,
+        kind,
+        category,
+        name,
+        finding: options.finding,
+        timeoutMs: options.timeoutMs ?? 10_000,
+        fn
+      });
+    }
+  };
+}
+
+export function allTests(): readonly TestCase[] {
+  return registry;
+}
+
+function formatLogValue(value: unknown): string {
+  if (value === undefined) return "";
+  try {
+    return JSON.stringify(value, (_k, v) =>
+      typeof v === "bigint" ? v.toString() : v
+    )!;
+  } catch {
+    return String(value);
+  }
+}
+
+function errorShape(value: unknown): TestResultRecord["error"] {
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack
+    };
+  }
+  return { name: "NonErrorThrow", message: String(value) };
+}
+
+async function withTimeout<T>(
+  operation: Promise<T>,
+  timeoutMs: number,
+  label: string
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const guard = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () =>
+        reject(
+          new Error(
+            `Test "${label}" exceeded harness timeout of ${timeoutMs}ms ` +
+              `(possible engine hang)`
+          )
+        ),
+      timeoutMs
+    );
+  });
+
+  try {
+    return await Promise.race([operation, guard]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+export interface RunSummary {
+  generatedAt: string;
+  nodeVersion: string;
+  durationMs: number;
+  totals: {
+    total: number;
+    passed: number;
+    failed: number;
+    byKind: Record<TestKind, KindTotals>;
+  };
+  byCategory: Array<{
+    category: string;
+    kind: TestKind;
+    total: number;
+    passed: number;
+    failed: number;
+    durationMs: number;
+  }>;
+  unhandledRejections: string[];
+  tests: TestResultRecord[];
+}
+
+export async function runAll(): Promise<RunSummary> {
+  const unhandledRejections: string[] = [];
+
+  const onUnhandled = (reason: unknown) => {
+    unhandledRejections.push(
+      reason instanceof Error
+        ? `${reason.name}: ${reason.message}`
+        : String(reason)
+    );
+  };
+
+  process.on("unhandledRejection", onUnhandled);
+
+  const results: TestResultRecord[] = [];
+  const startedAll = performance.now();
+
+  for (const test of allTests()) {
+    const logs: string[] = [];
+    const ctx: TestContext = {
+      log(message, ...values) {
+        const suffix = values
+          .filter(value => value !== undefined)
+          .map(value => formatLogValue(value))
+          .join(" ; ");
+        logs.push(`${message}${suffix ? ` :: ${suffix}` : ""}`);
+      }
+    };
+
+    const started = performance.now();
+    let record: TestResultRecord;
+
+    try {
+      await withTimeout(
+        Promise.resolve().then(() => test.fn(ctx)),
+        test.timeoutMs,
+        test.name
+      );
+      record = {
+        id: test.id,
+        kind: test.kind,
+        category: test.category,
+        name: test.name,
+        finding: test.finding,
+        status: "passed",
+        durationMs: Math.round((performance.now() - started) * 100) / 100,
+        logs
+      };
+    } catch (error) {
+      record = {
+        id: test.id,
+        kind: test.kind,
+        category: test.category,
+        name: test.name,
+        finding: test.finding,
+        status: "failed",
+        durationMs: Math.round((performance.now() - started) * 100) / 100,
+        logs,
+        error: errorShape(error)
+      };
+    }
+
+    results.push(record);
+
+    const mark = record.status === "passed" ? "PASS" : "FAIL";
+    process.stdout.write(
+      `[${mark}] ${record.id} ${record.category} :: ${record.name} (${record.durationMs}ms)\n`
+    );
+    if (record.error) {
+      process.stdout.write(`        -> ${record.error.name}: ${record.error.message}\n`);
+    }
+  }
+
+  const durationMs = Math.round((performance.now() - startedAll) * 100) / 100;
+
+  // Give detached (non-required) listeners a chance to surface problems
+  // before we snapshot unhandled rejections.
+  await new Promise(resolve => setTimeout(resolve, 50));
+  process.off("unhandledRejection", onUnhandled);
+
+  const categories = new Map<string, RunSummary["byCategory"][number]>();
+
+  for (const record of results) {
+    const key = `${record.kind}::${record.category}`;
+    let entry = categories.get(key);
+    if (!entry) {
+      entry = {
+        category: record.category,
+        kind: record.kind,
+        total: 0,
+        passed: 0,
+        failed: 0,
+        durationMs: 0
+      };
+      categories.set(key, entry);
+    }
+    entry.total += 1;
+    entry.passed += record.status === "passed" ? 1 : 0;
+    entry.failed += record.status === "failed" ? 1 : 0;
+    entry.durationMs = Math.round((entry.durationMs + record.durationMs) * 100) / 100;
+  }
+
+  const byKind = Object.fromEntries(
+    TEST_KINDS.map(kind => {
+      const group = results.filter(record => record.kind === kind);
+      return [
+        kind,
+        {
+          total: group.length,
+          passed: group.filter(record => record.status === "passed").length,
+          failed: group.filter(record => record.status === "failed").length
+        }
+      ];
+    })
+  ) as Record<TestKind, KindTotals>;
+
+  return {
+    generatedAt: new Date().toISOString(),
+    nodeVersion: process.version,
+    durationMs,
+    totals: {
+      total: results.length,
+      passed: results.filter(record => record.status === "passed").length,
+      failed: results.filter(record => record.status === "failed").length,
+      byKind
+    },
+    byCategory: [...categories.values()],
+    unhandledRejections,
+    tests: results
+  };
+}

package/tests/helpers.ts

@@ -0,0 +1,216 @@
+/* ============================================================
+ * Shared fixtures / builders / mocks for the AutomateGraph suite
+ * ============================================================ */
+
+import {
+  EnginePlugin,
+  ErrorPolicy,
+  ExecutionSnapshot,
+  GraphDefinition,
+  NodeContext,
+  NodeDefinition,
+  StoragePlugin
+} from "../src/automategraph";
+
+export const sleep = (ms: number): Promise<void> =>
+  new Promise(resolve => setTimeout(resolve, ms));
+
+/** Generous per-test timeout for engine round-trips (macrotasks + storage). */
+export const BIG = { timeoutMs: 20_000 };
+
+export function node(
+  id: string,
+  run: NodeDefinition["run"],
+  extra: Omit<Partial<NodeDefinition>, "id" | "run"> = {}
+): NodeDefinition {
+  return { id, run, ...extra };
+}
+
+export function constNode(
+  id: string,
+  output: unknown,
+  extra: Omit<Partial<NodeDefinition>, "id" | "run"> = {}
+): NodeDefinition {
+  return node(id, () => output, extra);
+}
+
+export interface GraphSpec {
+  nodes: NodeDefinition[];
+  entryNodes: string[];
+  terminalNodes: string[];
+  id?: string;
+  version?: string;
+  defaultNodeTimeoutMs?: number;
+  errorPolicy?: ErrorPolicy;
+  checkpointEveryNode?: boolean;
+  completionPolicy?: GraphDefinition["completionPolicy"];
+  /** v1.4: graph-local registry merged over the engine's. */
+  functions?: GraphDefinition["functions"];
+}
+
+export function g(spec: GraphSpec): GraphDefinition {
+  const nodes: Record<string, NodeDefinition> = {};
+  for (const definition of spec.nodes) nodes[definition.id] = definition;
+
+  return {
+    id: spec.id ?? "test-graph",
+    version: spec.version ?? "1.0.0",
+    entryNodes: spec.entryNodes,
+    terminalNodes: spec.terminalNodes,
+    nodes,
+    defaultNodeTimeoutMs: spec.defaultNodeTimeoutMs,
+    errorPolicy: spec.errorPolicy,
+    checkpointEveryNode: spec.checkpointEveryNode,
+    completionPolicy: spec.completionPolicy,
+    functions: spec.functions
+  };
+}
+
+/** Linear graph: a -> b -> c ... ; last node is the terminal. */
+export function linear(
+  ids: string[],
+  run?: (id: string, ctx: NodeContext) => unknown,
+  extra: Partial<GraphSpec> = {}
+): GraphDefinition {
+  const nodes = ids.map((id, index) =>
+    node(
+      id,
+      ctx => (run ? run(id, ctx) : `${id}-out`),
+      index < ids.length - 1 ? { next: [ids[index + 1]] } : {}
+    )
+  );
+
+  return g({
+    nodes,
+    entryNodes: [ids[0]],
+    terminalNodes: [ids[ids.length - 1]],
+    ...extra
+  });
+}
+
+/* ------------------------- storages ------------------------- */
+
+/** Records snapshots by reference, can be made to fail on the Nth call. */
+export class SpyStorage implements StoragePlugin {
+  readonly id = "test.spy-storage";
+  readonly version = "9.9.9";
+
+  snapshots: ExecutionSnapshot[] = [];
+  calls = 0;
+  failOn: (callIndex: number, snapshot: ExecutionSnapshot) => boolean =
+    () => false;
+
+  async saveAtomic(snapshot: ExecutionSnapshot): Promise<void> {
+    this.calls += 1;
+    if (this.failOn(this.calls, snapshot)) {
+      throw new Error(`disk-full@${this.calls}`);
+    }
+    this.snapshots.push(snapshot);
+  }
+
+  async load(executionId: string): Promise<ExecutionSnapshot | null> {
+    for (let i = this.snapshots.length - 1; i >= 0; i -= 1) {
+      if (this.snapshots[i].executionId === executionId) {
+        return this.snapshots[i];
+      }
+    }
+    return null;
+  }
+}
+
+/* ------------------------- plugins ------------------------- */
+
+export interface PluginSpec {
+  id: string;
+  version?: string;
+  required?: boolean;
+  onInitialize?: () => Promise<void> | void;
+  onClose?: () => Promise<void> | void;
+}
+
+export function plugin(spec: PluginSpec): EnginePlugin & {
+  events: string[];
+} {
+  const events: string[] = [];
+
+  return {
+    id: spec.id,
+    version: spec.version ?? "1.0.0",
+    required: spec.required,
+    events,
+    async initialize() {
+      events.push(`init:${spec.id}`);
+      await spec.onInitialize?.();
+    },
+    async close() {
+      events.push(`close:${spec.id}`);
+      await spec.onClose?.();
+    }
+  };
+}
+
+/** Plugin with only a close() hook (no initialize). */
+export function closeOnlyPlugin(id: string, events: string[]): EnginePlugin {
+  return {
+    id,
+    version: "1.0.0",
+    async close() {
+      events.push(`close:${id}`);
+    }
+  };
+}
+
+/* ------------------------- event capture ------------------------- */
+
+export interface CapturedEvent {
+  event: string;
+  payload: unknown;
+}
+
+/**
+ * Attaches required listeners (awaited by the bus, therefore
+ * deterministically ordered) and records payloads.
+ */
+export function capture(
+  engine: { events: { on: Function } },
+  eventNames: string[]
+): CapturedEvent[] {
+  const captured: CapturedEvent[] = [];
+
+  for (const name of eventNames) {
+    engine.events.on(
+      name,
+      (payload: unknown) => {
+        captured.push({ event: name, payload });
+      },
+      { required: true }
+    );
+  }
+
+  return captured;
+}
+
+export function errorsOnly(captured: CapturedEvent[]): CapturedEvent[] {
+  return captured.filter(entry => entry.event === "node.failed");
+}
+
+/** Creates an onLog collector for assertions. */
+export function logCollector() {
+  const lines: Array<{ level: string; message: string; details?: unknown }> = [];
+  const onLog = (
+    level: "debug" | "info" | "warn" | "error",
+    message: string,
+    details?: unknown
+  ) => {
+    lines.push({ level, message, details });
+  };
+  return { lines, onLog };
+}
+
+/** A promise that resolves on the next macrotask tick. */
+export const tick = (): Promise<void> =>
+  new Promise(resolve => setImmediate(resolve));
+
+export function sortedIds(values: string[]): string[] {
+  return [...values].sort();
+}