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

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,39 @@ export interface CreateFollowContextOptions {
   readonly responses?: Record<string, Result<unknown, Error>> | undefined;
 }
 
+/** Minimal permit shape returned by the mint function. */
+export interface MintedPermit {
+  readonly id: string;
+  readonly scopes: readonly string[];
+}
+
+/** Trail shape consumed by the mint function — avoids importing permits. */
+export interface MintableTrail {
+  readonly permit?:
+    | { readonly scopes: readonly string[] }
+    | 'public'
+    | undefined;
+}
+
+export interface TestExecutionOptions {
+  readonly ctx?: Partial<TrailContext> | undefined;
+  readonly services?: ServiceOverrideMap | undefined;
+  /**
+   * When true, disables automatic permit minting. Tests must provide
+   * explicit permits.
+   */
+  readonly strictPermits?: boolean | undefined;
+  /**
+   * Optional function to mint a test permit for a trail. When provided,
+   * called for each trail with a non-public `permit` requirement.
+   * Returning `undefined` skips minting for that trail.
+   *
+   * A default inline implementation is used when this is not provided,
+   * keeping the testing package free of a hard dependency on `@ontrails/permits`.
+   */
+  readonly mintPermit?: (trail: MintableTrail) => MintedPermit | undefined;
+}
+
 /**
  * Create a mock `FollowFn` for testing composite trails.
  *
@@ -70,14 +119,76 @@ export const createFollowContext = (
 };
 
 /**
- * Merge a Partial<TrailContext> into a test context.
- * Used internally when the public API accepts Partial<TrailContext>.
+ * Default permit minter — reads `trail.permit.scopes` and produces a
+ * minimal permit object. No dependency on `@ontrails/permits`.
  */
-export const mergeTestContext = (ctx?: Partial<TrailContext>): TrailContext => {
-  if (ctx === undefined) {
-    return createTestContext();
+export const defaultMintPermit = (
+  trail: MintableTrail
+): MintedPermit | undefined => {
+  if (!trail.permit || trail.permit === 'public') {
+    return undefined;
   }
+  return { id: 'test-permit', scopes: trail.permit.scopes };
+};
+
+const isTestExecutionOptions = (
+  input: Partial<TrailContext> | TestExecutionOptions | undefined
+): input is TestExecutionOptions =>
+  input !== undefined &&
+  (Object.hasOwn(input, 'ctx') ||
+    Object.hasOwn(input, 'services') ||
+    Object.hasOwn(input, 'strictPermits') ||
+    Object.hasOwn(input, 'mintPermit'));
 
+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>,
+  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;
 };