@ontrails/testing 1.0.0-beta.10 → 1.0.0-beta.12

package/src/contracts.ts

@@ -9,11 +9,17 @@
 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 {
+  mergeServiceOverrides,
+  mergeTestContext,
+  normalizeTestExecutionOptions,
+  resolveMockServices,
+} from './context.js';
+import type { TestExecutionOptions } from './context.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -22,13 +28,13 @@ import { mergeTestContext } from './context.js';
 /** Check if a trail requires follow() but the context doesn't provide it. */
 const needsFollowContext = (
   t: unknown,
-  resolveCtx: () => Partial<TrailContext> | undefined
+  resolveCtx: () => Partial<TrailContext> | TestExecutionOptions | undefined
 ): boolean => {
   const spec = t as { follow?: readonly string[] };
   if (!spec.follow || spec.follow.length === 0) {
     return false;
   }
-  return !resolveCtx()?.follow;
+  return !normalizeTestExecutionOptions(resolveCtx()).ctx?.follow;
 };
 
 const validateOutputSchema = (
@@ -58,9 +64,12 @@ const validateOutputSchema = (
  */
 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 allEntries = app.list() as Trail<unknown, unknown>[];
 
@@ -72,7 +81,7 @@ export const testContracts = (
       if (t.examples === undefined || t.examples.length === 0) {
         return;
       }
-      if (needsFollowContext(t, resolveCtx)) {
+      if (needsFollowContext(t, resolveInput)) {
         return;
       }
 
@@ -82,12 +91,21 @@ export const testContracts = (
       test.each(successExamples)(
         'contract: $name',
         async (example: TrailExample<unknown, unknown>) => {
-          const testCtx = mergeTestContext(resolveCtx());
+          const resolved = normalizeTestExecutionOptions(resolveInput());
+          const services = mergeServiceOverrides(
+            await resolveMockServices(app),
+            resolved.ctx,
+            resolved.services
+          );
+          const testCtx = mergeTestContext(resolved.ctx);
 
           const validated = validateInput(t.input, example.input);
-          const validatedInput = expectOk(validated);
+          expectOk(validated);
 
-          const result = await t.run(validatedInput, testCtx);
+          const result = await executeTrail(t, example.input, {
+            ctx: testCtx,
+            services,
+          });
           const resultValue = expectOk(result);
 
           validateOutputSchema(outputSchema, resultValue, t.id, example.name);

package/src/examples.ts

@@ -11,6 +11,7 @@ import { describe, expect, test } from 'bun:test';
 
 import type {
   FollowFn,
+  ServiceOverrideMap,
   Topo,
   TrailExample,
   Trail,
@@ -29,6 +30,7 @@ import {
   NotFoundError,
   PermissionError,
   RateLimitError,
+  executeTrail,
   Result,
   TimeoutError,
   TrailsError,
@@ -41,9 +43,15 @@ import {
   assertErrorMatch,
   assertFullMatch,
   assertSchemaMatch,
-  expectOk,
 } from './assertions.js';
-import { mergeTestContext } from './context.js';
+import {
+  defaultMintPermit,
+  mergeServiceOverrides,
+  mergeTestContext,
+  normalizeTestExecutionOptions,
+  resolveMockServices,
+} from './context.js';
+import type { MintableTrail, TestExecutionOptions } from './context.js';
 
 // ---------------------------------------------------------------------------
 // Error class name -> constructor map
@@ -120,6 +128,29 @@ const handleValidationError = (
   );
 };
 
+/**
+ * Apply auto-minting: if the trail declares scoped permits and the context
+ * doesn't already have a permit, mint one and merge it into the context.
+ */
+const applyAutoMint = (
+  ctx: TrailContext,
+  trailDef: MintableTrail,
+  opts: TestExecutionOptions
+): TrailContext => {
+  if (opts.strictPermits) {
+    return ctx;
+  }
+  if (ctx.permit !== undefined) {
+    return ctx;
+  }
+  const mint = opts.mintPermit ?? defaultMintPermit;
+  const permit = mint(trailDef);
+  if (!permit) {
+    return ctx;
+  }
+  return { ...ctx, permit };
+};
+
 /**
  * Run a single example against a trail.
  * Handles validation, execution, and assertions.
@@ -128,16 +159,22 @@ const runExample = async (
   t: Trail<unknown, unknown>,
   example: TrailExample<unknown, unknown>,
   output: z.ZodType | undefined,
-  testCtx: TrailContext
+  testCtx: TrailContext,
+  services?: ServiceOverrideMap,
+  opts?: TestExecutionOptions
 ): Promise<void> => {
   const validated = validateInput(t.input, example.input);
 
   if (handleValidationError(validated, example)) {
     return;
   }
-  const validatedInput = expectOk(validated);
 
-  const result = await t.run(validatedInput, testCtx);
+  const ctx = opts ? applyAutoMint(testCtx, t, opts) : testCtx;
+
+  const result = await executeTrail(t, example.input, {
+    ctx,
+    services,
+  });
   assertProgressiveMatch(result, example, output);
 };
 
@@ -156,7 +193,8 @@ const createCoverageFollow = (
   called: Set<string>,
   baseFollow: FollowFn | undefined,
   topo: Topo,
-  ctx: TrailContext
+  ctx: TrailContext,
+  services?: ServiceOverrideMap
 ): FollowFn => {
   const follow = (id: string, input: unknown) => {
     called.add(id);
@@ -167,11 +205,10 @@ const createCoverageFollow = (
 
     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.run(validated.value, ctx));
+      return executeTrail(trailDef, input, {
+        ctx: { ...ctx, follow },
+        services,
+      });
     }
 
     return Promise.resolve(Result.ok());
@@ -188,19 +225,30 @@ const runCompositionExample = async (
   output: z.ZodType | undefined,
   baseCtx: TrailContext,
   called: Set<string>,
-  topo: Topo
+  topo: Topo,
+  services?: ServiceOverrideMap,
+  opts?: TestExecutionOptions
 ): Promise<void> => {
   const validated = validateInput(trailDef.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 mintedCtx = opts ? applyAutoMint(baseCtx, trailDef, opts) : baseCtx;
+  const follow = createCoverageFollow(
+    called,
+    mintedCtx.follow,
+    topo,
+    mintedCtx,
+    services
+  );
+  const testCtx: TrailContext = { ...mintedCtx, follow };
 
-  const result = await trailDef.run(validatedInput, testCtx);
+  const result = await executeTrail(trailDef, example.input, {
+    ctx: testCtx,
+    services,
+  });
   assertProgressiveMatch(result, example, output);
 };
 
@@ -221,9 +269,12 @@ const runCompositionExample = async (
  */
 export const testExamples = (
   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 allTrails = app.list() as Trail<unknown, unknown>[];
 
@@ -244,8 +295,14 @@ export const testExamples = (
       test.each([...examples])(
         'example: $name',
         async (example: TrailExample<unknown, unknown>) => {
-          const testCtx = mergeTestContext(resolveCtx());
-          await runExample(t, example, output, testCtx);
+          const resolved = normalizeTestExecutionOptions(resolveInput());
+          const services = mergeServiceOverrides(
+            await resolveMockServices(app),
+            resolved.ctx,
+            resolved.services
+          );
+          const testCtx = mergeTestContext(resolved.ctx);
+          await runExample(t, example, output, testCtx, services, resolved);
         }
       );
     });
@@ -264,8 +321,23 @@ export const testExamples = (
       test.each([...examples])(
         'example: $name',
         async (example: TrailExample<unknown, unknown>) => {
-          const baseCtx = mergeTestContext(resolveCtx());
-          await runCompositionExample(t, example, output, baseCtx, called, app);
+          const resolved = normalizeTestExecutionOptions(resolveInput());
+          const services = mergeServiceOverrides(
+            await resolveMockServices(app),
+            resolved.ctx,
+            resolved.services
+          );
+          const baseCtx = mergeTestContext(resolved.ctx);
+          await runCompositionExample(
+            t,
+            example,
+            output,
+            baseCtx,
+            called,
+            app,
+            services,
+            resolved
+          );
         }
       );
 

package/src/follows.ts

@@ -7,8 +7,14 @@
 
 import { describe, expect, test } from 'bun:test';
 
-import type { AnyTrail, FollowFn, TrailContext } from '@ontrails/core';
+import type {
+  AnyTrail,
+  FollowFn,
+  ServiceOverrideMap,
+  TrailContext,
+} from '@ontrails/core';
 import {
+  executeTrail,
   InternalError,
   Result,
   ValidationError,
@@ -19,9 +25,8 @@ import {
   assertErrorMatch,
   assertFullMatch,
   assertSchemaMatch,
-  expectOk,
 } from './assertions.js';
-import { mergeTestContext } from './context.js';
+import { mergeServiceOverrides, mergeTestContext } from './context.js';
 import type { FollowScenario } from './types.js';
 
 // ---------------------------------------------------------------------------
@@ -33,6 +38,58 @@ interface FollowRecord {
   readonly input: unknown;
 }
 
+const collectDeclaredServices = (
+  trailDef: AnyTrail,
+  trailsMap: ReadonlyMap<string, AnyTrail> | undefined
+): AnyTrail['services'] => {
+  const seenServiceIds = new Set<string>();
+  const seenTrailIds = new Set<string>();
+  const services: AnyTrail['services'][number][] = [];
+
+  const collect = (candidate: AnyTrail): void => {
+    for (const declaredService of candidate.services) {
+      if (seenServiceIds.has(declaredService.id)) {
+        continue;
+      }
+      seenServiceIds.add(declaredService.id);
+      services.push(declaredService);
+    }
+  };
+
+  const visit = (candidate: AnyTrail): void => {
+    if (seenTrailIds.has(candidate.id)) {
+      return;
+    }
+    seenTrailIds.add(candidate.id);
+    collect(candidate);
+    for (const followedId of candidate.follow) {
+      const followedTrail = trailsMap?.get(followedId);
+      if (followedTrail) {
+        visit(followedTrail);
+      }
+    }
+  };
+
+  visit(trailDef);
+  return services;
+};
+
+const resolveMockServices = async (
+  trailDef: AnyTrail,
+  trailsMap: ReadonlyMap<string, AnyTrail> | undefined
+): Promise<ServiceOverrideMap> => {
+  const services: Record<string, unknown> = {};
+
+  for (const declaredService of collectDeclaredServices(trailDef, trailsMap)) {
+    if (!declaredService.mock) {
+      continue;
+    }
+    services[declaredService.id] = await declaredService.mock();
+  }
+
+  return services;
+};
+
 // ---------------------------------------------------------------------------
 // Injection helpers
 // ---------------------------------------------------------------------------
@@ -90,18 +147,20 @@ const executeFromMap = (
   id: string,
   input: unknown,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
-  ctx: TrailContext
+  ctx: TrailContext,
+  services: ServiceOverrideMap | undefined,
+  follow?: FollowFn
 ): Result<unknown, Error> | Promise<Result<unknown, Error>> | undefined => {
   const trailDef = trailsMap?.get(id);
   if (trailDef === undefined) {
     return undefined;
   }
 
-  const validated = validateInput(trailDef.input, input);
-  if (validated.isErr()) {
-    return validated;
-  }
-  return trailDef.run(validated.value, ctx);
+  const nestedCtx = follow ? { ...ctx, follow } : ctx;
+  return executeTrail(trailDef, input, {
+    ctx: nestedCtx,
+    services,
+  });
 };
 
 // ---------------------------------------------------------------------------
@@ -116,7 +175,8 @@ const createRecordingFollow = (
   scenario: FollowScenario,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
   baseFollow: FollowFn | undefined,
-  ctx: TrailContext
+  ctx: TrailContext,
+  services: ServiceOverrideMap | undefined
 ): FollowFn => {
   // The generic O on FollowFn is erased at runtime; the cast is safe
   // because callers narrow via isOk/isErr before accessing the value.
@@ -132,7 +192,14 @@ const createRecordingFollow = (
       return baseFollow(id, input);
     }
 
-    const executed = executeFromMap(id, input, trailsMap, ctx);
+    const executed = executeFromMap(
+      id,
+      input,
+      trailsMap,
+      ctx,
+      services,
+      follow as FollowFn
+    );
     if (executed !== undefined) {
       return Promise.resolve(executed);
     }
@@ -209,7 +276,8 @@ const handleValidationError = (
 const buildTestContext = (
   scenario: FollowScenario,
   ctx: Partial<TrailContext> | undefined,
-  trailsMap: ReadonlyMap<string, AnyTrail> | undefined
+  trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
+  services: ServiceOverrideMap | undefined
 ): { trace: FollowRecord[]; testCtx: TrailContext } => {
   const trace: FollowRecord[] = [];
   const baseCtx = mergeTestContext(ctx);
@@ -218,7 +286,8 @@ const buildTestContext = (
     scenario,
     trailsMap,
     baseCtx.follow,
-    baseCtx
+    baseCtx,
+    services
   );
   return { testCtx: { ...baseCtx, follow }, trace };
 };
@@ -227,15 +296,24 @@ const runScenario = async (
   trailDef: AnyTrail,
   scenario: FollowScenario,
   ctx: Partial<TrailContext> | undefined,
-  trailsMap: ReadonlyMap<string, AnyTrail> | undefined
+  trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
+  services: ServiceOverrideMap | undefined
 ): Promise<void> => {
   const validated = validateInput(trailDef.input, scenario.input);
   if (handleValidationError(validated, scenario)) {
     return;
   }
 
-  const { trace, testCtx } = buildTestContext(scenario, ctx, trailsMap);
-  const result = await trailDef.run(expectOk(validated), testCtx);
+  const { trace, testCtx } = buildTestContext(
+    scenario,
+    ctx,
+    trailsMap,
+    services
+  );
+  const result = await executeTrail(trailDef, scenario.input, {
+    ctx: testCtx,
+    services,
+  });
   assertFollowTrace(trace, scenario);
   assertScenarioResult(result, scenario, trailDef);
 };
@@ -248,6 +326,12 @@ const runScenario = async (
 export interface TestFollowOptions {
   /** Partial context overrides. */
   readonly ctx?: Partial<TrailContext> | undefined;
+  /**
+   * Explicit service overrides merged on top of auto-resolved mocks for every
+   * scenario. Values are passed by reference — provide immutable objects, or
+   * use `mock()` on the service definition to get a fresh instance per run.
+   */
+  readonly services?: ServiceOverrideMap | undefined;
   /** Map of trail ID to trail definition, used for injectFromExample. */
   readonly trails?: ReadonlyMap<string, AnyTrail> | undefined;
 }
@@ -276,7 +360,18 @@ export const testFollows = (
     test.each([...scenarios])(
       '$description',
       async (scenario: FollowScenario) => {
-        await runScenario(trailDef, scenario, options?.ctx, options?.trails);
+        const services = mergeServiceOverrides(
+          await resolveMockServices(trailDef, options?.trails),
+          options?.ctx,
+          options?.services
+        );
+        await runScenario(
+          trailDef,
+          scenario,
+          options?.ctx,
+          options?.trails,
+          services
+        );
       }
     );
   });

package/src/index.ts

@@ -16,7 +16,11 @@ export {
 } from './assertions.js';
 
 // Mock factories
-export { createFollowContext, createTestContext } from './context.js';
+export {
+  createFollowContext,
+  createTestContext,
+  defaultMintPermit,
+} from './context.js';
 export { createTestLogger } from './logger.js';
 
 // Surface harnesses
@@ -25,6 +29,11 @@ export { createMcpHarness } from './harness-mcp.js';
 
 // Types
 export type { CreateFollowContextOptions } from './context.js';
+export type {
+  MintableTrail,
+  MintedPermit,
+  TestExecutionOptions,
+} from './context.js';
 export type { TestFollowOptions } from './follows.js';
 
 export type {