@ontrails/testing 0.2.0

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,89 @@
+/**
+ * Shared types for @ontrails/testing.
+ */
+
+import type { AnyTrail, Logger, TraceFn } from '@ontrails/core';
+import type { LogLevel, LogRecord } from '@ontrails/observability';
+
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+// ---------------------------------------------------------------------------
+// Compose Scenario (for testComposes)
+// ---------------------------------------------------------------------------
+
+/** A test scenario for a trail's composing graph. */
+export interface ComposeScenario extends TestScenario {
+  /** Assert these trail IDs were composed, in order. */
+  readonly expectComposed?: readonly string[] | undefined;
+  /** Assert composing counts per trail ID. */
+  readonly expectComposedCount?: Readonly<Record<string, number>> | undefined;
+  /** Inject failure from a composed 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 abortSignal?: AbortSignal | undefined;
+  readonly trace?: TraceFn | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Scenario (for composition testing)
+// ---------------------------------------------------------------------------
+
+/** Marker for compose-step references in scenario inputs. */
+export interface RefToken {
+  readonly __ref: true;
+  readonly path: string;
+}
+
+/** A single step in a scenario. */
+export interface ScenarioStep {
+  readonly compose: AnyTrail;
+  readonly input: Record<string, unknown>;
+  readonly as?: string | undefined;
+  readonly expected?: unknown | undefined;
+  readonly expectedMatch?: unknown | undefined;
+}