@ontrails/testing 1.0.0-beta.2 → 1.0.0-beta.21

package/src/contracts.ts

@@ -2,18 +2,26 @@
  * testContracts — output schema verification.
  *
  * For every trail that has both examples and an output schema,
- * run each example and validate the implementation output against
+ * run each example and validate the Result.ok value 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 { executeTrail, formatZodIssues, validateInput } from '@ontrails/core';
 import type { z } from 'zod';
 
 import { expectOk } from './assertions.js';
-import { mergeTestContext } from './context.js';
+import {
+  mergeResourceOverrides,
+  mergeTestContext,
+  normalizeTestExecutionOptions,
+  createMockResources,
+} from './context.js';
+import type { TestExecutionOptions } from './context.js';
+import type { TrailExampleTarget } from './effective-examples.js';
+import { deriveTrailExampleTargets } from './effective-examples.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -34,47 +42,63 @@ const validateOutputSchema = (
   }
 };
 
+type ContractExampleTarget = TrailExampleTarget & {
+  readonly output: z.ZodType;
+};
+
+const hasContractExamples = (
+  target: TrailExampleTarget
+): target is ContractExampleTarget =>
+  target.output !== undefined && target.examples.length > 0;
+
 // ---------------------------------------------------------------------------
 // testContracts
 // ---------------------------------------------------------------------------
 
 /**
- * Verify that every trail's implementation output matches its declared
- * output schema. Catches implementation-schema drift.
+ * Verify that every successful trail result matches its declared
+ * output schema. Catches output-schema drift.
  *
  * Trails without output schemas or examples are skipped.
  */
 export const testContracts = (
   app: Topo,
-  ctxOrFactory?: Partial<TrailContext> | (() => Partial<TrailContext>)
+  ctxOrFactory?:
+    | Partial<TrailContext>
+    | TestExecutionOptions
+    | (() => Partial<TrailContext> | TestExecutionOptions)
 ): void => {
-  const resolveCtx =
+  const resolveInput =
     typeof ctxOrFactory === 'function' ? ctxOrFactory : () => ctxOrFactory;
-  const trailEntries = [...app.trails];
+  const allEntries = (app.list() as Trail<unknown, unknown, unknown>[])
+    .flatMap(deriveTrailExampleTargets)
+    .filter(hasContractExamples);
 
   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;
-      }
-
+    describe.each(allEntries)('$id', (t) => {
       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 resolved = normalizeTestExecutionOptions(resolveInput());
+          const resources = mergeResourceOverrides(
+            await createMockResources(app),
+            resolved.ctx,
+            resolved.resources
+          );
+          const testCtx = mergeTestContext(resolved.ctx);
 
           const validated = validateInput(t.input, example.input);
-          const validatedInput = expectOk(validated);
+          expectOk(validated);
 
-          const result = await t.implementation(validatedInput, testCtx);
+          const result = await executeTrail(t.trail, example.input, {
+            ctx: testCtx,
+            resources,
+            topo: app,
+            ...(t.version === undefined ? {} : { version: t.version }),
+          });
           const resultValue = expectOk(result);
 
           validateOutputSchema(outputSchema, resultValue, t.id, example.name);

package/src/detours.ts

@@ -1,42 +1,179 @@
 /**
- * testDetours — verify that all detour targets exist in the topo.
+ * testDetours — validate the live detour contract for every trail.
  *
- * Pure structural validation. No implementation execution needed.
+ * Pure structural validation. No blaze or detour recovery execution needed.
  */
 
-import { describe, expect, test } from 'bun:test';
+import { describe, test } from 'bun:test';
 
+import { TrailsError } from '@ontrails/core';
 import type { Topo, Trail } from '@ontrails/core';
 
-// ---------------------------------------------------------------------------
-// testDetours
-// ---------------------------------------------------------------------------
+interface RuntimeDetour {
+  readonly on?: unknown;
+  readonly recover?: unknown;
+}
+
+const isErrorConstructor = (
+  value: unknown
+): value is abstract new (...args: never[]) => Error => {
+  if (typeof value !== 'function') {
+    return false;
+  }
+
+  const { prototype } = value as { prototype?: unknown };
+  return prototype instanceof Error;
+};
+
+const detourLabel = (trailId: string, index: number, detour: RuntimeDetour) => {
+  if (typeof detour.on === 'function') {
+    const { name } = detour.on as { name?: unknown };
+    if (typeof name === 'string' && name.length > 0) {
+      return `${trailId} detour[${index}] on ${name}`;
+    }
+  }
+
+  return `${trailId} detour[${index}]`;
+};
+
+const assertValidOn = (
+  trailId: string,
+  index: number,
+  detour: RuntimeDetour
+): void => {
+  if (isErrorConstructor(detour.on)) {
+    return;
+  }
+
+  throw new Error(
+    `${detourLabel(trailId, index, detour)} must declare a real error constructor in on:`
+  );
+};
+
+const assertCallableRecover = (
+  trailId: string,
+  index: number,
+  detour: RuntimeDetour
+): void => {
+  if (typeof detour.recover === 'function') {
+    return;
+  }
+
+  throw new Error(
+    `${detourLabel(trailId, index, detour)} must declare a callable recover function`
+  );
+};
+
+const sameOrSubtype = (
+  candidate: abstract new (...args: never[]) => Error,
+  ancestor: abstract new (...args: never[]) => Error
+): boolean => {
+  if (candidate === ancestor) {
+    return true;
+  }
+
+  let current = Object.getPrototypeOf(candidate.prototype);
+  while (current && typeof current === 'object') {
+    const ctor = (current as { constructor?: unknown }).constructor;
+    if (ctor === ancestor) {
+      return true;
+    }
+    current = Object.getPrototypeOf(current);
+  }
+
+  return false;
+};
+
+const getShadowingDetour = (
+  detours: readonly RuntimeDetour[],
+  index: number
+):
+  | {
+      readonly index: number;
+      readonly on: abstract new (...args: never[]) => Error;
+    }
+  | undefined => {
+  const detour = detours[index];
+  if (!detour || !isErrorConstructor(detour.on)) {
+    return undefined;
+  }
+
+  for (let previousIndex = 0; previousIndex < index; previousIndex += 1) {
+    const previous = detours[previousIndex];
+    if (!previous || !isErrorConstructor(previous.on)) {
+      continue;
+    }
+
+    if (sameOrSubtype(detour.on, previous.on)) {
+      return { index: previousIndex, on: previous.on };
+    }
+  }
+
+  return undefined;
+};
+
+const assertNotShadowed = (
+  trailId: string,
+  detours: readonly RuntimeDetour[],
+  index: number
+): void => {
+  const detour = detours[index];
+  if (!detour || !isErrorConstructor(detour.on)) {
+    return;
+  }
+
+  const shadowing = getShadowingDetour(detours, index);
+  if (!shadowing) {
+    return;
+  }
+
+  const previousName = shadowing.on.name || TrailsError.name;
+  const currentName = detour.on.name || TrailsError.name;
+  throw new Error(
+    `${trailId} detour[${index}] on ${currentName} is shadowed by earlier detour[${shadowing.index}] on ${previousName}`
+  );
+};
 
 /**
- * Verify that every trail's detour targets reference trails that
- * actually exist in the app's topo.
+ * Verify that every trail's detours match the live runtime contract:
+ * `on` must be an error constructor, `recover` must be callable, and
+ * later detours must not be shadowed by earlier broader `on` types.
  */
 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>;
+      const trail = trailDef as Trail<unknown, unknown, unknown>;
 
-      if (t.detours === undefined) {
+      if (trail.detours.length === 0) {
         return;
       }
 
-      const { detours } = t;
-      const testCases = Object.entries(detours).flatMap(
-        ([detourName, targets]) =>
-          targets.map((targetId) => ({ detourName, targetId }))
+      const detourCases = trail.detours.map((detour, index) => ({
+        detour,
+        index,
+        trailId: trail.id,
+      }));
+
+      test.each(detourCases)(
+        '$trailId detour[$index] uses an error constructor',
+        ({ detour, index, trailId }) => {
+          assertValidOn(trailId, index, detour);
+        }
+      );
+
+      test.each(detourCases)(
+        '$trailId detour[$index] provides a callable recover',
+        ({ detour, index, trailId }) => {
+          assertCallableRecover(trailId, index, detour);
+        }
       );
 
-      test.each(testCases)(
-        'detour "$detourName" -> "$targetId" exists',
-        ({ targetId }) => {
-          expect(app.has(targetId)).toBe(true);
+      test.each(detourCases)(
+        '$trailId detour[$index] is not shadowed by an earlier detour',
+        ({ index, trailId }) => {
+          assertNotShadowed(trailId, trail.detours, index);
         }
       );
     });