@ontrails/testing 1.0.0-beta.1 → 1.0.0-beta.11

package/src/context.ts

@@ -2,11 +2,21 @@
  * Test context factory for creating TrailContext instances suitable for testing.
  */
 
-import type { TrailContext } from '@ontrails/core';
+import type {
+  FollowFn,
+  ServiceOverrideMap,
+  Topo,
+  TrailContext,
+} from '@ontrails/core';
+import { Result, createServiceLookup } from '@ontrails/core';
 
 import { createTestLogger } from './logger.js';
 import type { TestTrailContextOptions } from './types.js';
 
+type MutableTrailContext = {
+  -readonly [K in keyof TrailContext]: TrailContext[K];
+};
+
 // ---------------------------------------------------------------------------
 // createTestContext
 // ---------------------------------------------------------------------------
@@ -20,23 +30,121 @@ import type { TestTrailContextOptions } from './types.js';
  */
 export const createTestContext = (
   overrides?: TestTrailContextOptions
-): TrailContext => ({
-  env: overrides?.env ?? { TRAILS_ENV: 'test' },
-  logger: overrides?.logger ?? createTestLogger(),
-  requestId: overrides?.requestId ?? 'test-request-001',
-  signal: overrides?.signal ?? new AbortController().signal,
-  workspaceRoot: overrides?.cwd ?? process.cwd(),
+): TrailContext => {
+  const cwd = overrides?.cwd ?? process.cwd();
+  const ctx = {
+    cwd,
+    env: overrides?.env ?? { TRAILS_ENV: 'test' },
+    extensions: undefined,
+    logger: overrides?.logger ?? createTestLogger(),
+    requestId: overrides?.requestId ?? 'test-request-001',
+    signal: overrides?.signal ?? new AbortController().signal,
+    workspaceRoot: cwd,
+  } as MutableTrailContext;
+  ctx.service = createServiceLookup(() => ctx);
+  return ctx;
+};
+
+// ---------------------------------------------------------------------------
+// createFollowContext
+// ---------------------------------------------------------------------------
+
+export interface CreateFollowContextOptions {
+  readonly responses?: Record<string, Result<unknown, Error>> | undefined;
+}
+
+export interface TestExecutionOptions {
+  readonly ctx?: Partial<TrailContext> | undefined;
+  readonly services?: ServiceOverrideMap | undefined;
+}
+
+/**
+ * Create a mock `FollowFn` for testing composite trails.
+ *
+ * Returns preconfigured `Result` values keyed by trail ID. Calls to
+ * unregistered IDs return `Result.err` with a descriptive message.
+ *
+ * @example
+ * ```ts
+ * const follow = createFollowContext({
+ *   responses: { 'entity.add': Result.ok({ id: '1', name: 'Alpha' }) },
+ * });
+ * const ctx = { ...createTestContext(), follow };
+ * ```
+ */
+export const createFollowContext = (
+  options?: CreateFollowContextOptions
+): FollowFn => {
+  const responses = options?.responses ?? {};
+  return <O>(id: string, _input: unknown): Promise<Result<O, Error>> => {
+    const response = responses[id];
+    if (response === undefined) {
+      return Promise.resolve(
+        Result.err(new Error(`No mock response for follow("${id}")`)) as Result<
+          O,
+          Error
+        >
+      );
+    }
+    return Promise.resolve(response as Result<O, Error>);
+  };
+};
+
+const isTestExecutionOptions = (
+  input: Partial<TrailContext> | TestExecutionOptions | undefined
+): input is TestExecutionOptions =>
+  input !== undefined &&
+  (Object.hasOwn(input, 'ctx') || Object.hasOwn(input, 'services'));
+
+export const normalizeTestExecutionOptions = (
+  input?: Partial<TrailContext> | TestExecutionOptions
+): TestExecutionOptions =>
+  isTestExecutionOptions(input) ? input : { ctx: input };
+
+export const mergeServiceOverrides = (
+  autoResolved: ServiceOverrideMap,
+  ctx: Partial<TrailContext> | undefined,
+  explicit: ServiceOverrideMap | undefined
+): ServiceOverrideMap => ({
+  ...autoResolved,
+  ...ctx?.extensions,
+  ...explicit,
 });
 
+const buildMockServices = async (app: Topo): Promise<ServiceOverrideMap> => {
+  const services: Record<string, unknown> = {};
+  for (const declaredService of app.listServices()) {
+    if (!declaredService.mock) {
+      continue;
+    }
+    services[declaredService.id] = await declaredService.mock();
+  }
+  return services;
+};
+
+export const resolveMockServices = async (
+  app: Topo
+): Promise<ServiceOverrideMap> => await buildMockServices(app);
+
 /**
  * Merge a Partial<TrailContext> into a test context.
  * Used internally when the public API accepts Partial<TrailContext>.
  */
-export const mergeTestContext = (ctx?: Partial<TrailContext>): TrailContext => {
-  if (ctx === undefined) {
-    return createTestContext();
-  }
-
+export const mergeTestContext = (
+  ctx?: Partial<TrailContext>,
+  services?: ServiceOverrideMap
+): TrailContext => {
   const base = createTestContext();
-  return { ...base, ...ctx };
+  const extensions = {
+    ...base.extensions,
+    ...ctx?.extensions,
+    ...services,
+  };
+  const merged = {
+    ...base,
+    ...ctx,
+    extensions: Object.keys(extensions).length === 0 ? undefined : extensions,
+  } as MutableTrailContext;
+  merged.service = createServiceLookup(() => merged);
+  return merged;
 };

package/src/contracts.ts

@@ -9,16 +9,34 @@
 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
 // ---------------------------------------------------------------------------
 
+/** Check if a trail requires follow() but the context doesn't provide it. */
+const needsFollowContext = (
+  t: unknown,
+  resolveCtx: () => Partial<TrailContext> | TestExecutionOptions | undefined
+): boolean => {
+  const spec = t as { follow?: readonly string[] };
+  if (!spec.follow || spec.follow.length === 0) {
+    return false;
+  }
+  return !normalizeTestExecutionOptions(resolveCtx()).ctx?.follow;
+};
+
 const validateOutputSchema = (
   outputSchema: z.ZodType,
   value: unknown,
@@ -39,29 +57,33 @@ const validateOutputSchema = (
 // ---------------------------------------------------------------------------
 
 /**
- * Verify that every trail's implementation output matches its declared
+ * Verify that every trail implementation output matches its declared
  * output schema. Catches implementation-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>[];
 
   describe('contracts', () => {
-    describe.each(trailEntries)('%s', (_id, trailDef) => {
-      const t = trailDef as Trail<unknown, unknown>;
-
+    describe.each(allEntries)('$id', (t) => {
       if (t.output === undefined) {
         return;
       }
       if (t.examples === undefined || t.examples.length === 0) {
         return;
       }
+      if (needsFollowContext(t, resolveInput)) {
+        return;
+      }
 
       const { examples, output: outputSchema } = t;
       const successExamples = examples.filter((e) => e.error === undefined);
@@ -69,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.implementation(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

@@ -3,15 +3,15 @@
  *
  * 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 hikes with `follows`
+ * determines which check to run per example. For trails with `follow`
  * declarations, checks that every declared follow was called at least once.
  */
 
 import { describe, expect, test } from 'bun:test';
 
 import type {
-  AnyHike,
   FollowFn,
+  ServiceOverrideMap,
   Topo,
   TrailExample,
   Trail,
@@ -30,6 +30,7 @@ import {
   NotFoundError,
   PermissionError,
   RateLimitError,
+  executeTrail,
   Result,
   TimeoutError,
   TrailsError,
@@ -42,9 +43,14 @@ import {
   assertErrorMatch,
   assertFullMatch,
   assertSchemaMatch,
-  expectOk,
 } from './assertions.js';
-import { mergeTestContext } from './context.js';
+import {
+  mergeServiceOverrides,
+  mergeTestContext,
+  normalizeTestExecutionOptions,
+  resolveMockServices,
+} from './context.js';
+import type { TestExecutionOptions } from './context.js';
 
 // ---------------------------------------------------------------------------
 // Error class name -> constructor map
@@ -129,21 +135,24 @@ const runExample = async (
   t: Trail<unknown, unknown>,
   example: TrailExample<unknown, unknown>,
   output: z.ZodType | undefined,
-  testCtx: TrailContext
+  testCtx: TrailContext,
+  services?: ServiceOverrideMap
 ): Promise<void> => {
   const validated = validateInput(t.input, example.input);
 
   if (handleValidationError(validated, example)) {
     return;
   }
-  const validatedInput = expectOk(validated);
 
-  const result = await t.implementation(validatedInput, testCtx);
+  const result = await executeTrail(t, example.input, {
+    ctx: testCtx,
+    services,
+  });
   assertProgressiveMatch(result, example, output);
 };
 
 // ---------------------------------------------------------------------------
-// Follows coverage for hikes
+// Follow coverage for composition trails
 // ---------------------------------------------------------------------------
 
 /**
@@ -157,7 +166,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);
@@ -168,11 +178,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.implementation(validated.value, ctx));
+      return executeTrail(trailDef, input, {
+        ctx: { ...ctx, follow },
+        services,
+      });
     }
 
     return Promise.resolve(Result.ok());
@@ -181,93 +190,37 @@ const createCoverageFollow = (
 };
 
 /**
- * Run a single example against a hike, recording follow calls.
+ * Run a single example against a composition trail, recording follow calls.
  */
-const runHikeExample = async (
-  hikeDef: AnyHike,
+const runCompositionExample = async (
+  trailDef: Trail<unknown, unknown>,
   example: TrailExample<unknown, unknown>,
   output: z.ZodType | undefined,
   baseCtx: TrailContext,
   called: Set<string>,
-  topo: Topo
+  topo: Topo,
+  services?: ServiceOverrideMap
 ): Promise<void> => {
-  const validated = validateInput(hikeDef.input, example.input);
+  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 follow = createCoverageFollow(
+    called,
+    baseCtx.follow,
+    topo,
+    baseCtx,
+    services
+  );
   const testCtx: TrailContext = { ...baseCtx, follow };
 
-  const result = await hikeDef.implementation(validatedInput, testCtx);
-  assertProgressiveMatch(result, example, output);
-};
-
-// ---------------------------------------------------------------------------
-// Hike entry with examples pre-validated
-// ---------------------------------------------------------------------------
-
-interface HikeWithExamples {
-  readonly hikeDef: AnyHike;
-  readonly hikeId: string;
-  readonly examples: readonly TrailExample<unknown, unknown>[];
-}
-
-const collectHikesWithExamples = (app: Topo): readonly HikeWithExamples[] =>
-  [...app.hikes]
-    .filter(([, h]) => h.examples !== undefined && h.examples.length > 0)
-    .map(([hikeId, hikeDef]) => ({
-      examples: hikeDef.examples as readonly TrailExample<unknown, unknown>[],
-      hikeDef,
-      hikeId,
-    }));
-
-// ---------------------------------------------------------------------------
-// Hike example describe blocks
-// ---------------------------------------------------------------------------
-
-/**
- * Generate describe/test blocks for hikes with follows coverage.
- *
- * Always uses a recording follow so that follows coverage can be checked.
- * Hikes without `follows` still run their examples but skip the coverage test.
- */
-const describeHikeExamples = (
-  hikesWithExamples: readonly HikeWithExamples[],
-  resolveCtx: () => Partial<TrailContext> | undefined,
-  topo: Topo
-): void => {
-  if (hikesWithExamples.length === 0) {
-    return;
-  }
-
-  describe.each([...hikesWithExamples])('$hikeId', ({ hikeDef, examples }) => {
-    const called = new Set<string>();
-
-    test.each([...examples])(
-      'example: $name',
-      async (example: TrailExample<unknown, unknown>) => {
-        const baseCtx = mergeTestContext(resolveCtx());
-        await runHikeExample(
-          hikeDef,
-          example,
-          hikeDef.output,
-          baseCtx,
-          called,
-          topo
-        );
-      }
-    );
-
-    if (hikeDef.follows.length > 0) {
-      test('follows coverage', () => {
-        const uncovered = hikeDef.follows.filter((id) => !called.has(id));
-        expect(uncovered).toEqual([]);
-      });
-    }
+  const result = await executeTrail(trailDef, example.input, {
+    ctx: testCtx,
+    services,
   });
+  assertProgressiveMatch(result, example, output);
 };
 
 // ---------------------------------------------------------------------------
@@ -277,7 +230,7 @@ const describeHikeExamples = (
 /**
  * Generate describe/test blocks for every trail example in the app.
  *
- * For hikes with `follows` declarations and examples, also verifies that
+ * For trails with `follow` declarations and examples, also verifies that
  * every declared follow ID was called at least once across all examples.
  *
  * One line in your test file:
@@ -287,28 +240,81 @@ const describeHikeExamples = (
  */
 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 trailEntries = [...app.trails];
+  const allTrails = app.list() as Trail<unknown, unknown>[];
 
-  describe.each(trailEntries)('%s', (_id, trailDef) => {
-    const t = trailDef as Trail<unknown, unknown>;
-    if (t.examples === undefined || t.examples.length === 0) {
-      return;
-    }
+  const withExamples = allTrails.filter(
+    (t) => t.examples !== undefined && t.examples.length > 0
+  );
+  const simpleTrails = withExamples.filter((t) => t.follow.length === 0);
+  const compositionTrails = withExamples.filter((t) => t.follow.length > 0);
+
+  // Simple trails: run examples directly
+  if (simpleTrails.length > 0) {
+    describe.each(simpleTrails)('$id', (t) => {
+      const { examples, output } = t;
+      if (!examples) {
+        return;
+      }
 
-    const { examples, output } = t;
+      test.each([...examples])(
+        'example: $name',
+        async (example: TrailExample<unknown, unknown>) => {
+          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);
+        }
+      );
+    });
+  }
 
-    test.each([...examples])(
-      'example: $name',
-      async (example: TrailExample<unknown, unknown>) => {
-        const testCtx = mergeTestContext(resolveCtx());
-        await runExample(t, example, output, testCtx);
+  // Composition trails: use recording follow and check coverage
+  if (compositionTrails.length > 0) {
+    describe.each(compositionTrails)('$id', (t) => {
+      const { examples, output } = t;
+      if (!examples) {
+        return;
       }
-    );
-  });
 
-  describeHikeExamples(collectHikesWithExamples(app), resolveCtx, app);
+      const called = new Set<string>();
+
+      test.each([...examples])(
+        'example: $name',
+        async (example: TrailExample<unknown, unknown>) => {
+          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
+          );
+        }
+      );
+
+      test('follow coverage', () => {
+        const uncovered = t.follow.filter((id) => !called.has(id));
+        expect(uncovered).toEqual([]);
+      });
+    });
+  }
 };