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

package/src/__tests__/examples.test.ts

@@ -1,6 +1,6 @@
 import { describe, test } from 'bun:test';
 
-import { NotFoundError, Result, hike, trail, topo } from '@ontrails/core';
+import { NotFoundError, Result, service, trail, topo } from '@ontrails/core';
 import { z } from 'zod';
 
 import { testExamples } from '../examples.js';
@@ -18,10 +18,10 @@ const greetTrail = trail('greet', {
       name: 'Greet Alice',
     },
   ],
-  implementation: (input: { name: string }) =>
-    Result.ok({ greeting: `Hello, ${input.name}` }),
   input: z.object({ name: z.string() }),
   output: z.object({ greeting: z.string() }),
+  run: (input: { name: string }) =>
+    Result.ok({ greeting: `Hello, ${input.name}` }),
 });
 
 const searchTrail = trail('search', {
@@ -32,10 +32,10 @@ const searchTrail = trail('search', {
       name: 'Schema-only search',
     },
   ],
-  implementation: (input: { query: string }) =>
-    Result.ok({ results: [`result for ${input.query}`] }),
   input: z.object({ query: z.string() }),
   output: z.object({ results: z.array(z.string()) }),
+  run: (input: { query: string }) =>
+    Result.ok({ results: [`result for ${input.query}`] }),
 });
 
 const entityTrail = trail('entity.show', {
@@ -52,42 +52,171 @@ const entityTrail = trail('entity.show', {
       name: 'Entity not found returns NotFoundError',
     },
   ],
-  implementation: (input: { name: string }) => {
+  input: z.object({ name: z.string() }),
+  output: z.object({ id: z.number(), name: z.string() }),
+  run: (input: { name: string }) => {
     if (input.name === 'missing') {
       return Result.err(new NotFoundError('Entity not found'));
     }
     return Result.ok({ id: 1, name: input.name });
   },
-  input: z.object({ name: z.string() }),
-  output: z.object({ id: z.number(), name: z.string() }),
 });
 
 const noExamplesTrail = trail('noexamples', {
-  implementation: (input: { x: number }) => Result.ok(input.x * 2),
   input: z.object({ x: z.number() }),
+  run: (input: { x: number }) => Result.ok(input.x * 2),
+});
+
+const mockDbService = service('db.mock.examples', {
+  create: () => Result.ok({ source: 'factory' }),
+  mock: () => ({ source: 'mock' }),
+});
+
+const mockServiceTrail = trail('service.mocked', {
+  description: 'Trail that reads from a mocked service',
+  examples: [
+    {
+      expected: { source: 'mock' },
+      input: {},
+      name: 'Uses auto-resolved service mock',
+    },
+  ],
+  input: z.object({}),
+  output: z.object({ source: z.string() }),
+  run: (_input, ctx) => Result.ok({ source: mockDbService.from(ctx).source }),
+  services: [mockDbService],
+});
+
+const explicitOverrideTrail = trail('service.override', {
+  description: 'Trail whose service mock can be overridden explicitly',
+  examples: [
+    {
+      expected: { source: 'override' },
+      input: {},
+      name: 'Explicit service override wins over mock factory',
+    },
+  ],
+  input: z.object({}),
+  output: z.object({ source: z.string() }),
+  run: (_input, ctx) => Result.ok({ source: mockDbService.from(ctx).source }),
+  services: [mockDbService],
+});
+
+const transformedInputTrail = trail('example.transformed', {
+  description: 'Trail whose input schema transforms once',
+  examples: [
+    {
+      expected: { value: 2 },
+      input: { value: '1' },
+      name: 'Raw example input is only transformed once',
+    },
+  ],
+  input: z
+    .object({ value: z.string() })
+    .transform(({ value }) => ({ value: Number(value) + 1 })),
+  output: z.object({ value: z.number() }),
+  run: (input: { value: number }) => Result.ok({ value: input.value }),
+});
+
+const ctxOverrideTrail = trail('service.ctx-override', {
+  description: 'Trail whose service mock can be overridden by ctx.extensions',
+  examples: [
+    {
+      expected: { source: 'ctx' },
+      input: {},
+      name: 'Context extensions beat auto-resolved mock services',
+    },
+  ],
+  input: z.object({}),
+  output: z.object({ source: z.string() }),
+  run: (_input, ctx) => Result.ok({ source: mockDbService.from(ctx).source }),
+  services: [mockDbService],
+});
+
+const undeclaredDbService = service('db.undeclared.examples', {
+  create: () => Result.ok({ source: 'factory' }),
+  mock: () => ({ source: 'mock' }),
+});
+
+const undeclaredServiceTrail = trail('service.undeclared.examples', {
+  description: 'Trail that uses a service without declaring it',
+  examples: [
+    {
+      error: 'InternalError',
+      input: {},
+      name: 'Undeclared services stay unavailable during example execution',
+    },
+  ],
+  input: z.object({}),
+  output: z.object({ source: z.string() }),
+  run: (_input, ctx) =>
+    Result.ok({ source: undeclaredDbService.from(ctx).source }),
+});
+const followedDbService = service('db.mock.examples.follow', {
+  create: () => Result.ok({ source: 'factory' }),
+  mock: () => ({ source: 'mock' }),
+});
+
+const followedLeafTrail = trail('service.follow.leaf', {
+  description: 'Leaf trail that resolves a service inside a follow chain',
+  input: z.object({}),
+  output: z.object({ childSource: z.string() }),
+  run: (_input, ctx) =>
+    Result.ok({ childSource: followedDbService.from(ctx).source }),
+  services: [followedDbService],
+});
+
+const followedRootTrail = trail('service.follow.root', {
+  description: 'Root trail that follows a child trail using services',
+  examples: [
+    {
+      expected: { childSource: 'mock', rootSource: 'mock' },
+      input: {},
+      name: 'Propagates service mocks through follow execution',
+    },
+  ],
+  follow: ['service.follow.leaf'],
+  input: z.object({}),
+  output: z.object({ childSource: z.string(), rootSource: z.string() }),
+  run: async (_input, ctx) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('follow not available'));
+    }
+    const childResult = await ctx.follow<{ childSource: string }>(
+      'service.follow.leaf',
+      {}
+    );
+    if (childResult.isErr()) {
+      return childResult;
+    }
+    return Result.ok({
+      childSource: childResult.value.childSource,
+      rootSource: followedDbService.from(ctx).source,
+    });
+  },
+  services: [followedDbService],
 });
 
 // ---------------------------------------------------------------------------
-// Test hikes (for follows coverage)
+// Composition trails (for follow coverage)
 // ---------------------------------------------------------------------------
 
 const addTrail = trail('entity.add', {
   description: 'Add an entity',
-  implementation: (input: { name: string }) =>
-    Result.ok({ id: '1', name: input.name }),
   input: z.object({ name: z.string() }),
   output: z.object({ id: z.string(), name: z.string() }),
+  run: (input: { name: string }) => Result.ok({ id: '1', name: input.name }),
 });
 
 const relateTrail = trail('entity.relate', {
   description: 'Relate entities',
-  implementation: (input: { from: string; to: string }) =>
-    Result.ok({ from: input.from, to: input.to }),
   input: z.object({ from: z.string(), to: z.string() }),
   output: z.object({ from: z.string(), to: z.string() }),
+  run: (input: { from: string; to: string }) =>
+    Result.ok({ from: input.from, to: input.to }),
 });
 
-const onboardHike = hike('entity.onboard', {
+const onboardTrail = trail('entity.onboard', {
   description: 'Onboard a new entity',
   examples: [
     {
@@ -96,8 +225,10 @@ const onboardHike = hike('entity.onboard', {
       name: 'Onboard Alpha',
     },
   ],
-  follows: ['entity.add', 'entity.relate'],
-  implementation: async (input: { name: string }, ctx) => {
+  follow: ['entity.add', 'entity.relate'],
+  input: z.object({ name: z.string() }),
+  output: z.object({ id: z.string(), name: z.string() }),
+  run: async (input: { name: string }, ctx) => {
     if (!ctx.follow) {
       return Result.err(new Error('follow not available'));
     }
@@ -114,8 +245,6 @@ const onboardHike = hike('entity.onboard', {
     }
     return Result.ok({ id: '1', name: input.name });
   },
-  input: z.object({ name: z.string() }),
-  output: z.object({ id: z.string(), name: z.string() }),
 });
 
 // ---------------------------------------------------------------------------
@@ -164,13 +293,147 @@ describe('testExamples skips trails with no examples', () => {
   });
 });
 
-describe('testExamples follows coverage for hikes', () => {
+describe('testExamples service mocks', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('service-mock-app', {
+      mockDbService,
+      mockServiceTrail,
+    } as Record<string, unknown>)
+  );
+});
+
+describe('testExamples explicit service overrides', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('service-override-app', {
+      explicitOverrideTrail,
+      mockDbService,
+    } as Record<string, unknown>),
+    {
+      services: { 'db.mock.examples': { source: 'override' } },
+    }
+  );
+});
+
+describe('testExamples raw transformed input', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('transformed-input-app', {
+      transformedInputTrail,
+    } as Record<string, unknown>)
+  );
+});
+
+describe('testExamples context extension overrides', () => {
   // eslint-disable-next-line jest/require-hook
   testExamples(
-    topo('hike-app', {
+    topo('ctx-override-app', {
+      ctxOverrideTrail,
+      mockDbService,
+    } as Record<string, unknown>),
+    {
+      ctx: {
+        extensions: { 'db.mock.examples': { source: 'ctx' } },
+      },
+    }
+  );
+});
+
+describe('testExamples service declarations', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('undeclared-service-app', {
+      undeclaredDbService,
+      undeclaredServiceTrail,
+    } as Record<string, unknown>)
+  );
+});
+
+describe('testExamples follow coverage for composition trails', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('composition-app', {
       addTrail,
-      onboardHike,
+      onboardTrail,
       relateTrail,
     } as Record<string, unknown>)
   );
 });
+
+describe('testExamples service mocks through follow', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('service-follow-app', {
+      followedDbService,
+      followedLeafTrail,
+      followedRootTrail,
+    } as Record<string, unknown>)
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 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) => {
+    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 rootTrail = trail('step.root', {
+  description: 'Root trail that follows the middle trail',
+  examples: [
+    {
+      expected: { root: 'hello' },
+      input: { value: 'hello' },
+      name: 'Nested follow chain A→B→C',
+    },
+  ],
+  follow: ['step.middle'],
+  input: z.object({ value: z.string() }),
+  output: z.object({ root: z.string() }),
+  run: async (input: { value: string }, ctx) => {
+    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 });
+  },
+});
+
+describe('testExamples nested follow chain (A → B → C)', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('nested-chain-app', {
+      leafTrail,
+      middleTrail,
+      rootTrail,
+    } as Record<string, unknown>)
+  );
+});