@ontrails/testing 1.0.0-beta.0

package/src/logger.ts

@@ -0,0 +1,125 @@
+/**
+ * Test logger that captures log records for assertion.
+ */
+
+import type { LogLevel, LogMetadata, LogRecord } from '@ontrails/logging';
+
+import type { TestLogger } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Level ordering for filtering
+// ---------------------------------------------------------------------------
+
+const LEVEL_ORDER: Record<string, number> = {
+  debug: 1,
+  error: 4,
+  fatal: 5,
+  info: 2,
+  silent: 6,
+  trace: 0,
+  warn: 3,
+};
+
+// ---------------------------------------------------------------------------
+// Internal factory (shared between root and child loggers)
+// ---------------------------------------------------------------------------
+
+const createTestLoggerInternal = (
+  name: string,
+  minLevel: LogLevel,
+  sharedEntries: LogRecord[],
+  baseMetadata: LogMetadata
+): TestLogger => {
+  const minOrder = LEVEL_ORDER[minLevel] ?? 0;
+
+  const shouldLog = (level: LogLevel): boolean =>
+    (LEVEL_ORDER[level] ?? 0) >= minOrder;
+
+  const log = (
+    level: LogLevel,
+    message: string,
+    metadata?: LogMetadata
+  ): void => {
+    if (!shouldLog(level)) {
+      return;
+    }
+    const record: LogRecord = {
+      category: name,
+      level,
+      message,
+      metadata: { ...baseMetadata, ...metadata },
+      timestamp: new Date(),
+    };
+    sharedEntries.push(record);
+  };
+
+  return {
+    assertLogged(level: LogLevel, messageSubstring: string): void {
+      const match = sharedEntries.find(
+        (r) => r.level === level && r.message.includes(messageSubstring)
+      );
+      if (match === undefined) {
+        throw new Error(
+          `Expected a log entry with level="${level}" containing "${messageSubstring}", but none was found. ` +
+            `Entries: ${JSON.stringify(sharedEntries.map((r) => ({ level: r.level, message: r.message })))}`
+        );
+      }
+    },
+
+    child(metadata: LogMetadata): TestLogger {
+      const merged = { ...baseMetadata, ...metadata };
+      return createTestLoggerInternal(name, minLevel, sharedEntries, merged);
+    },
+
+    clear(): void {
+      sharedEntries.length = 0;
+    },
+
+    debug(message: string, metadata?: LogMetadata): void {
+      log('debug', message, metadata);
+    },
+
+    get entries(): readonly LogRecord[] {
+      return sharedEntries;
+    },
+
+    error(message: string, metadata?: LogMetadata): void {
+      log('error', message, metadata);
+    },
+
+    fatal(message: string, metadata?: LogMetadata): void {
+      log('fatal', message, metadata);
+    },
+
+    find(predicate: (record: LogRecord) => boolean): readonly LogRecord[] {
+      return sharedEntries.filter(predicate);
+    },
+
+    info(message: string, metadata?: LogMetadata): void {
+      log('info', message, metadata);
+    },
+
+    name,
+
+    trace(message: string, metadata?: LogMetadata): void {
+      log('trace', message, metadata);
+    },
+
+    warn(message: string, metadata?: LogMetadata): void {
+      log('warn', message, metadata);
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// createTestLogger
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a test logger that captures all log records in an array.
+ *
+ * Records are not printed. Use `entries`, `find()`, and `assertLogged()`
+ * to inspect what was logged during a test.
+ */
+export const createTestLogger = (options?: { level?: LogLevel }): TestLogger =>
+  createTestLoggerInternal('test', options?.level ?? 'trace', [], {});

package/src/trail.ts

@@ -0,0 +1,116 @@
+/**
+ * testTrail — custom scenario testing for individual trails.
+ *
+ * Use this for edge cases, boundary values, and regression tests
+ * that don't belong in `examples` (which are agent-facing documentation).
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import type { AnyTrail, Result, TrailContext } from '@ontrails/core';
+import { ValidationError, validateInput } from '@ontrails/core';
+
+import {
+  assertErrorMatch,
+  assertFullMatch,
+  assertSchemaMatch,
+  expectOk,
+} from './assertions.js';
+import { mergeTestContext } from './context.js';
+import type { TestScenario } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const assertScenarioResult = (
+  result: Result<unknown, Error>,
+  scenario: TestScenario,
+  trailDef: AnyTrail
+): void => {
+  if (scenario.expectValue !== undefined) {
+    assertFullMatch(result, scenario.expectValue);
+  } else if (scenario.expectErr !== undefined) {
+    assertErrorMatch(result, scenario.expectErr, scenario.expectErrMessage);
+  } else if (scenario.expectErrMessage !== undefined) {
+    expect(result.isErr()).toBe(true);
+    if (result.isErr()) {
+      expect(result.error.message).toContain(scenario.expectErrMessage);
+    }
+  } else if (scenario.expectOk === true) {
+    expect(result.isOk()).toBe(true);
+    assertSchemaMatch(result, trailDef.output);
+  }
+};
+
+/**
+ * Handle input validation failure for a scenario.
+ * Returns true if the error was expected and handled.
+ * Throws if the error was unexpected.
+ */
+const handleValidationError = (
+  validated: Result<unknown, Error>,
+  scenario: TestScenario
+): boolean => {
+  if (!validated.isErr()) {
+    return false;
+  }
+
+  if (scenario.expectErr === ValidationError) {
+    expect(validated.error).toBeInstanceOf(ValidationError);
+    if (scenario.expectErrMessage !== undefined) {
+      expect(validated.error.message).toContain(scenario.expectErrMessage);
+    }
+    return true;
+  }
+
+  throw new Error(
+    `Input validation failed unexpectedly: ${validated.error.message}`
+  );
+};
+
+const runScenario = async (
+  trailDef: AnyTrail,
+  scenario: TestScenario,
+  ctx: Partial<TrailContext> | undefined
+): Promise<void> => {
+  const testCtx = mergeTestContext(ctx);
+  const validated = validateInput(trailDef.input, scenario.input);
+
+  if (handleValidationError(validated, scenario)) {
+    return;
+  }
+  const validatedInput = expectOk(validated);
+
+  const result = await trailDef.implementation(validatedInput, testCtx);
+  assertScenarioResult(result, scenario, trailDef);
+};
+
+// ---------------------------------------------------------------------------
+// testTrail
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a describe block for a trail with one test per scenario.
+ *
+ * ```ts
+ * testTrail(myTrail, [
+ *   { description: "valid input", input: { name: "Alpha" }, expectOk: true },
+ *   { description: "missing name", input: {}, expectErr: ValidationError },
+ * ]);
+ * ```
+ */
+export const testTrail = (
+  trailDef: AnyTrail,
+  scenarios: readonly TestScenario[],
+  ctx?: Partial<TrailContext>
+): void => {
+  describe(trailDef.id, () => {
+    test.each([...scenarios])(
+      '$description',
+      async (scenario: TestScenario) => {
+        await runScenario(trailDef, scenario, ctx);
+      }
+    );
+  });
+};

package/src/types.ts

@@ -0,0 +1,117 @@
+/**
+ * Shared types for @ontrails/testing.
+ */
+
+import type { Logger, Topo } from '@ontrails/core';
+import type { LogLevel, LogRecord } from '@ontrails/logging';
+
+// ---------------------------------------------------------------------------
+// Test Scenario (for testTrail)
+// ---------------------------------------------------------------------------
+
+/** A custom test scenario for a single trail. */
+export interface TestScenario {
+  /** Description shown in test output. */
+  readonly description?: string | undefined;
+  /** Assert the result error has this message (substring match). */
+  readonly expectErrMessage?: string | undefined;
+  /** Assert the result is an error of this type. */
+  readonly expectErr?: (new (...args: never[]) => Error) | undefined;
+  /** Assert the result is ok. */
+  readonly expectOk?: boolean | undefined;
+  /** Assert the result value equals this. */
+  readonly expectValue?: unknown | undefined;
+  /** Input to pass to the implementation. */
+  readonly input: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Hike Scenario (for testHike)
+// ---------------------------------------------------------------------------
+
+/** A test scenario for a hike's composition graph. */
+export interface HikeScenario extends TestScenario {
+  /** Assert these trail IDs were followed, in order. */
+  readonly expectFollowed?: readonly string[] | undefined;
+  /** Assert follow counts per trail ID. */
+  readonly expectFollowedCount?: Readonly<Record<string, number>> | undefined;
+  /** Inject failure from a followed trail's example by description. */
+  readonly injectFromExample?: Readonly<Record<string, string>> | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Test Logger
+// ---------------------------------------------------------------------------
+
+/** A logger that captures entries for assertion in tests. */
+export interface TestLogger extends Logger {
+  /** All log records captured during the test. */
+  readonly entries: readonly LogRecord[];
+  /** Clear captured entries. */
+  clear(): void;
+  /** Find entries matching a predicate. */
+  find(predicate: (record: LogRecord) => boolean): readonly LogRecord[];
+  /** Assert that at least one entry matches. */
+  assertLogged(level: LogLevel, messageSubstring: string): void;
+}
+
+// ---------------------------------------------------------------------------
+// Test Trail Context Options
+// ---------------------------------------------------------------------------
+
+/** Options for creating a test trail context. */
+export interface TestTrailContextOptions {
+  readonly cwd?: string | undefined;
+  readonly env?: Record<string, string> | undefined;
+  readonly logger?: Logger | undefined;
+  readonly requestId?: string | undefined;
+  readonly signal?: AbortSignal | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// CLI Harness
+// ---------------------------------------------------------------------------
+
+/** Options for creating a CLI harness. */
+export interface CliHarnessOptions {
+  readonly app: Topo;
+}
+
+/** A test harness for CLI commands. */
+export interface CliHarness {
+  /** Execute a CLI command string and capture output. */
+  run(command: string): Promise<CliHarnessResult>;
+}
+
+/** The result of a CLI harness command execution. */
+export interface CliHarnessResult {
+  readonly exitCode: number;
+  /** Parsed JSON output if --output json was used. */
+  readonly json?: unknown | undefined;
+  readonly stderr: string;
+  readonly stdout: string;
+}
+
+// ---------------------------------------------------------------------------
+// MCP Harness
+// ---------------------------------------------------------------------------
+
+/** Options for creating an MCP harness. */
+export interface McpHarnessOptions {
+  readonly app: Topo;
+}
+
+/** A test harness for MCP tools. */
+export interface McpHarness {
+  /** Call an MCP tool by name with arguments. */
+  callTool(
+    name: string,
+    args: Record<string, unknown>
+  ): Promise<McpHarnessResult>;
+}
+
+/** The result of an MCP harness tool invocation. */
+export interface McpHarnessResult {
+  readonly content: unknown;
+  readonly isError: boolean;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/all.ts","./src/assertions.ts","./src/context.ts","./src/contracts.ts","./src/detours.ts","./src/examples.ts","./src/harness-cli.ts","./src/harness-mcp.ts","./src/hike.ts","./src/index.ts","./src/logger.ts","./src/trail.ts","./src/types.ts"],"version":"5.9.3"}