@ontrails/testing 1.0.0-beta.18 → 1.0.0-beta.19

package/src/errors.ts

@@ -0,0 +1,47 @@
+import {
+  errorClasses,
+  InternalError,
+  RetryExhaustedError,
+  TrailsError,
+} from '@ontrails/core';
+
+type ErrorConstructor = new (...args: never[]) => Error;
+type MessageErrorConstructor = new (message: string) => Error;
+
+const ERROR_CLASS_BY_NAME = new Map<string, ErrorConstructor>([
+  ...errorClasses.map(
+    (entry) => [entry.name, entry.ctor as ErrorConstructor] as const
+  ),
+  ['TrailsError', TrailsError as unknown as ErrorConstructor],
+]);
+
+/**
+ * Resolve an error class name string to the actual constructor.
+ * Falls back to generic Error if the name is not in the core taxonomy.
+ */
+export const resolveErrorClass = (name: string): ErrorConstructor =>
+  ERROR_CLASS_BY_NAME.get(name) ?? (Error as ErrorConstructor);
+
+/**
+ * Create an error instance for an authored example error name.
+ */
+export const createErrorFromName = (name: string): Error => {
+  if (name === 'TrailsError') {
+    return new InternalError(name);
+  }
+
+  const entry = errorClasses.find((candidate) => candidate.name === name);
+  if (entry === undefined) {
+    return new Error(name);
+  }
+
+  if (entry.name === 'RetryExhaustedError') {
+    return new RetryExhaustedError(new InternalError(name), {
+      attempts: 1,
+      detour: 'testComposes',
+    });
+  }
+
+  const ErrorClass = entry.ctor as unknown as MessageErrorConstructor;
+  return new ErrorClass(name);
+};

package/src/examples.ts

@@ -3,14 +3,16 @@
  *
  * 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 trails with `crosses`
- * declarations, checks that every declared crossing was called at least once.
+ * determines which check to run per example. For trails with `composes`
+ * declarations, checks that every declared composing was called at least once.
  */
 
 import { describe, expect, test } from 'bun:test';
 
 import type {
-  CrossFn,
+  ComposeFn,
+  ComposeOptions,
+  ExecuteTrailOptions,
   ResourceOverrideMap,
   Topo,
   TrailExample,
@@ -19,25 +21,10 @@ import type {
 } from '@ontrails/core';
 
 import {
-  AlreadyExistsError,
-  AmbiguousError,
-  AssertionError,
-  AuthError,
-  buildCrossValidationSchema,
-  CancelledError,
-  ConflictError,
-  DerivationError,
-  InternalError,
-  NetworkError,
-  NotFoundError,
-  PermissionError,
-  PermitError,
-  RateLimitError,
-  RetryExhaustedError,
+  buildComposeValidationSchema,
   executeTrail,
+  parseTrailIdVersionReference,
   Result,
-  TimeoutError,
-  TrailsError,
   ValidationError,
   validateInput,
 } from '@ontrails/core';
@@ -57,42 +44,18 @@ import {
   createMockResources,
 } from './context.js';
 import type { PermittedTrail, TestExecutionOptions } from './context.js';
-import { isDerivedExample, deriveTrailExamples } from './effective-examples.js';
+import {
+  deriveTrailExampleTargets,
+  isDerivedExample,
+} from './effective-examples.js';
+import type { TrailExampleTarget } from './effective-examples.js';
+import { resolveErrorClass } from './errors.js';
 import { withSignalAssertions } from './signals.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,
-  DerivationError: DerivationError 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,
-  PermitError: PermitError as new (...args: never[]) => Error,
-  RateLimitError: RateLimitError as new (...args: never[]) => Error,
-  RetryExhaustedError: RetryExhaustedError as unknown 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,
+type TestingExecuteTrailOptions = ExecuteTrailOptions & {
+  readonly validationSchema?: ReturnType<typeof buildComposeValidationSchema>;
 };
 
-/**
- * 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
 // ---------------------------------------------------------------------------
@@ -161,21 +124,17 @@ const applyAutoPermit = (
   return { ...ctx, permit };
 };
 
-/**
- * Run a single example against a trail.
- * Handles validation, execution, and assertions.
- */
-export const runExample = async (
-  t: Trail<unknown, unknown, unknown>,
+const runTargetExample = async (
+  target: TrailExampleTarget,
   example: TrailExample<unknown, unknown>,
-  output: z.ZodType | undefined,
   testCtx: TrailContext,
   resources?: ResourceOverrideMap,
   opts?: TestExecutionOptions
 ): Promise<void> => {
+  const { output, trail: t } = target;
   const ctx = opts ? applyAutoPermit(testCtx, t, opts) : testCtx;
   const signals = withSignalAssertions(ctx, example);
-  const validated = validateInput(t.input, example.input);
+  const validated = validateInput(target.input, example.input);
 
   if (handleValidationError(validated, example)) {
     signals.assert();
@@ -185,118 +144,176 @@ export const runExample = async (
   const result = await executeTrail(t, example.input, {
     ctx: signals.ctx,
     resources: resources ?? opts?.resources,
+    ...(target.version === undefined ? {} : { version: target.version }),
   });
   assertProgressiveMatch(result, example, output);
   signals.assert();
 };
 
+/**
+ * Run a single example against a trail.
+ * Handles validation, execution, and assertions.
+ */
+export const runExample = async (
+  t: Trail<unknown, unknown, unknown>,
+  example: TrailExample<unknown, unknown>,
+  output: z.ZodType | undefined,
+  testCtx: TrailContext,
+  resources?: ResourceOverrideMap,
+  opts?: TestExecutionOptions
+): Promise<void> => {
+  await runTargetExample(
+    {
+      composes: t.composes,
+      current: true,
+      examples: [example],
+      id: t.id,
+      input: t.input,
+      output,
+      trail: t,
+    },
+    example,
+    testCtx,
+    resources,
+    opts
+  );
+};
+
 // ---------------------------------------------------------------------------
-// Crossing coverage for trails with crossings
+// Composing coverage for trails with compositions
 // ---------------------------------------------------------------------------
 
 /**
- * Build a recording cross function that tracks which trail IDs are called.
+ * Build a recording compose function that tracks which trail IDs are called.
  *
- * Delegates to `baseCross` when available, otherwise looks up the trail
+ * Delegates to `baseCompose` 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 createCoverageCross = (
+const createCoverageCompose = (
   called: Set<string>,
-  baseCross: CrossFn | undefined,
+  baseCompose: ComposeFn | undefined,
   topo: Topo,
   ctx: TrailContext,
   resources?: ResourceOverrideMap
-): CrossFn => {
-  const invokeCross = async (
+): ComposeFn => {
+  const invokeCompose = async (
     idOrTrail: string | { readonly id: string },
     input: unknown,
-    self: CrossFn
+    self: ComposeFn,
+    composeOptions?: ComposeOptions | undefined
   ) => {
-    const id = typeof idOrTrail === 'string' ? idOrTrail : idOrTrail.id;
-    called.add(id);
+    const parsed =
+      typeof idOrTrail === 'string'
+        ? parseTrailIdVersionReference(idOrTrail)
+        : Result.ok({ id: idOrTrail.id });
+    if (parsed.isErr()) {
+      return parsed;
+    }
+    const parsedVersion =
+      'version' in parsed.value ? parsed.value.version : undefined;
+    if (parsedVersion !== undefined && composeOptions?.version !== undefined) {
+      return Result.err(
+        new ValidationError(
+          `Trail "${parsed.value.id}" version was provided both in the id reference and ctx.compose() options`
+        )
+      );
+    }
 
-    if (baseCross !== undefined) {
-      return await baseCross(id, input);
+    const { id } = parsed.value;
+    called.add(id);
+    const version = composeOptions?.version ?? parsedVersion;
+
+    if (baseCompose !== undefined) {
+      const forwardedOptions =
+        parsedVersion === undefined
+          ? composeOptions
+          : { ...composeOptions, version: parsedVersion };
+      return await baseCompose(id, input, forwardedOptions);
     }
 
     const trailDef = topo.get(id);
     if (trailDef !== undefined) {
-      return await executeTrail(trailDef, input, {
-        ctx: { ...ctx, cross: self },
+      const options: TestingExecuteTrailOptions = {
+        ctx: { ...ctx, compose: self },
         resources,
-        validationSchema: buildCrossValidationSchema(trailDef),
-      });
+        ...(version === undefined ? {} : { version }),
+        validationSchema: buildComposeValidationSchema(trailDef),
+      };
+      return await executeTrail(trailDef, input, options);
     }
 
     return Result.ok();
   };
 
-  // Accepts either a trail object (typed cross), a string id (untyped),
+  // Accepts either a trail object (typed compose), a string id (untyped),
   // or a batch of `[target, input]` tuples.
-  const cross = async function cross(
+  const compose = async function compose(
     idOrTrail:
       | string
       | { readonly id: string }
       | readonly (readonly [string | { readonly id: string }, unknown])[],
-    input?: unknown
+    inputOrOptions?: unknown,
+    singleOptions?: ComposeOptions
   ) {
     if (Array.isArray(idOrTrail)) {
       return await Promise.all(
         idOrTrail.map(([target, batchInput]) =>
-          invokeCross(target, batchInput, cross as CrossFn)
+          invokeCompose(target, batchInput, compose as ComposeFn)
         )
       );
     }
 
-    return await invokeCross(
+    return await invokeCompose(
       idOrTrail as string | { readonly id: string },
-      input,
-      cross as CrossFn
+      inputOrOptions,
+      compose as ComposeFn,
+      singleOptions
     );
-  } as CrossFn;
+  } as ComposeFn;
 
-  return cross;
+  return compose;
 };
 
 /**
- * Run a single example against a trail with crossings, recording cross calls.
+ * Run a single example against a trail with compositions, recording compose calls.
  */
 const runCompositionExample = async (
-  trailDef: Trail<unknown, unknown, unknown>,
+  target: TrailExampleTarget,
   example: TrailExample<unknown, unknown>,
-  output: z.ZodType | undefined,
   baseCtx: TrailContext,
   called: Set<string>,
   topo: Topo,
   resources?: ResourceOverrideMap,
   opts?: TestExecutionOptions
 ): Promise<void> => {
+  const { output, trail: trailDef } = target;
   const permittedCtx = opts
     ? applyAutoPermit(baseCtx, trailDef, opts)
     : baseCtx;
   const signals = withSignalAssertions(permittedCtx, example);
-  const validated = validateInput(trailDef.input, example.input);
+  const validated = validateInput(target.input, example.input);
 
   if (handleValidationError(validated, example)) {
     signals.assert();
     return;
   }
 
-  const cross = createCoverageCross(
+  const compose = createCoverageCompose(
     called,
-    signals.ctx.cross,
+    signals.ctx.compose,
     topo,
     signals.ctx,
     resources
   );
-  const testCtx: TrailContext = { ...signals.ctx, cross };
+  const testCtx: TrailContext = { ...signals.ctx, compose };
 
-  // Top-level trail validates against trail.input (not merged crossInput).
-  // Merged validation only applies to cross targets in executeFromMap/createCoverageCross.
+  // Top-level trail validates against trail.input (not merged composeInput).
+  // Merged validation only applies to compose targets in executeFromMap/createCoverageCompose.
   const result = await executeTrail(trailDef, example.input, {
     ctx: testCtx,
     resources: resources ?? opts?.resources,
+    ...(target.version === undefined ? {} : { version: target.version }),
   });
   assertProgressiveMatch(result, example, output);
   signals.assert();
@@ -309,8 +326,8 @@ const runCompositionExample = async (
 /**
  * Generate describe/test blocks for every trail example in the app.
  *
- * For trails with `crosses` declarations and examples, also verifies that
- * every declared crossed ID was called at least once across all examples.
+ * For trails with `composes` declarations and examples, also verifies that
+ * every declared composed ID was called at least once across all examples.
  *
  * One line in your test file:
  * ```ts
@@ -327,18 +344,15 @@ export const testExamples = (
   const resolveInput =
     typeof ctxOrFactory === 'function' ? ctxOrFactory : () => ctxOrFactory;
   const withExamples = (app.list() as Trail<unknown, unknown, unknown>[])
-    .map((trailDef) => ({
-      ...trailDef,
-      examples: deriveTrailExamples(trailDef),
-    }))
-    .filter((trailDef) => trailDef.examples.length > 0);
-  const simpleTrails = withExamples.filter((t) => t.crosses.length === 0);
-  const compositionTrails = withExamples.filter((t) => t.crosses.length > 0);
+    .flatMap(deriveTrailExampleTargets)
+    .filter((target) => target.examples.length > 0);
+  const simpleTrails = withExamples.filter((t) => t.composes.length === 0);
+  const compositionTrails = withExamples.filter((t) => t.composes.length > 0);
 
   // Simple trails: run examples directly
   if (simpleTrails.length > 0) {
     describe.each(simpleTrails)('$id', (t) => {
-      const { examples, output } = t;
+      const { examples } = t;
       if (!examples) {
         return;
       }
@@ -353,42 +367,42 @@ export const testExamples = (
             resolved.resources
           );
           const testCtx = mergeTestContext(resolved.ctx);
-          await runExample(t, example, output, testCtx, resources, resolved);
+          await runTargetExample(t, example, testCtx, resources, resolved);
         }
       );
     });
   }
 
-  // Composition trails: use recording cross and check coverage.
+  // Composition trails: use recording compose and check coverage.
   //
-  // Crossing coverage only runs against AUTHORED examples. Contour-derived
+  // Composing coverage only runs against AUTHORED examples. Contour-derived
   // fixtures are opportunistic coverage that may not exercise every
-  // `ctx.cross()` branch in the trail, so asserting coverage against them
+  // `ctx.compose()` branch in the trail, so asserting coverage against them
   // would produce false failures for trails whose authored intent was a
   // single path. When a trail has zero authored examples the coverage
   // assertion is skipped entirely — the derived-example runs still
-  // execute, but they are not required to cover declared crossings.
+  // execute, but they are not required to cover declared compositions.
   if (compositionTrails.length > 0) {
     describe.each(compositionTrails)('$id', (t) => {
-      const { examples, output } = t;
+      const { examples } = t;
       if (!examples) {
         return;
       }
 
-      const calledFromAuthored = new Set<string>();
+      const composedFromAuthored = new Set<string>();
       const hasAuthoredExamples = examples.some(
         (example) => !isDerivedExample(example)
       );
 
-      // Only record cross calls from authored examples. Derived fixtures
+      // Only record compose calls from authored examples. Derived fixtures
       // execute normally but do not contribute to coverage — the sink map
-      // routes each example to the right bucket without an inline
+      // puts each example in the right bucket without an inline
       // conditional inside the test body.
       const discardSink = new Set<string>();
       const pickCoverageSink = (
         example: TrailExample<unknown, unknown>
       ): Set<string> =>
-        isDerivedExample(example) ? discardSink : calledFromAuthored;
+        isDerivedExample(example) ? discardSink : composedFromAuthored;
 
       test.each([...examples])(
         'example: $name',
@@ -403,7 +417,6 @@ export const testExamples = (
           await runCompositionExample(
             t,
             example,
-            output,
             baseCtx,
             pickCoverageSink(example),
             app,
@@ -414,9 +427,9 @@ export const testExamples = (
       );
 
       if (hasAuthoredExamples) {
-        test('crossing coverage', () => {
-          const uncovered = t.crosses.filter(
-            (id) => !calledFromAuthored.has(id)
+        test('composing coverage', () => {
+          const uncovered = t.composes.filter(
+            (id) => !composedFromAuthored.has(id)
           );
           expect(uncovered).toEqual([]);
         });

package/src/harness-cli.ts

@@ -6,16 +6,42 @@
  */
 
 import { deriveCliCommands } from '@ontrails/cli';
-import type { CliCommand } from '@ontrails/cli';
-import type { TrailContext } from '@ontrails/core';
+import type { CliCommand, DeriveCliCommandsOptions } from '@ontrails/cli';
+import type { Topo, TrailContext } from '@ontrails/core';
 import { projectPublicSurfaceError } from '@ontrails/core';
 
 import { mergeTestContext } from './context.js';
-import type {
-  CliHarness,
-  CliHarnessOptions,
-  CliHarnessResult,
-} from './types.js';
+
+/** Options for creating a CLI harness. */
+export interface CliHarnessOptions extends Omit<
+  DeriveCliCommandsOptions,
+  'onResult' | 'presets' | 'resolveInput'
+> {
+  readonly ctx?: Partial<TrailContext> | undefined;
+  readonly graph: 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 error?:
+    | {
+        readonly category: string;
+        readonly code: string;
+        readonly message: string;
+      }
+    | undefined;
+  readonly exitCode: number;
+  /** Parsed JSON output if --output json was used. */
+  readonly json?: unknown | undefined;
+  readonly stderr: string;
+  readonly stdout: string;
+}
 
 // ---------------------------------------------------------------------------
 // Tokenizer
@@ -288,6 +314,8 @@ const runCommand = async (
  * that parses command strings and executes them in-process.
  *
  * ```ts
+ * import { createCliHarness } from '@ontrails/testing/cli';
+ *
  * const harness = createCliHarness({ graph });
  * const result = await harness.run("entity show --name Alpha --output json");
  * expect(result.exitCode).toBe(0);

package/src/harness-http.ts

@@ -6,18 +6,96 @@
  */
 
 import { deriveHttpRoutes } from '@ontrails/http';
-import type { HttpMethod, HttpRouteDefinition } from '@ontrails/http';
-import type { TrailContext, TrailContextInit } from '@ontrails/core';
+import type {
+  DeriveHttpRoutesOptions,
+  HttpHeaderSource,
+  HttpMethod,
+  HttpRouteDefinition,
+} from '@ontrails/http';
+import type { Topo, TrailContext, TrailContextInit } from '@ontrails/core';
 import { NotFoundError, projectPublicSurfaceError } from '@ontrails/core';
 
 import { mergeTestContext } from './context.js';
-import type {
-  HttpHarness,
-  HttpHarnessOptions,
+
+/** Options for creating an HTTP harness. */
+export interface HttpHarnessOptions extends DeriveHttpRoutesOptions {
+  readonly ctx?: Partial<TrailContext> | undefined;
+  readonly graph: Topo;
+}
+
+export interface HttpHarnessRequest {
+  readonly abortSignal?: AbortSignal | undefined;
+  readonly body?: unknown | undefined;
+  readonly headers?: HttpHeaderSource | undefined;
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly query?: Record<string, unknown> | undefined;
+  readonly requestId?: string | undefined;
+}
+
+export interface HttpHarnessRequestOptions extends Omit<
   HttpHarnessRequest,
-  HttpHarnessRequestOptions,
-  HttpHarnessResult,
-} from './types.js';
+  'body' | 'method' | 'path' | 'query'
+> {
+  readonly query?: Record<string, unknown> | undefined;
+}
+
+/** A test harness for HTTP route projections. */
+export interface HttpHarness {
+  /** Execute a raw HTTP-style harness request. */
+  request(request: HttpHarnessRequest): Promise<HttpHarnessResult>;
+  /** Execute a GET request, reading input from query params. */
+  get(
+    path: string,
+    query?: Record<string, unknown>,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a POST request, reading input from the JSON-like body value. */
+  post(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a PUT request. */
+  put(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a PATCH request. */
+  patch(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a DELETE request. */
+  delete(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+}
+
+export interface HttpHarnessErrorBody {
+  readonly error: {
+    readonly category: string;
+    readonly code: string;
+    readonly message: string;
+  };
+}
+
+export interface HttpHarnessSuccessBody {
+  readonly data: unknown;
+}
+
+/** The result of an HTTP harness request. */
+export interface HttpHarnessResult {
+  readonly body: HttpHarnessErrorBody | HttpHarnessSuccessBody;
+  readonly data?: unknown | undefined;
+  readonly error?: HttpHarnessErrorBody['error'] | undefined;
+  readonly ok: boolean;
+  readonly status: number;
+}
 
 const TEST_ORIGIN = 'http://ontrails.test';
 
@@ -163,7 +241,7 @@ const executeRoute = async (
  *
  * @example
  * ```ts
- * import { createHttpHarness } from '@ontrails/testing';
+ * import { createHttpHarness } from '@ontrails/testing/http';
  *
  * const http = createHttpHarness({ graph });
  * const result = await http.get('/entity/show', { name: 'Alpha' });