@ontrails/testing 1.0.0-beta.3 → 1.0.0-beta.4

package/src/__tests__/contracts.test.ts

@@ -1,6 +1,6 @@
 import { describe, test } from 'bun:test';
 
-import { Result, hike, trail, topo } from '@ontrails/core';
+import { Result, trail, topo } from '@ontrails/core';
 import { z } from 'zod';
 
 import { testContracts } from '../contracts.js';
@@ -18,44 +18,43 @@ const validTrail = trail('valid', {
       name: 'Valid output',
     },
   ],
-  implementation: (input: { name: string }) =>
-    Result.ok({ id: 1, name: input.name }),
   input: z.object({ name: z.string() }),
   output: z.object({ id: z.number(), name: z.string() }),
+  run: (input: { name: string }) => Result.ok({ id: 1, name: input.name }),
 });
 
 /** Trail without output schema -- should be skipped. */
 const noSchemaTrail = trail('noschema', {
   examples: [{ expected: 10, input: { x: 5 }, name: 'No schema' }],
-  implementation: (input: { x: number }) => Result.ok(input.x * 2),
   input: z.object({ x: z.number() }),
+  run: (input: { x: number }) => Result.ok(input.x * 2),
 });
 
 /** Trail without examples -- should be skipped. */
 const noExamplesTrail = trail('noexamples', {
-  implementation: (input: { x: number }) => Result.ok({ value: input.x }),
   input: z.object({ x: z.number() }),
   output: z.object({ value: z.number() }),
+  run: (input: { x: number }) => Result.ok({ value: input.x }),
 });
 
 // ---------------------------------------------------------------------------
-// Test hikes
+// Composition trail
 // ---------------------------------------------------------------------------
 
-/** Hike whose implementation matches the output schema. */
-const validHike = hike('hike.valid', {
+/** Composition trail whose implementation matches the output schema. */
+const compositionTrail = trail('composition.valid', {
   examples: [
     {
       expected: { total: 3 },
       input: { a: 1, b: 2 },
-      name: 'Valid hike output',
+      name: 'Valid composition output',
     },
   ],
-  follows: ['valid'],
-  implementation: (input: { a: number; b: number }) =>
-    Result.ok({ total: input.a + input.b }),
+  follow: ['valid'],
   input: z.object({ a: z.number(), b: z.number() }),
   output: z.object({ total: z.number() }),
+  run: (input: { a: number; b: number }) =>
+    Result.ok({ total: input.a + input.b }),
 });
 
 // ---------------------------------------------------------------------------
@@ -87,7 +86,9 @@ describe('testContracts: skips trails without examples', () => {
   });
 });
 
-describe('testContracts: validates hike output schemas', () => {
+describe('testContracts: validates composition trail output schemas', () => {
   // eslint-disable-next-line jest/require-hook
-  testContracts(topo('test-app', { validHike } as Record<string, unknown>));
+  testContracts(
+    topo('test-app', { compositionTrail } as Record<string, unknown>)
+  );
 });

package/src/__tests__/detours.test.ts

@@ -13,18 +13,18 @@ const showTrail = trail('entity.show', {
   detours: {
     related: ['entity.list'],
   },
-  implementation: (input: { id: string }) => Result.ok({ id: input.id }),
   input: z.object({ id: z.string() }),
+  run: (input: { id: string }) => Result.ok({ id: input.id }),
 });
 
 const listTrail = trail('entity.list', {
-  implementation: () => Result.ok([]),
   input: z.object({}),
+  run: () => Result.ok([]),
 });
 
 const noDetoursTrail = trail('entity.plain', {
-  implementation: () => Result.ok('ok'),
   input: z.object({}),
+  run: () => Result.ok('ok'),
 });
 
 // ---------------------------------------------------------------------------

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, 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,41 @@ 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),
 });
 
 // ---------------------------------------------------------------------------
-// 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 +95,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 +115,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,12 +163,12 @@ describe('testExamples skips trails with no examples', () => {
   });
 });
 
-describe('testExamples follows coverage for hikes', () => {
+describe('testExamples follow coverage for composition trails', () => {
   // eslint-disable-next-line jest/require-hook
   testExamples(
-    topo('hike-app', {
+    topo('composition-app', {
       addTrail,
-      onboardHike,
+      onboardTrail,
       relateTrail,
     } as Record<string, unknown>)
   );

package/src/__tests__/{hike.test.ts → follows.test.ts}

@@ -1,13 +1,13 @@
 import { describe } from 'bun:test';
 
 import type { AnyTrail, TrailContext } from '@ontrails/core';
-import { Result, hike, trail } from '@ontrails/core';
+import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { testHike } from '../hike.js';
+import { testFollows } from '../follows.js';
 
 // ---------------------------------------------------------------------------
-// Test trails (followed by hikes)
+// Test trails (followed by composition trail)
 // ---------------------------------------------------------------------------
 
 const addTrail = trail('entity.add', {
@@ -21,27 +21,28 @@ const addTrail = trail('entity.add', {
       name: 'duplicate',
     },
   ],
-  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 two 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 }),
 });
 
 // ---------------------------------------------------------------------------
-// Test hike
+// Composition trail
 // ---------------------------------------------------------------------------
 
-const onboardHike = hike('entity.onboard', {
-  follows: ['entity.add', 'entity.relate'],
-  implementation: async (
+const onboardTrail = trail('entity.onboard', {
+  follow: ['entity.add', 'entity.relate'],
+  input: z.object({ name: z.string(), relatedTo: z.string() }),
+  output: z.object({ name: z.string(), relatedTo: z.string() }),
+  run: async (
     input: { name: string; relatedTo: string },
     ctx: TrailContext
   ) => {
@@ -69,8 +70,6 @@ const onboardHike = hike('entity.onboard', {
       relatedTo: relateResult.value.to,
     });
   },
-  input: z.object({ name: z.string(), relatedTo: z.string() }),
-  output: z.object({ name: z.string(), relatedTo: z.string() }),
 });
 
 const trailsMap = new Map<string, AnyTrail>([
@@ -84,10 +83,10 @@ const trailsMap = new Map<string, AnyTrail>([
 
 const opts = { trails: trailsMap };
 
-describe('testHike: expectOk', () => {
+describe('testFollows: expectOk', () => {
   // eslint-disable-next-line jest/require-hook
-  testHike(
-    onboardHike,
+  testFollows(
+    onboardTrail,
     [
       {
         description: 'basic onboard succeeds',
@@ -99,10 +98,10 @@ describe('testHike: expectOk', () => {
   );
 });
 
-describe('testHike: expectFollowed', () => {
+describe('testFollows: expectFollowed', () => {
   // eslint-disable-next-line jest/require-hook
-  testHike(
-    onboardHike,
+  testFollows(
+    onboardTrail,
     [
       {
         description: 'follows add then relate in order',
@@ -115,10 +114,10 @@ describe('testHike: expectFollowed', () => {
   );
 });
 
-describe('testHike: expectFollowedCount', () => {
+describe('testFollows: expectFollowedCount', () => {
   // eslint-disable-next-line jest/require-hook
-  testHike(
-    onboardHike,
+  testFollows(
+    onboardTrail,
     [
       {
         description: 'each trail followed exactly once',
@@ -131,10 +130,10 @@ describe('testHike: expectFollowedCount', () => {
   );
 });
 
-describe('testHike: injectFromExample', () => {
+describe('testFollows: injectFromExample', () => {
   // eslint-disable-next-line jest/require-hook
-  testHike(
-    onboardHike,
+  testFollows(
+    onboardTrail,
     [
       {
         description: 'inject duplicate error from add trail example',
@@ -148,10 +147,10 @@ describe('testHike: injectFromExample', () => {
   );
 });
 
-describe('testHike: expectValue', () => {
+describe('testFollows: expectValue', () => {
   // eslint-disable-next-line jest/require-hook
-  testHike(
-    onboardHike,
+  testFollows(
+    onboardTrail,
     [
       {
         description: 'exact value match',

package/src/__tests__/trail.test.ts

@@ -10,20 +10,20 @@ import { testTrail } from '../trail.js';
 // ---------------------------------------------------------------------------
 
 const greetTrail = trail('greet', {
-  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 failTrail = trail('fail', {
-  implementation: (input: { id: string }) => {
+  input: z.object({ id: z.string() }),
+  run: (input: { id: string }) => {
     if (input.id === 'missing') {
       return Result.err(new NotFoundError('Not found: missing'));
     }
     return Result.ok({ id: input.id });
   },
-  input: z.object({ id: z.string() }),
 });
 
 // ---------------------------------------------------------------------------

package/src/contracts.ts

@@ -1,7 +1,7 @@
 /**
  * testContracts — output schema verification.
  *
- * For every trail and hike that has both examples and an output schema,
+ * For every trail that has both examples and an output schema,
  * run each example and validate the implementation output against
  * the declared schema.
  */
@@ -19,13 +19,13 @@ import { mergeTestContext } from './context.js';
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** Check if a trail/hike requires follow() but the context doesn't provide it. */
+/** Check if a trail requires follow() but the context doesn't provide it. */
 const needsFollowContext = (
   t: unknown,
   resolveCtx: () => Partial<TrailContext> | undefined
 ): boolean => {
-  const spec = t as { follows?: readonly string[] };
-  if (!spec.follows || spec.follows.length === 0) {
+  const spec = t as { follow?: readonly string[] };
+  if (!spec.follow || spec.follow.length === 0) {
     return false;
   }
   return !resolveCtx()?.follow;
@@ -51,10 +51,10 @@ const validateOutputSchema = (
 // ---------------------------------------------------------------------------
 
 /**
- * Verify that every trail and hike implementation output matches its declared
+ * Verify that every trail implementation output matches its declared
  * output schema. Catches implementation-schema drift.
  *
- * Trails and hikes without output schemas or examples are skipped.
+ * Trails without output schemas or examples are skipped.
  */
 export const testContracts = (
   app: Topo,
@@ -87,7 +87,7 @@ export const testContracts = (
           const validated = validateInput(t.input, example.input);
           const validatedInput = expectOk(validated);
 
-          const result = await t.implementation(validatedInput, testCtx);
+          const result = await t.run(validatedInput, testCtx);
           const resultValue = expectOk(result);
 
           validateOutputSchema(outputSchema, resultValue, t.id, example.name);

package/src/examples.ts

@@ -3,14 +3,13 @@
  *
  * 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,
   Topo,
   TrailExample,
@@ -138,12 +137,12 @@ const runExample = async (
   }
   const validatedInput = expectOk(validated);
 
-  const result = await t.implementation(validatedInput, testCtx);
+  const result = await t.run(validatedInput, testCtx);
   assertProgressiveMatch(result, example, output);
 };
 
 // ---------------------------------------------------------------------------
-// Follows coverage for hikes
+// Follow coverage for composition trails
 // ---------------------------------------------------------------------------
 
 /**
@@ -172,7 +171,7 @@ const createCoverageFollow = (
       if (validated.isErr()) {
         return Promise.resolve(validated);
       }
-      return Promise.resolve(trailDef.implementation(validated.value, ctx));
+      return Promise.resolve(trailDef.run(validated.value, ctx));
     }
 
     return Promise.resolve(Result.ok());
@@ -181,17 +180,17 @@ 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
 ): Promise<void> => {
-  const validated = validateInput(hikeDef.input, example.input);
+  const validated = validateInput(trailDef.input, example.input);
 
   if (handleValidationError(validated, example)) {
     return;
@@ -201,75 +200,10 @@ const runHikeExample = async (
   const follow = createCoverageFollow(called, baseCtx.follow, topo, baseCtx);
   const testCtx: TrailContext = { ...baseCtx, follow };
 
-  const result = await hikeDef.implementation(validatedInput, testCtx);
+  const result = await trailDef.run(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([]);
-      });
-    }
-  });
-};
-
 // ---------------------------------------------------------------------------
 // testExamples
 // ---------------------------------------------------------------------------
@@ -277,7 +211,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:
@@ -291,24 +225,54 @@ export const testExamples = (
 ): void => {
   const resolveCtx =
     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 testCtx = mergeTestContext(resolveCtx());
+          await runExample(t, example, output, testCtx);
+        }
+      );
+    });
+  }
 
-    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 baseCtx = mergeTestContext(resolveCtx());
+          await runCompositionExample(t, example, output, baseCtx, called, app);
+        }
+      );
+
+      test('follow coverage', () => {
+        const uncovered = t.follow.filter((id) => !called.has(id));
+        expect(uncovered).toEqual([]);
+      });
+    });
+  }
 };