@ontrails/testing 1.0.0-beta.0

package/src/all.ts

@@ -0,0 +1,55 @@
+/**
+ * testAll — single-line governance suite for any Topo.
+ *
+ * Wraps topo validation, example execution, contract checks, and detour
+ * verification into one describe block.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import type { Topo, TrailContext } from '@ontrails/core';
+import { validateTopo } from '@ontrails/core';
+
+import { testContracts } from './contracts.js';
+import { testDetours } from './detours.js';
+import { testExamples } from './examples.js';
+
+/**
+ * Run the full governance test suite for a Topo.
+ *
+ * Generates a `governance` describe block containing:
+ * - Structural validation via `validateTopo`
+ * - Example execution via `testExamples`
+ * - Output contract checks via `testContracts`
+ * - Detour target verification via `testDetours`
+ *
+ * Accepts either a static context or a factory function that produces a
+ * fresh context per test (useful when the context contains mutable state
+ * like an in-memory store).
+ *
+ * @example
+ * ```ts
+ * import { testAll } from '@ontrails/testing';
+ * import { app } from '../src/app.js';
+ *
+ * testAll(app);
+ * ```
+ */
+export const testAll = (
+  topo: Topo,
+  ctxOrFactory?: Partial<TrailContext> | (() => Partial<TrailContext>)
+): void => {
+  describe('governance', () => {
+    test('topo validates', () => {
+      const result = validateTopo(topo);
+      expect(result.isOk()).toBe(true);
+    });
+
+    // oxlint-disable-next-line jest/require-hook -- these generate describe/test blocks, not setup code
+    testExamples(topo, ctxOrFactory);
+    // oxlint-disable-next-line jest/require-hook -- these generate describe/test blocks, not setup code
+    testContracts(topo, ctxOrFactory);
+    // oxlint-disable-next-line jest/require-hook -- these generate describe/test blocks, not setup code
+    testDetours(topo);
+  });
+};

package/src/assertions.ts

@@ -0,0 +1,108 @@
+/**
+ * Progressive assertion logic for example-driven testing.
+ *
+ * Three tiers:
+ * 1. Full match — example has `expected` output
+ * 2. Schema-only — no expected output, no error
+ * 3. Error match — example declares an error class name
+ */
+
+import { expect } from 'bun:test';
+
+import type { Result } from '@ontrails/core';
+import { formatZodIssues } from '@ontrails/core';
+import type { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Result narrowing helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Assert that a Result is Ok and return its value.
+ *
+ * Eliminates the `if (result.isOk())` / `as unknown as` dance in tests.
+ *
+ * @example
+ * ```typescript
+ * const value = expectOk(result);
+ * expect(value.name).toBe('Alice');
+ * ```
+ */
+export const expectOk = <T, E>(result: Result<T, E>): T => {
+  expect(result.isOk()).toBe(true);
+  return (result as unknown as { value: T }).value;
+};
+
+/**
+ * Assert that a Result is Err and return its error.
+ *
+ * Eliminates the `if (result.isErr())` / `as unknown as` dance in tests.
+ *
+ * @example
+ * ```typescript
+ * const error = expectErr(result);
+ * expect(error).toBeInstanceOf(ValidationError);
+ * ```
+ */
+export const expectErr = <T, E>(result: Result<T, E>): E => {
+  expect(result.isErr()).toBe(true);
+  return (result as unknown as { error: E }).error;
+};
+
+// ---------------------------------------------------------------------------
+// Full Match
+// ---------------------------------------------------------------------------
+
+/**
+ * Assert that the result is ok and its value deep-equals the expected output.
+ */
+export const assertFullMatch = (
+  result: Result<unknown, Error>,
+  expected: unknown
+): void => {
+  const value = expectOk(result);
+  expect(value).toEqual(expected);
+};
+
+// ---------------------------------------------------------------------------
+// Schema-Only Match
+// ---------------------------------------------------------------------------
+
+/**
+ * Assert that the result is ok and, if an output schema is provided,
+ * the value parses against it.
+ */
+export const assertSchemaMatch = (
+  result: Result<unknown, Error>,
+  outputSchema: z.ZodType | undefined
+): void => {
+  const value = expectOk(result);
+  if (outputSchema !== undefined) {
+    const parsed = outputSchema.safeParse(value);
+    if (!parsed.success) {
+      throw new Error(
+        `Output does not match schema: ${formatZodIssues(parsed.error.issues).join('; ')}`
+      );
+    }
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Error Match
+// ---------------------------------------------------------------------------
+
+/**
+ * Assert that the result is an error of the specified type, with optional
+ * message substring matching.
+ */
+export const assertErrorMatch = (
+  result: Result<unknown, Error>,
+  expectedError: new (...args: never[]) => Error,
+  expectedMessage?: string
+): void => {
+  const error = expectErr(result);
+  expect(error).toBeInstanceOf(expectedError);
+  if (expectedMessage !== undefined) {
+    expect(error.message).toContain(expectedMessage);
+  }
+};

package/src/context.ts

@@ -0,0 +1,42 @@
+/**
+ * Test context factory for creating TrailContext instances suitable for testing.
+ */
+
+import type { TrailContext } from '@ontrails/core';
+
+import { createTestLogger } from './logger.js';
+import type { TestTrailContextOptions } from './types.js';
+
+// ---------------------------------------------------------------------------
+// createTestContext
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a TrailContext with deterministic, test-friendly defaults.
+ *
+ * - `requestId`: `"test-request-001"` (deterministic)
+ * - `logger`: a `TestLogger` that captures entries
+ * - `signal`: a non-aborted AbortController signal
+ */
+export const createTestContext = (
+  overrides?: TestTrailContextOptions
+): TrailContext => ({
+  env: overrides?.env ?? { TRAILS_ENV: 'test' },
+  logger: overrides?.logger ?? createTestLogger(),
+  requestId: overrides?.requestId ?? 'test-request-001',
+  signal: overrides?.signal ?? new AbortController().signal,
+  workspaceRoot: overrides?.cwd ?? process.cwd(),
+});
+
+/**
+ * Merge a Partial<TrailContext> into a test context.
+ * Used internally when the public API accepts Partial<TrailContext>.
+ */
+export const mergeTestContext = (ctx?: Partial<TrailContext>): TrailContext => {
+  if (ctx === undefined) {
+    return createTestContext();
+  }
+
+  const base = createTestContext();
+  return { ...base, ...ctx };
+};

package/src/contracts.ts

@@ -0,0 +1,85 @@
+/**
+ * testContracts — output schema verification.
+ *
+ * For every trail that has both examples and an output schema,
+ * run each example and validate the implementation output against
+ * the declared schema.
+ */
+
+import { describe, test } from 'bun:test';
+
+import type { Topo, TrailExample, Trail, TrailContext } from '@ontrails/core';
+import { formatZodIssues, validateInput } from '@ontrails/core';
+import type { z } from 'zod';
+
+import { expectOk } from './assertions.js';
+import { mergeTestContext } from './context.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const validateOutputSchema = (
+  outputSchema: z.ZodType,
+  value: unknown,
+  trailId: string,
+  exampleName: string
+): void => {
+  const parsed = outputSchema.safeParse(value);
+  if (!parsed.success) {
+    const issues = formatZodIssues(parsed.error.issues);
+    throw new Error(
+      `Output schema violation for trail "${trailId}", example "${exampleName}":\n${issues.map((i) => `  - ${i}`).join('\n')}\n\nActual output: ${JSON.stringify(value, null, 2)}`
+    );
+  }
+};
+
+// ---------------------------------------------------------------------------
+// testContracts
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify that every trail's implementation output matches its declared
+ * output schema. Catches implementation-schema drift.
+ *
+ * Trails without output schemas or examples are skipped.
+ */
+export const testContracts = (
+  app: Topo,
+  ctxOrFactory?: Partial<TrailContext> | (() => Partial<TrailContext>)
+): void => {
+  const resolveCtx =
+    typeof ctxOrFactory === 'function' ? ctxOrFactory : () => ctxOrFactory;
+  const trailEntries = [...app.trails];
+
+  describe('contracts', () => {
+    describe.each(trailEntries)('%s', (_id, trailDef) => {
+      const t = trailDef as Trail<unknown, unknown>;
+
+      if (t.output === undefined) {
+        return;
+      }
+      if (t.examples === undefined || t.examples.length === 0) {
+        return;
+      }
+
+      const { examples, output: outputSchema } = t;
+      const successExamples = examples.filter((e) => e.error === undefined);
+
+      test.each(successExamples)(
+        'contract: $name',
+        async (example: TrailExample<unknown, unknown>) => {
+          const testCtx = mergeTestContext(resolveCtx());
+
+          const validated = validateInput(t.input, example.input);
+          const validatedInput = expectOk(validated);
+
+          const result = await t.implementation(validatedInput, testCtx);
+          const resultValue = expectOk(result);
+
+          validateOutputSchema(outputSchema, resultValue, t.id, example.name);
+        }
+      );
+    });
+  });
+};

package/src/detours.ts

@@ -0,0 +1,44 @@
+/**
+ * testDetours — verify that all detour targets exist in the topo.
+ *
+ * Pure structural validation. No implementation execution needed.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import type { Topo, Trail } from '@ontrails/core';
+
+// ---------------------------------------------------------------------------
+// testDetours
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify that every trail's detour targets reference trails that
+ * actually exist in the app's topo.
+ */
+export const testDetours = (app: Topo): void => {
+  const trailEntries = [...app.trails];
+
+  describe('detours', () => {
+    describe.each(trailEntries)('%s', (_id, trailDef) => {
+      const t = trailDef as Trail<unknown, unknown>;
+
+      if (t.detours === undefined) {
+        return;
+      }
+
+      const { detours } = t;
+      const testCases = Object.entries(detours).flatMap(
+        ([detourName, targets]) =>
+          targets.map((targetId) => ({ detourName, targetId }))
+      );
+
+      test.each(testCases)(
+        'detour "$detourName" -> "$targetId" exists',
+        ({ targetId }) => {
+          expect(app.has(targetId)).toBe(true);
+        }
+      );
+    });
+  });
+};

package/src/examples.ts

@@ -0,0 +1,314 @@
+/**
+ * testExamples — the headline one-liner.
+ *
+ * Iterates every trail in the app's topo. For each trail with examples,
+ * generates describe/test blocks using bun:test. Progressive assertion
+ * determines which check to run per example. For hikes with `follows`
+ * declarations, checks that every declared follow was called at least once.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import type {
+  AnyHike,
+  FollowFn,
+  Topo,
+  TrailExample,
+  Trail,
+  TrailContext,
+} from '@ontrails/core';
+
+import {
+  AlreadyExistsError,
+  AmbiguousError,
+  AssertionError,
+  AuthError,
+  CancelledError,
+  ConflictError,
+  InternalError,
+  NetworkError,
+  NotFoundError,
+  PermissionError,
+  RateLimitError,
+  Result,
+  TimeoutError,
+  TrailsError,
+  ValidationError,
+  validateInput,
+} from '@ontrails/core';
+import type { z } from 'zod';
+
+import {
+  assertErrorMatch,
+  assertFullMatch,
+  assertSchemaMatch,
+  expectOk,
+} from './assertions.js';
+import { mergeTestContext } from './context.js';
+
+// ---------------------------------------------------------------------------
+// Error class name -> constructor map
+// ---------------------------------------------------------------------------
+
+const ERROR_MAP: Record<string, new (...args: never[]) => Error> = {
+  AlreadyExistsError: AlreadyExistsError as new (...args: never[]) => Error,
+  AmbiguousError: AmbiguousError as new (...args: never[]) => Error,
+  AssertionError: AssertionError as new (...args: never[]) => Error,
+  AuthError: AuthError as new (...args: never[]) => Error,
+  CancelledError: CancelledError as new (...args: never[]) => Error,
+  ConflictError: ConflictError as new (...args: never[]) => Error,
+  InternalError: InternalError as new (...args: never[]) => Error,
+  NetworkError: NetworkError as new (...args: never[]) => Error,
+  NotFoundError: NotFoundError as new (...args: never[]) => Error,
+  PermissionError: PermissionError as new (...args: never[]) => Error,
+  RateLimitError: RateLimitError as new (...args: never[]) => Error,
+  TimeoutError: TimeoutError as new (...args: never[]) => Error,
+  TrailsError: TrailsError as unknown as new (...args: never[]) => Error,
+  ValidationError: ValidationError as new (...args: never[]) => Error,
+};
+
+/**
+ * Resolve an error class name string to the actual constructor.
+ * Falls back to generic Error if the name is not in the core taxonomy.
+ */
+const resolveErrorClass = (name: string): (new (...args: never[]) => Error) =>
+  ERROR_MAP[name] ?? (Error as new (...args: never[]) => Error);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const assertProgressiveMatch = (
+  result: Result<unknown, Error>,
+  example: TrailExample<unknown, unknown>,
+  output: z.ZodType | undefined
+): void => {
+  if (example.expected !== undefined) {
+    assertFullMatch(result, example.expected);
+    return;
+  }
+
+  if (example.error !== undefined) {
+    const errorClass = resolveErrorClass(example.error);
+    assertErrorMatch(result, errorClass);
+    return;
+  }
+
+  assertSchemaMatch(result, output);
+};
+
+/**
+ * Handle input validation failure for an example.
+ * Returns true if the validation error was expected (and assertions passed).
+ * Throws if the validation error was unexpected.
+ */
+const handleValidationError = (
+  validated: Result<unknown, Error>,
+  example: TrailExample<unknown, unknown>
+): boolean => {
+  if (!validated.isErr()) {
+    return false;
+  }
+
+  if (example.error !== undefined) {
+    const errorClass = resolveErrorClass(example.error);
+    expect(validated.error).toBeInstanceOf(errorClass);
+    return true;
+  }
+
+  throw new Error(
+    `Example "${example.name}" has invalid input: ${validated.error.message}`
+  );
+};
+
+/**
+ * Run a single example against a trail.
+ * Handles validation, execution, and assertions.
+ */
+const runExample = async (
+  t: Trail<unknown, unknown>,
+  example: TrailExample<unknown, unknown>,
+  output: z.ZodType | undefined,
+  testCtx: TrailContext
+): Promise<void> => {
+  const validated = validateInput(t.input, example.input);
+
+  if (handleValidationError(validated, example)) {
+    return;
+  }
+  const validatedInput = expectOk(validated);
+
+  const result = await t.implementation(validatedInput, testCtx);
+  assertProgressiveMatch(result, example, output);
+};
+
+// ---------------------------------------------------------------------------
+// Follows coverage for hikes
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a recording follow function that tracks which trail IDs are called.
+ *
+ * Delegates to `baseFollow` when available, otherwise looks up the trail
+ * in the topo and executes it with validated input. Falls back to
+ * `Result.ok()` when neither is available.
+ */
+const createCoverageFollow = (
+  called: Set<string>,
+  baseFollow: FollowFn | undefined,
+  topo: Topo,
+  ctx: TrailContext
+): FollowFn => {
+  const follow = (id: string, input: unknown) => {
+    called.add(id);
+
+    if (baseFollow !== undefined) {
+      return baseFollow(id, input);
+    }
+
+    const trailDef = topo.get(id);
+    if (trailDef !== undefined) {
+      const validated = validateInput(trailDef.input, input);
+      if (validated.isErr()) {
+        return Promise.resolve(validated);
+      }
+      return Promise.resolve(trailDef.implementation(validated.value, ctx));
+    }
+
+    return Promise.resolve(Result.ok());
+  };
+  return follow as FollowFn;
+};
+
+/**
+ * Run a single example against a hike, recording follow calls.
+ */
+const runHikeExample = async (
+  hikeDef: AnyHike,
+  example: TrailExample<unknown, unknown>,
+  output: z.ZodType | undefined,
+  baseCtx: TrailContext,
+  called: Set<string>,
+  topo: Topo
+): Promise<void> => {
+  const validated = validateInput(hikeDef.input, example.input);
+
+  if (handleValidationError(validated, example)) {
+    return;
+  }
+  const validatedInput = expectOk(validated);
+
+  const follow = createCoverageFollow(called, baseCtx.follow, topo, baseCtx);
+  const testCtx: TrailContext = { ...baseCtx, follow };
+
+  const result = await hikeDef.implementation(validatedInput, testCtx);
+  assertProgressiveMatch(result, example, output);
+};
+
+// ---------------------------------------------------------------------------
+// Hike entry with examples pre-validated
+// ---------------------------------------------------------------------------
+
+interface HikeWithExamples {
+  readonly hikeDef: AnyHike;
+  readonly hikeId: string;
+  readonly examples: readonly TrailExample<unknown, unknown>[];
+}
+
+const collectHikesWithExamples = (app: Topo): readonly HikeWithExamples[] =>
+  [...app.hikes]
+    .filter(([, h]) => h.examples !== undefined && h.examples.length > 0)
+    .map(([hikeId, hikeDef]) => ({
+      examples: hikeDef.examples as readonly TrailExample<unknown, unknown>[],
+      hikeDef,
+      hikeId,
+    }));
+
+// ---------------------------------------------------------------------------
+// Hike example describe blocks
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate describe/test blocks for hikes with follows coverage.
+ *
+ * Always uses a recording follow so that follows coverage can be checked.
+ * Hikes without `follows` still run their examples but skip the coverage test.
+ */
+const describeHikeExamples = (
+  hikesWithExamples: readonly HikeWithExamples[],
+  resolveCtx: () => Partial<TrailContext> | undefined,
+  topo: Topo
+): void => {
+  if (hikesWithExamples.length === 0) {
+    return;
+  }
+
+  describe.each([...hikesWithExamples])('$hikeId', ({ hikeDef, examples }) => {
+    const called = new Set<string>();
+
+    test.each([...examples])(
+      'example: $name',
+      async (example: TrailExample<unknown, unknown>) => {
+        const baseCtx = mergeTestContext(resolveCtx());
+        await runHikeExample(
+          hikeDef,
+          example,
+          hikeDef.output,
+          baseCtx,
+          called,
+          topo
+        );
+      }
+    );
+
+    if (hikeDef.follows.length > 0) {
+      test('follows coverage', () => {
+        const uncovered = hikeDef.follows.filter((id) => !called.has(id));
+        expect(uncovered).toEqual([]);
+      });
+    }
+  });
+};
+
+// ---------------------------------------------------------------------------
+// testExamples
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate describe/test blocks for every trail example in the app.
+ *
+ * For hikes with `follows` declarations and examples, also verifies that
+ * every declared follow ID was called at least once across all examples.
+ *
+ * One line in your test file:
+ * ```ts
+ * testExamples(app);
+ * ```
+ */
+export const testExamples = (
+  app: Topo,
+  ctxOrFactory?: Partial<TrailContext> | (() => Partial<TrailContext>)
+): void => {
+  const resolveCtx =
+    typeof ctxOrFactory === 'function' ? ctxOrFactory : () => ctxOrFactory;
+  const trailEntries = [...app.trails];
+
+  describe.each(trailEntries)('%s', (_id, trailDef) => {
+    const t = trailDef as Trail<unknown, unknown>;
+    if (t.examples === undefined || t.examples.length === 0) {
+      return;
+    }
+
+    const { examples, output } = t;
+
+    test.each([...examples])(
+      'example: $name',
+      async (example: TrailExample<unknown, unknown>) => {
+        const testCtx = mergeTestContext(resolveCtx());
+        await runExample(t, example, output, testCtx);
+      }
+    );
+  });
+
+  describeHikeExamples(collectHikesWithExamples(app), resolveCtx, app);
+};