@ontrails/testing 1.0.0-beta.13 → 1.0.0-beta.15

package/src/__tests__/crosses.test.ts

@@ -1,7 +1,7 @@
 import { describe } from 'bun:test';
 
 import type { AnyTrail, TrailContext } from '@ontrails/core';
-import { InternalError, Result, provision, trail } from '@ontrails/core';
+import { InternalError, Result, resource, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import { testCrosses } from '../crosses.js';
@@ -228,27 +228,27 @@ describe('testCrosses: nested cross chain (A → B → C)', () => {
   );
 });
 
-const mockDbProvision = provision('db.mock.crosses', {
+const mockDbResource = resource('db.mock.crosses', {
   create: () => Result.ok({ source: 'factory' }),
   mock: () => ({ source: 'mock' }),
 });
 
-const provisionLeafTrail = trail('provision.leaf', {
+const provisionLeafTrail = trail('resource.leaf', {
   blaze: (_input, ctx) =>
-    Result.ok({ childSource: mockDbProvision.from(ctx).source }),
-  description: 'Leaf trail that reads from a provision',
+    Result.ok({ childSource: mockDbResource.from(ctx).source }),
+  description: 'Leaf trail that reads from a resource',
   input: z.object({}),
   output: z.object({ childSource: z.string() }),
-  provisions: [mockDbProvision],
+  resources: [mockDbResource],
 });
 
-const provisionRootTrail = trail('provision.root', {
+const provisionRootTrail = trail('resource.root', {
   blaze: async (_input, ctx: TrailContext) => {
     if (!ctx.cross) {
       return Result.err(new Error('cross not available'));
     }
     const childResult = await ctx.cross<{ childSource: string }>(
-      'provision.leaf',
+      'resource.leaf',
       {}
     );
     if (childResult.isErr()) {
@@ -257,46 +257,46 @@ const provisionRootTrail = trail('provision.root', {
 
     return Result.ok({
       childSource: childResult.value.childSource,
-      rootSource: mockDbProvision.from(ctx).source,
+      rootSource: mockDbResource.from(ctx).source,
     });
   },
-  crosses: ['provision.leaf'],
+  crosses: ['resource.leaf'],
   description:
-    'Root trail that reads from a provision and crosses a child trail',
+    'Root trail that reads from a resource and crosses a child trail',
   input: z.object({}),
   output: z.object({ childSource: z.string(), rootSource: z.string() }),
-  provisions: [mockDbProvision],
+  resources: [mockDbResource],
 });
 
 const provisionTrailsMap = new Map<string, AnyTrail>([
-  ['provision.leaf', provisionLeafTrail],
+  ['resource.leaf', provisionLeafTrail],
 ]);
 
-const statefulMockDbProvision = provision('db.mock.crosses.stateful', {
+const statefulMockDbResource = resource('db.mock.crosses.stateful', {
   create: () => Result.ok({ count: 0 }),
   mock: () => ({ count: 0 }),
 });
 
-const statefulProvisionLeafTrail = trail('provision.stateful.leaf', {
+const statefulResourceLeafTrail = trail('resource.stateful.leaf', {
   blaze: (_input, ctx) =>
-    Result.ok({ childCount: statefulMockDbProvision.from(ctx).count }),
-  description: 'Leaf trail that observes the current mock provision state',
+    Result.ok({ childCount: statefulMockDbResource.from(ctx).count }),
+  description: 'Leaf trail that observes the current mock resource state',
   input: z.object({}),
   output: z.object({ childCount: z.number() }),
-  provisions: [statefulMockDbProvision],
+  resources: [statefulMockDbResource],
 });
 
-const statefulProvisionRootTrail = trail('provision.stateful.root', {
+const statefulResourceRootTrail = trail('resource.stateful.root', {
   blaze: async (_input, ctx: TrailContext) => {
     if (!ctx.cross) {
       return Result.err(new Error('cross not available'));
     }
 
-    const statefulProvision = statefulMockDbProvision.from(ctx);
-    statefulProvision.count += 1;
+    const statefulResource = statefulMockDbResource.from(ctx);
+    statefulResource.count += 1;
 
     const childResult = await ctx.cross<{ childCount: number }>(
-      'provision.stateful.leaf',
+      'resource.stateful.leaf',
       {}
     );
     if (childResult.isErr()) {
@@ -305,46 +305,46 @@ const statefulProvisionRootTrail = trail('provision.stateful.root', {
 
     return Result.ok({
       childCount: childResult.value.childCount,
-      rootCount: statefulProvision.count,
+      rootCount: statefulResource.count,
     });
   },
-  crosses: ['provision.stateful.leaf'],
+  crosses: ['resource.stateful.leaf'],
   description:
-    'Root trail that mutates a mocked provision and crosses a child trail',
+    'Root trail that mutates a mocked resource and crosses a child trail',
   input: z.object({}),
   output: z.object({ childCount: z.number(), rootCount: z.number() }),
-  provisions: [statefulMockDbProvision],
+  resources: [statefulMockDbResource],
 });
 
-const statefulProvisionTrailsMap = new Map<string, AnyTrail>([
-  ['provision.stateful.leaf', statefulProvisionLeafTrail],
+const statefulResourceTrailsMap = new Map<string, AnyTrail>([
+  ['resource.stateful.leaf', statefulResourceLeafTrail],
 ]);
 
-const scenarioStateProvision = provision('db.mock.scenarios', {
+const scenarioStateResource = resource('db.mock.scenarios', {
   create: () => Result.ok({ count: 0 }),
   mock: () => ({ count: 0 }),
 });
 
-const scenarioLeafTrail = trail('provision.scenario.leaf', {
+const scenarioLeafTrail = trail('resource.scenario.leaf', {
   blaze: (_input, ctx) =>
-    Result.ok({ count: scenarioStateProvision.from(ctx).count }),
+    Result.ok({ count: scenarioStateResource.from(ctx).count }),
   description: 'Leaf trail that reads mutable scenario state',
   input: z.object({}),
   output: z.object({ count: z.number() }),
-  provisions: [scenarioStateProvision],
+  resources: [scenarioStateResource],
 });
 
-const scenarioRootTrail = trail('provision.scenario.root', {
+const scenarioRootTrail = trail('resource.scenario.root', {
   blaze: async (_input, ctx: TrailContext) => {
     if (!ctx.cross) {
       return Result.err(new Error('cross not available'));
     }
 
-    const state = scenarioStateProvision.from(ctx);
+    const state = scenarioStateResource.from(ctx);
     state.count += 1;
 
     const leafResult = await ctx.cross<{ count: number }>(
-      'provision.scenario.leaf',
+      'resource.scenario.leaf',
       {}
     );
     if (leafResult.isErr()) {
@@ -353,15 +353,15 @@ const scenarioRootTrail = trail('provision.scenario.root', {
 
     return Result.ok({ count: leafResult.value.count });
   },
-  crosses: ['provision.scenario.leaf'],
+  crosses: ['resource.scenario.leaf'],
   description: 'Root trail that mutates scenario state and crosses a leaf',
   input: z.object({}),
   output: z.object({ count: z.number() }),
-  provisions: [scenarioStateProvision],
+  resources: [scenarioStateResource],
 });
 
-const scenarioProvisionTrailsMap = new Map<string, AnyTrail>([
-  ['provision.scenario.leaf', scenarioLeafTrail],
+const scenarioResourceTrailsMap = new Map<string, AnyTrail>([
+  ['resource.scenario.leaf', scenarioLeafTrail],
 ]);
 
 const transformedCrossLeafTrail = trail('cross.transformed.leaf', {
@@ -399,28 +399,28 @@ const transformedCrossTrailsMap = new Map<string, AnyTrail>([
   ['cross.transformed.leaf', transformedCrossLeafTrail],
 ]);
 
-const undeclaredCrossProvision = provision('db.undeclared.crosses', {
+const undeclaredCrossResource = resource('db.undeclared.crosses', {
   create: () => Result.ok({ source: 'factory' }),
   mock: () => ({ source: 'mock' }),
 });
 
-const undeclaredProvisionLeafTrail = trail('provision.undeclared.leaf', {
+const undeclaredResourceLeafTrail = trail('resource.undeclared.leaf', {
   blaze: (_input, ctx) =>
-    Result.ok({ childSource: undeclaredCrossProvision.from(ctx).source }),
-  description: 'Leaf trail that declares the shared provision',
+    Result.ok({ childSource: undeclaredCrossResource.from(ctx).source }),
+  description: 'Leaf trail that declares the shared resource',
   input: z.object({}),
   output: z.object({ childSource: z.string() }),
-  provisions: [undeclaredCrossProvision],
+  resources: [undeclaredCrossResource],
 });
 
-const undeclaredProvisionRootTrail = trail('provision.undeclared.root', {
+const undeclaredResourceRootTrail = trail('resource.undeclared.root', {
   blaze: async (_input, ctx: TrailContext) => {
     if (!ctx.cross) {
       return Result.err(new Error('cross not available'));
     }
 
     const childResult = await ctx.cross<{ childSource: string }>(
-      'provision.undeclared.leaf',
+      'resource.undeclared.leaf',
       {}
     );
     if (childResult.isErr()) {
@@ -429,46 +429,46 @@ const undeclaredProvisionRootTrail = trail('provision.undeclared.root', {
 
     return Result.ok({
       childSource: childResult.value.childSource,
-      rootSource: undeclaredCrossProvision.from(ctx).source,
+      rootSource: undeclaredCrossResource.from(ctx).source,
     });
   },
-  crosses: ['provision.undeclared.leaf'],
-  description: 'Root trail that uses a provision without declaring it',
+  crosses: ['resource.undeclared.leaf'],
+  description: 'Root trail that uses a resource without declaring it',
   input: z.object({}),
   output: z.object({ childSource: z.string(), rootSource: z.string() }),
 });
 
-const undeclaredProvisionTrailsMap = new Map<string, AnyTrail>([
-  ['provision.undeclared.leaf', undeclaredProvisionLeafTrail],
+const undeclaredResourceTrailsMap = new Map<string, AnyTrail>([
+  ['resource.undeclared.leaf', undeclaredResourceLeafTrail],
 ]);
 
-const unrelatedCrossProvision = provision('db.unrelated.crosses', {
+const unrelatedCrossResource = resource('db.unrelated.crosses', {
   create: () => Result.ok({ source: 'factory' }),
   mock: () => {
     throw new Error('unrelated mock should not be resolved');
   },
 });
 
-const unrelatedProvisionTrail = trail('provision.unrelated', {
+const unrelatedResourceTrail = trail('resource.unrelated', {
   blaze: (_input, ctx) =>
-    Result.ok({ source: unrelatedCrossProvision.from(ctx).source }),
+    Result.ok({ source: unrelatedCrossResource.from(ctx).source }),
   description: 'Trail that should not be traversed or mocked',
   input: z.object({}),
   output: z.object({ source: z.string() }),
-  provisions: [unrelatedCrossProvision],
+  resources: [unrelatedCrossResource],
 });
 
-const unrelatedProvisionTrailsMap = new Map<string, AnyTrail>([
-  ['provision.unrelated', unrelatedProvisionTrail],
+const unrelatedResourceTrailsMap = new Map<string, AnyTrail>([
+  ['resource.unrelated', unrelatedResourceTrail],
 ]);
 
-describe('testCrosses provision mocks', () => {
+describe('testCrosses resource mocks', () => {
   // eslint-disable-next-line jest/require-hook
   testCrosses(
     provisionRootTrail,
     [
       {
-        description: 'propagates auto-resolved provision mocks through cross',
+        description: 'propagates auto-resolved resource mocks through cross',
         expectValue: { childSource: 'mock', rootSource: 'mock' },
         input: {},
       },
@@ -477,39 +477,39 @@ describe('testCrosses provision mocks', () => {
   );
 });
 
-describe('testCrosses provision mocks are fresh per scenario', () => {
+describe('testCrosses resource mocks are fresh per scenario', () => {
   // eslint-disable-next-line jest/require-hook
   testCrosses(
     scenarioRootTrail,
     [
       {
-        description: 'first scenario sees a fresh mutable provision',
+        description: 'first scenario sees a fresh mutable resource',
         expectValue: { count: 1 },
         input: {},
       },
       {
-        description: 'second scenario also sees a fresh mutable provision',
+        description: 'second scenario also sees a fresh mutable resource',
         expectValue: { count: 1 },
         input: {},
       },
     ],
-    { trails: scenarioProvisionTrailsMap }
+    { trails: scenarioResourceTrailsMap }
   );
 });
 
-describe('testCrosses explicit provision overrides', () => {
+describe('testCrosses explicit resource overrides', () => {
   // eslint-disable-next-line jest/require-hook
   testCrosses(
     provisionRootTrail,
     [
       {
-        description: 'propagates explicit provision overrides through cross',
+        description: 'propagates explicit resource overrides through cross',
         expectValue: { childSource: 'override', rootSource: 'override' },
         input: {},
       },
     ],
     {
-      provisions: { 'db.mock.crosses': { source: 'override' } },
+      resources: { 'db.mock.crosses': { source: 'override' } },
       trails: provisionTrailsMap,
     }
   );
@@ -530,19 +530,19 @@ describe('testCrosses raw transformed input', () => {
   );
 });
 
-describe('testCrosses provision declarations', () => {
+describe('testCrosses resource declarations', () => {
   // eslint-disable-next-line jest/require-hook
   testCrosses(
-    undeclaredProvisionRootTrail,
+    undeclaredResourceRootTrail,
     [
       {
-        description: 'fails when the root trail omits a required provision',
+        description: 'fails when the root trail omits a required resource',
         expectErr: InternalError,
-        expectErrMessage: undeclaredCrossProvision.id,
+        expectErrMessage: undeclaredCrossResource.id,
         input: {},
       },
     ],
-    { trails: undeclaredProvisionTrailsMap }
+    { trails: undeclaredResourceTrailsMap }
   );
 });
 
@@ -552,7 +552,7 @@ describe('testCrosses only resolves mocks for trails under test', () => {
     provisionRootTrail,
     [
       {
-        description: 'unrelated provision mocks are not resolved',
+        description: 'unrelated resource mocks are not resolved',
         expectValue: { childSource: 'mock', rootSource: 'mock' },
         input: {},
       },
@@ -560,28 +560,28 @@ describe('testCrosses only resolves mocks for trails under test', () => {
     {
       trails: new Map<string, AnyTrail>([
         ...provisionTrailsMap.entries(),
-        ...unrelatedProvisionTrailsMap.entries(),
+        ...unrelatedResourceTrailsMap.entries(),
       ]),
     }
   );
 });
 
-describe('testCrosses fresh provision mocks per scenario', () => {
+describe('testCrosses fresh resource mocks per scenario', () => {
   // eslint-disable-next-line jest/require-hook
   testCrosses(
-    statefulProvisionRootTrail,
+    statefulResourceRootTrail,
     [
       {
-        description: 'first scenario gets a fresh provision mock',
+        description: 'first scenario gets a fresh resource mock',
         expectValue: { childCount: 1, rootCount: 1 },
         input: {},
       },
       {
-        description: 'second scenario also gets a fresh provision mock',
+        description: 'second scenario also gets a fresh resource mock',
         expectValue: { childCount: 1, rootCount: 1 },
         input: {},
       },
     ],
-    { trails: statefulProvisionTrailsMap }
+    { trails: statefulResourceTrailsMap }
   );
 });

package/src/__tests__/detours.test.ts

@@ -1,47 +1,163 @@
-import { describe, test } from 'bun:test';
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 
-import { Result, trail, topo } from '@ontrails/core';
+import { ConflictError, Result, trail, topo } from '@ontrails/core';
 import { z } from 'zod';
 
 import { testDetours } from '../detours.js';
 
-// ---------------------------------------------------------------------------
-// Test trails
-// ---------------------------------------------------------------------------
-
 const showTrail = trail('entity.show', {
   blaze: (input: { id: string }) => Result.ok({ id: input.id }),
-  detours: {
-    related: ['entity.list'],
-  },
+  detours: [
+    {
+      on: ConflictError,
+      /* oxlint-disable-next-line require-await -- test stub */
+      recover: async () => Result.ok({ id: 'recovered' }),
+    },
+  ],
   input: z.object({ id: z.string() }),
 });
 
-const listTrail = trail('entity.list', {
-  blaze: () => Result.ok([]),
+const noDetoursTrail = trail('entity.plain', {
+  blaze: () => Result.ok('ok'),
   input: z.object({}),
 });
 
-const noDetoursTrail = trail('entity.plain', {
-  blaze: () => Result.ok('ok'),
+const createBlankNamedDetourTrail = () => {
+  class BlankNamedConflictError extends ConflictError {}
+
+  Object.defineProperty(BlankNamedConflictError, 'name', { value: '' });
+
+  return trail('entity.blank-name', {
+    blaze: (input: { id: string }) => Result.ok({ id: input.id }),
+    detours: [
+      {
+        on: BlankNamedConflictError,
+        /* oxlint-disable-next-line require-await -- test stub */
+        recover: async () => Result.ok({ id: 'recovered' }),
+      },
+    ],
+    input: z.object({ id: z.string() }),
+  });
+};
+
+const repoTempDir = (): string =>
+  join(
+    resolve(import.meta.dir, '../..'),
+    '.tmp-tests',
+    `test-detours-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+
+const generatedSuiteSource = (
+  variant: 'invalidOn' | 'invalidRecover' | 'shadowed'
+): string => {
+  const shared = `import { ConflictError, Result, TrailsError, trail, topo } from '@ontrails/core';
+import { testDetours } from '../../src/index.ts';
+import { z } from 'zod';
+
+const baseTrail = trail('entity.save', {
+  blaze: () => Result.err(new ConflictError('conflict')),
+  detours: [
+    {
+      on: ConflictError,
+      recover: async () => Result.ok({ recovered: true }),
+    },
+  ],
+  input: z.object({}),
+  output: z.object({ recovered: z.boolean() }),
+});
+`;
+
+  if (variant === 'invalidOn') {
+    return `${shared}
+const candidate = {
+  ...baseTrail,
+  detours: [
+    {
+      on: 'ConflictError',
+      recover: async () => Result.ok({ recovered: true }),
+    },
+  ],
+} as typeof baseTrail;
+
+testDetours(topo('detour-invalid-on', { candidate } as Record<string, unknown>));
+`;
+  }
+
+  if (variant === 'invalidRecover') {
+    return `${shared}
+const candidate = {
+  ...baseTrail,
+  detours: [
+    {
+      on: ConflictError,
+      recover: 'not callable',
+    },
+  ],
+} as typeof baseTrail;
+
+testDetours(topo('detour-invalid-recover', { candidate } as Record<string, unknown>));
+`;
+  }
+
+  return `${shared}
+const candidate = trail('entity.shadowed', {
+  blaze: () => Result.err(new ConflictError('conflict')),
+  detours: [
+    {
+      on: TrailsError,
+      recover: async () => Result.ok({ recovered: 'broad' }),
+    },
+    {
+      on: ConflictError,
+      recover: async () => Result.ok({ recovered: 'specific' }),
+    },
+  ],
   input: z.object({}),
+  output: z.object({ recovered: z.string() }),
 });
 
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
+testDetours(topo('detour-shadowed', { candidate }));
+`;
+};
+
+const runGeneratedDetourSuite = (
+  variant: 'invalidOn' | 'invalidRecover' | 'shadowed'
+): { readonly exitCode: number; readonly output: string } => {
+  const dir = repoTempDir();
+  const testFile = join(dir, `${variant}.test.ts`);
 
-describe('testDetours: all targets exist', () => {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(testFile, generatedSuiteSource(variant));
+
+  try {
+    const proc = Bun.spawnSync({
+      cmd: ['bun', 'test', testFile, '--bail'],
+      cwd: resolve(import.meta.dir, '..', '..', '..'),
+      stderr: 'pipe',
+      stdout: 'pipe',
+    });
+
+    return {
+      exitCode: proc.exitCode,
+      output: `${proc.stdout.toString()}\n${proc.stderr.toString()}`,
+    };
+  } finally {
+    rmSync(dir, { force: true, recursive: true });
+  }
+};
+
+describe('testDetours valid contracts', () => {
   // eslint-disable-next-line jest/require-hook
   testDetours(
     topo('test-app', {
-      listTrail,
       showTrail,
     } as Record<string, unknown>)
   );
 });
 
-describe('testDetours: skips trails without detours', () => {
+describe('testDetours skips trails without detours', () => {
   // eslint-disable-next-line jest/require-hook
   testDetours(
     topo('test-app', {
@@ -53,3 +169,44 @@ describe('testDetours: skips trails without detours', () => {
     // Trail without detours is skipped -- no detour tests generated
   });
 });
+
+describe('testDetours constructor handling', () => {
+  // eslint-disable-next-line jest/require-hook
+  testDetours(
+    topo('test-app', {
+      blankNamedDetourTrail: createBlankNamedDetourTrail(),
+    } as Record<string, unknown>)
+  );
+});
+
+describe('testDetours invalid contract detection', () => {
+  test('fails when on is not an error constructor', () => {
+    const result = runGeneratedDetourSuite('invalidOn');
+
+    expect(result.exitCode).toBe(1);
+    expect(result.output).toContain(
+      'entity.save detour[0] must declare a real error constructor in on:'
+    );
+  });
+
+  test('fails when recover is not callable', () => {
+    const result = runGeneratedDetourSuite('invalidRecover');
+
+    expect(result.exitCode).toBe(1);
+    expect(result.output).toContain(
+      'entity.save detour[0] on ConflictError must declare a callable recover function'
+    );
+  });
+
+  test('fails when a later detour is shadowed by an earlier broader detour', () => {
+    const result = runGeneratedDetourSuite('shadowed');
+
+    expect(result.exitCode).toBe(1);
+    expect(result.output).toContain(
+      'entity.shadowed detour[1] on ConflictError'
+    );
+    expect(result.output).toContain(
+      'shadowed by earlier detour[0] on TrailsError'
+    );
+  });
+});