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

package/src/__tests__/follows.test.ts

@@ -1,7 +1,7 @@
 import { describe } from 'bun:test';
 
 import type { AnyTrail, TrailContext } from '@ontrails/core';
-import { Result, trail } from '@ontrails/core';
+import { InternalError, Result, service, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import { testFollows } from '../follows.js';
@@ -161,3 +161,429 @@ describe('testFollows: expectValue', () => {
     opts
   );
 });
+
+// ---------------------------------------------------------------------------
+// Nested follow chain: A → B → C
+// ---------------------------------------------------------------------------
+
+const leafTrail = trail('step.leaf', {
+  description: 'Leaf trail in a nested chain',
+  input: z.object({ value: z.string() }),
+  output: z.object({ leaf: z.string() }),
+  run: (input: { value: string }) => Result.ok({ leaf: input.value }),
+});
+
+const middleTrail = trail('step.middle', {
+  description: 'Middle trail that follows the leaf',
+  follow: ['step.leaf'],
+  input: z.object({ value: z.string() }),
+  output: z.object({ middle: z.string() }),
+  run: async (input: { value: string }, ctx: TrailContext) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('follow not available'));
+    }
+    const leafResult = await ctx.follow<{ leaf: string }>('step.leaf', input);
+    if (leafResult.isErr()) {
+      return leafResult;
+    }
+    return Result.ok({ middle: leafResult.value.leaf });
+  },
+});
+
+const nestedRootTrail = trail('step.root', {
+  description: 'Root trail that follows the middle trail',
+  follow: ['step.middle'],
+  input: z.object({ value: z.string() }),
+  output: z.object({ root: z.string() }),
+  run: async (input: { value: string }, ctx: TrailContext) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('follow not available'));
+    }
+    const midResult = await ctx.follow<{ middle: string }>(
+      'step.middle',
+      input
+    );
+    if (midResult.isErr()) {
+      return midResult;
+    }
+    return Result.ok({ root: midResult.value.middle });
+  },
+});
+
+const nestedTrailsMap = new Map<string, AnyTrail>([
+  ['step.leaf', leafTrail],
+  ['step.middle', middleTrail],
+]);
+
+describe('testFollows: nested follow chain (A → B → C)', () => {
+  // eslint-disable-next-line jest/require-hook
+  testFollows(
+    nestedRootTrail,
+    [
+      {
+        description: 'nested ctx.follow works through A → B → C',
+        expectOk: true,
+        expectValue: { root: 'hello' },
+        input: { value: 'hello' },
+      },
+    ],
+    { trails: nestedTrailsMap }
+  );
+});
+
+const mockDbService = service('db.mock.follows', {
+  create: () => Result.ok({ source: 'factory' }),
+  mock: () => ({ source: 'mock' }),
+});
+
+const serviceLeafTrail = trail('service.leaf', {
+  description: 'Leaf trail that reads from a service',
+  input: z.object({}),
+  output: z.object({ childSource: z.string() }),
+  run: (_input, ctx) =>
+    Result.ok({ childSource: mockDbService.from(ctx).source }),
+  services: [mockDbService],
+});
+
+const serviceRootTrail = trail('service.root', {
+  description: 'Root trail that reads from a service and follows a child trail',
+  follow: ['service.leaf'],
+  input: z.object({}),
+  output: z.object({ childSource: z.string(), rootSource: z.string() }),
+  run: async (_input, ctx: TrailContext) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('follow not available'));
+    }
+    const childResult = await ctx.follow<{ childSource: string }>(
+      'service.leaf',
+      {}
+    );
+    if (childResult.isErr()) {
+      return childResult;
+    }
+
+    return Result.ok({
+      childSource: childResult.value.childSource,
+      rootSource: mockDbService.from(ctx).source,
+    });
+  },
+  services: [mockDbService],
+});
+
+const serviceTrailsMap = new Map<string, AnyTrail>([
+  ['service.leaf', serviceLeafTrail],
+]);
+
+const statefulMockDbService = service('db.mock.follows.stateful', {
+  create: () => Result.ok({ count: 0 }),
+  mock: () => ({ count: 0 }),
+});
+
+const statefulServiceLeafTrail = trail('service.stateful.leaf', {
+  description: 'Leaf trail that observes the current mock service state',
+  input: z.object({}),
+  output: z.object({ childCount: z.number() }),
+  run: (_input, ctx) =>
+    Result.ok({ childCount: statefulMockDbService.from(ctx).count }),
+  services: [statefulMockDbService],
+});
+
+const statefulServiceRootTrail = trail('service.stateful.root', {
+  description:
+    'Root trail that mutates a mocked service and follows a child trail',
+  follow: ['service.stateful.leaf'],
+  input: z.object({}),
+  output: z.object({ childCount: z.number(), rootCount: z.number() }),
+  run: async (_input, ctx: TrailContext) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('follow not available'));
+    }
+
+    const statefulService = statefulMockDbService.from(ctx);
+    statefulService.count += 1;
+
+    const childResult = await ctx.follow<{ childCount: number }>(
+      'service.stateful.leaf',
+      {}
+    );
+    if (childResult.isErr()) {
+      return childResult;
+    }
+
+    return Result.ok({
+      childCount: childResult.value.childCount,
+      rootCount: statefulService.count,
+    });
+  },
+  services: [statefulMockDbService],
+});
+
+const statefulServiceTrailsMap = new Map<string, AnyTrail>([
+  ['service.stateful.leaf', statefulServiceLeafTrail],
+]);
+
+const scenarioStateService = service('db.mock.scenarios', {
+  create: () => Result.ok({ count: 0 }),
+  mock: () => ({ count: 0 }),
+});
+
+const scenarioLeafTrail = trail('service.scenario.leaf', {
+  description: 'Leaf trail that reads mutable scenario state',
+  input: z.object({}),
+  output: z.object({ count: z.number() }),
+  run: (_input, ctx) =>
+    Result.ok({ count: scenarioStateService.from(ctx).count }),
+  services: [scenarioStateService],
+});
+
+const scenarioRootTrail = trail('service.scenario.root', {
+  description: 'Root trail that mutates scenario state and follows a leaf',
+  follow: ['service.scenario.leaf'],
+  input: z.object({}),
+  output: z.object({ count: z.number() }),
+  run: async (_input, ctx: TrailContext) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('follow not available'));
+    }
+
+    const state = scenarioStateService.from(ctx);
+    state.count += 1;
+
+    const leafResult = await ctx.follow<{ count: number }>(
+      'service.scenario.leaf',
+      {}
+    );
+    if (leafResult.isErr()) {
+      return leafResult;
+    }
+
+    return Result.ok({ count: leafResult.value.count });
+  },
+  services: [scenarioStateService],
+});
+
+const scenarioTrailsMap = new Map<string, AnyTrail>([
+  ['service.scenario.leaf', scenarioLeafTrail],
+]);
+
+const transformedFollowLeafTrail = trail('follow.transformed.leaf', {
+  description: 'Leaf trail in a transformed follow chain',
+  input: z.object({ value: z.number() }),
+  output: z.object({ value: z.number() }),
+  run: (input: { value: number }) => Result.ok({ value: input.value }),
+});
+
+const transformedFollowRootTrail = trail('follow.transformed.root', {
+  description: 'Root trail that transforms input once before following',
+  follow: ['follow.transformed.leaf'],
+  input: z
+    .object({ value: z.string() })
+    .transform(({ value }) => ({ value: Number(value) + 1 })),
+  output: z.object({ root: z.number() }),
+  run: async (input: { value: number }, ctx: TrailContext) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('follow not available'));
+    }
+
+    const leafResult = await ctx.follow<{ value: number }>(
+      'follow.transformed.leaf',
+      { value: input.value }
+    );
+    if (leafResult.isErr()) {
+      return leafResult;
+    }
+
+    return Result.ok({ root: leafResult.value.value });
+  },
+});
+
+const transformedFollowTrailsMap = new Map<string, AnyTrail>([
+  ['follow.transformed.leaf', transformedFollowLeafTrail],
+]);
+
+const undeclaredFollowService = service('db.undeclared.follows', {
+  create: () => Result.ok({ source: 'factory' }),
+  mock: () => ({ source: 'mock' }),
+});
+
+const undeclaredServiceLeafTrail = trail('service.undeclared.leaf', {
+  description: 'Leaf trail that declares the shared service',
+  input: z.object({}),
+  output: z.object({ childSource: z.string() }),
+  run: (_input, ctx) =>
+    Result.ok({ childSource: undeclaredFollowService.from(ctx).source }),
+  services: [undeclaredFollowService],
+});
+
+const undeclaredServiceRootTrail = trail('service.undeclared.root', {
+  description: 'Root trail that uses a service without declaring it',
+  follow: ['service.undeclared.leaf'],
+  input: z.object({}),
+  output: z.object({ childSource: z.string(), rootSource: z.string() }),
+  run: async (_input, ctx: TrailContext) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('follow not available'));
+    }
+
+    const childResult = await ctx.follow<{ childSource: string }>(
+      'service.undeclared.leaf',
+      {}
+    );
+    if (childResult.isErr()) {
+      return childResult;
+    }
+
+    return Result.ok({
+      childSource: childResult.value.childSource,
+      rootSource: undeclaredFollowService.from(ctx).source,
+    });
+  },
+});
+
+const undeclaredServiceTrailsMap = new Map<string, AnyTrail>([
+  ['service.undeclared.leaf', undeclaredServiceLeafTrail],
+]);
+
+const unrelatedFollowService = service('db.unrelated.follows', {
+  create: () => Result.ok({ source: 'factory' }),
+  mock: () => {
+    throw new Error('unrelated mock should not be resolved');
+  },
+});
+
+const unrelatedServiceTrail = trail('service.unrelated', {
+  description: 'Trail that should not be traversed or mocked',
+  input: z.object({}),
+  output: z.object({ source: z.string() }),
+  run: (_input, ctx) =>
+    Result.ok({ source: unrelatedFollowService.from(ctx).source }),
+  services: [unrelatedFollowService],
+});
+
+const unrelatedServiceTrailsMap = new Map<string, AnyTrail>([
+  ['service.unrelated', unrelatedServiceTrail],
+]);
+
+describe('testFollows service mocks', () => {
+  // eslint-disable-next-line jest/require-hook
+  testFollows(
+    serviceRootTrail,
+    [
+      {
+        description: 'propagates auto-resolved service mocks through follow',
+        expectValue: { childSource: 'mock', rootSource: 'mock' },
+        input: {},
+      },
+    ],
+    { trails: serviceTrailsMap }
+  );
+});
+
+describe('testFollows service mocks are fresh per scenario', () => {
+  // eslint-disable-next-line jest/require-hook
+  testFollows(
+    scenarioRootTrail,
+    [
+      {
+        description: 'first scenario sees a fresh mutable service',
+        expectValue: { count: 1 },
+        input: {},
+      },
+      {
+        description: 'second scenario also sees a fresh mutable service',
+        expectValue: { count: 1 },
+        input: {},
+      },
+    ],
+    { trails: scenarioTrailsMap }
+  );
+});
+
+describe('testFollows explicit service overrides', () => {
+  // eslint-disable-next-line jest/require-hook
+  testFollows(
+    serviceRootTrail,
+    [
+      {
+        description: 'propagates explicit service overrides through follow',
+        expectValue: { childSource: 'override', rootSource: 'override' },
+        input: {},
+      },
+    ],
+    {
+      services: { 'db.mock.follows': { source: 'override' } },
+      trails: serviceTrailsMap,
+    }
+  );
+});
+
+describe('testFollows raw transformed input', () => {
+  // eslint-disable-next-line jest/require-hook
+  testFollows(
+    transformedFollowRootTrail,
+    [
+      {
+        description: 'raw scenario input is only transformed once',
+        expectValue: { root: 2 },
+        input: { value: '1' },
+      },
+    ],
+    { trails: transformedFollowTrailsMap }
+  );
+});
+
+describe('testFollows service declarations', () => {
+  // eslint-disable-next-line jest/require-hook
+  testFollows(
+    undeclaredServiceRootTrail,
+    [
+      {
+        description: 'fails when the root trail omits a required service',
+        expectErr: InternalError,
+        expectErrMessage: undeclaredFollowService.id,
+        input: {},
+      },
+    ],
+    { trails: undeclaredServiceTrailsMap }
+  );
+});
+
+describe('testFollows only resolves mocks for trails under test', () => {
+  // eslint-disable-next-line jest/require-hook
+  testFollows(
+    serviceRootTrail,
+    [
+      {
+        description: 'unrelated service mocks are not resolved',
+        expectValue: { childSource: 'mock', rootSource: 'mock' },
+        input: {},
+      },
+    ],
+    {
+      trails: new Map<string, AnyTrail>([
+        ...serviceTrailsMap.entries(),
+        ...unrelatedServiceTrailsMap.entries(),
+      ]),
+    }
+  );
+});
+
+describe('testFollows fresh service mocks per scenario', () => {
+  // eslint-disable-next-line jest/require-hook
+  testFollows(
+    statefulServiceRootTrail,
+    [
+      {
+        description: 'first scenario gets a fresh service mock',
+        expectValue: { childCount: 1, rootCount: 1 },
+        input: {},
+      },
+      {
+        description: 'second scenario also gets a fresh service mock',
+        expectValue: { childCount: 1, rootCount: 1 },
+        input: {},
+      },
+    ],
+    { trails: statefulServiceTrailsMap }
+  );
+});

package/src/all.ts

@@ -11,6 +11,7 @@ import type { Topo, TrailContext } from '@ontrails/core';
 import { validateTopo } from '@ontrails/core';
 
 import { testContracts } from './contracts.js';
+import type { TestExecutionOptions } from './context.js';
 import { testDetours } from './detours.js';
 import { testExamples } from './examples.js';
 
@@ -37,7 +38,10 @@ import { testExamples } from './examples.js';
  */
 export const testAll = (
   topo: Topo,
-  ctxOrFactory?: Partial<TrailContext> | (() => Partial<TrailContext>)
+  ctxOrFactory?:
+    | Partial<TrailContext>
+    | TestExecutionOptions
+    | (() => Partial<TrailContext> | TestExecutionOptions)
 ): void => {
   describe('governance', () => {
     test('topo validates', () => {

package/src/context.ts

@@ -2,12 +2,21 @@
  * Test context factory for creating TrailContext instances suitable for testing.
  */
 
-import type { FollowFn, TrailContext } from '@ontrails/core';
-import { Result } 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
 // ---------------------------------------------------------------------------
@@ -21,13 +30,20 @@ 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
@@ -37,6 +53,11 @@ 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.
  *
@@ -69,15 +90,61 @@ export const createFollowContext = (
   };
 };
 
+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,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);