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

package/src/__tests__/partial-match.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result } from '@ontrails/core';
+
+import { assertPartialMatch } from '../assertions.js';
+
+describe('assertPartialMatch', () => {
+  describe('scalar values', () => {
+    test('passes with exact scalar match', () => {
+      const result = Result.ok('hello');
+      assertPartialMatch(result, 'hello');
+    });
+
+    test('passes with numeric match', () => {
+      const result = Result.ok(42);
+      assertPartialMatch(result, 42);
+    });
+
+    test('fails when scalar does not match', () => {
+      const result = Result.ok('hello');
+      expect(() => assertPartialMatch(result, 'world')).toThrow();
+    });
+  });
+
+  describe('object subset', () => {
+    test('passes with full match', () => {
+      const result = Result.ok({ id: '1', name: 'Alpha', type: 'concept' });
+      assertPartialMatch(result, { id: '1', name: 'Alpha', type: 'concept' });
+    });
+
+    test('passes with partial match (extra keys in actual ignored)', () => {
+      const result = Result.ok({
+        createdAt: '2026-01-01',
+        id: '1',
+        name: 'Alpha',
+        type: 'concept',
+      });
+      assertPartialMatch(result, { name: 'Alpha', type: 'concept' });
+    });
+
+    test('fails when expected key is missing from actual', () => {
+      const result = Result.ok({ id: '1', name: 'Alpha' });
+      expect(() =>
+        assertPartialMatch(result, { missing: true, name: 'Alpha' })
+      ).toThrow();
+    });
+
+    test('fails when expected value does not match', () => {
+      const result = Result.ok({ id: '1', name: 'Alpha' });
+      expect(() => assertPartialMatch(result, { name: 'Beta' })).toThrow();
+    });
+  });
+
+  describe('nested object subset', () => {
+    test('passes with nested partial match', () => {
+      const result = Result.ok({
+        id: '1',
+        meta: { stars: 0, tags: ['a', 'b'], views: 5 },
+      });
+      assertPartialMatch(result, { meta: { stars: 0 } });
+    });
+
+    test('fails when nested value does not match', () => {
+      const result = Result.ok({
+        id: '1',
+        meta: { stars: 0, views: 5 },
+      });
+      expect(() =>
+        assertPartialMatch(result, { meta: { stars: 3 } })
+      ).toThrow();
+    });
+  });
+
+  describe('array subset', () => {
+    test('passes when actual contains all expected elements (order-independent)', () => {
+      const result = Result.ok({
+        tags: ['a', 'b', 'c'],
+      });
+      assertPartialMatch(result, { tags: ['c', 'a'] });
+    });
+
+    test('fails when actual is missing expected array element', () => {
+      const result = Result.ok({
+        tags: ['a', 'b'],
+      });
+      expect(() => assertPartialMatch(result, { tags: ['a', 'z'] })).toThrow();
+    });
+
+    test('fails when expected has duplicate but actual has only one match', () => {
+      const result = Result.ok({
+        tags: ['a', 'b'],
+      });
+      expect(() => assertPartialMatch(result, { tags: ['a', 'a'] })).toThrow();
+    });
+
+    test('passes when expected has duplicate and actual has enough matches', () => {
+      const result = Result.ok({
+        tags: ['a', 'a', 'b'],
+      });
+      assertPartialMatch(result, { tags: ['a', 'a'] });
+    });
+
+    test('fails when expected objects have duplicates but actual has only one', () => {
+      const result = Result.ok({
+        items: [{ id: 1 }],
+      });
+      expect(() =>
+        assertPartialMatch(result, { items: [{ id: 1 }, { id: 1 }] })
+      ).toThrow();
+    });
+
+    test('passes when expected objects have duplicates and actual has enough', () => {
+      const result = Result.ok({
+        items: [{ id: 1 }, { id: 1 }, { id: 2 }],
+      });
+      assertPartialMatch(result, { items: [{ id: 1 }, { id: 1 }] });
+    });
+  });
+
+  describe('error on non-ok result', () => {
+    test('fails when result is an error', () => {
+      const result = Result.err(new Error('boom'));
+      expect(() => assertPartialMatch(result, { id: '1' })).toThrow();
+    });
+  });
+});

package/src/__tests__/scenario.test.ts

@@ -0,0 +1,381 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { TrailContext } from '@ontrails/core';
+import { resource, Result, trail, topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { errResultMatch, okResultMatch } from '../assertions.js';
+import { executeScenarioSteps, ref, scenario } from '../scenario.js';
+import type { ScenarioStep } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Test trails
+// ---------------------------------------------------------------------------
+
+const createTrail = trail('item.create', {
+  blaze: (input: { name: string }) => Result.ok({ id: 'g1', name: input.name }),
+  description: 'Create an item',
+  input: z.object({ name: z.string() }),
+  output: z.object({ id: z.string(), name: z.string() }),
+});
+
+const showTrail = trail('item.show', {
+  blaze: (input: { id: string }) =>
+    Result.ok({ found: true, id: input.id, name: 'Test' }),
+  description: 'Show an item',
+  input: z.object({ id: z.string() }),
+  output: z.object({ found: z.boolean(), id: z.string(), name: z.string() }),
+});
+
+const failTrail = trail('item.fail', {
+  blaze: () => Result.err(new Error('intentional failure')),
+  description: 'Always fails',
+  input: z.object({}),
+  output: z.object({}),
+});
+
+/** A trail that uses ctx.cross() to delegate to item.create. */
+const createViaProxy = trail('item.create-via-proxy', {
+  blaze: (input: { name: string }, ctx: TrailContext) => {
+    const crossFn = ctx.cross;
+    if (!crossFn) {
+      return Promise.resolve(Result.err(new Error('ctx.cross is undefined')));
+    }
+    return crossFn(createTrail, input);
+  },
+  crosses: [createTrail],
+  description: 'Delegates to item.create via ctx.cross()',
+  input: z.object({ name: z.string() }),
+  output: z.object({ id: z.string(), name: z.string() }),
+});
+
+/** A resource with a mock factory. */
+const db = resource<{ query: (sql: string) => string }>('db', {
+  create: () => Result.err(new Error('not wired in tests')),
+  mock: () => ({ query: (sql: string) => `mock:${sql}` }),
+});
+
+/** A trail that uses a resource via ctx.resource(). */
+const queryTrail = trail('item.query', {
+  blaze: (_input: { sql: string }, ctx: TrailContext) => {
+    const instance = db.from(ctx);
+    return Result.ok({ result: instance.query(_input.sql) });
+  },
+  description: 'Run a query via the db resource',
+  input: z.object({ sql: z.string() }),
+  output: z.object({ result: z.string() }),
+  resources: [db],
+});
+
+const app = topo('scenario-test-app', {
+  createTrail,
+  createViaProxy,
+  db,
+  failTrail,
+  queryTrail,
+  showTrail,
+} as Record<string, unknown>);
+
+const readySignal = 'ready';
+type ReadySignal = typeof readySignal;
+
+const concurrentBatchOutput = z.object({ results: z.array(z.unknown()) });
+
+const createReadyController = () => Promise.withResolvers<ReadySignal>();
+
+const requireCrossFn = (
+  ctx: TrailContext
+): NonNullable<TrailContext['cross']> => {
+  expect(ctx.cross).toBeDefined();
+  return ctx.cross as NonNullable<TrailContext['cross']>;
+};
+
+const waitForReadyPair = async (
+  first: Promise<ReadySignal>,
+  second: Promise<ReadySignal>
+): Promise<void> => {
+  await first;
+  await second;
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('ref()', () => {
+  test('creates a RefToken with the given path', () => {
+    const token = ref('create.id');
+    expect(token).toEqual({ __ref: true, path: 'create.id' });
+  });
+});
+
+describe('scenario()', () => {
+  // oxlint-disable-next-line jest/require-hook -- scenario() registers describe/test blocks, not setup code
+  scenario('basic two-step flow', app, [
+    {
+      as: 'created',
+      cross: createTrail,
+      input: { name: 'Hello' },
+    },
+    {
+      cross: showTrail,
+      expectedMatch: { found: true, id: 'g1' },
+      input: { id: ref('created.id') },
+    },
+  ]);
+
+  // oxlint-disable-next-line jest/require-hook -- scenario() registers describe/test blocks, not setup code
+  scenario('ref resolves dot-path from prior step', app, [
+    {
+      as: 'original',
+      cross: createTrail,
+      expected: { id: 'g1', name: 'Test' },
+      input: { name: 'Test' },
+    },
+    {
+      cross: showTrail,
+      input: { id: ref('original.id') },
+    },
+  ]);
+
+  // oxlint-disable-next-line jest/require-hook -- scenario() registers describe/test blocks, not setup code
+  scenario('expectedMatch on a step works', app, [
+    {
+      cross: createTrail,
+      expectedMatch: { name: 'Partial' },
+      input: { name: 'Partial' },
+    },
+  ]);
+
+  // oxlint-disable-next-line jest/require-hook -- scenario() registers describe/test blocks, not setup code
+  scenario('step that uses ctx.cross() receives a bound cross function', app, [
+    {
+      as: 'proxied',
+      cross: createViaProxy,
+      expectedMatch: { id: 'g1', name: 'CrossTest' },
+      input: { name: 'CrossTest' },
+    },
+  ]);
+
+  // Resource mock forwarding
+  // oxlint-disable-next-line jest/require-hook -- scenario() registers describe/test blocks, not setup code
+  scenario('step with resource receives mock from topo', app, [
+    {
+      cross: queryTrail,
+      expected: { result: 'mock:SELECT 1' },
+      input: { sql: 'SELECT 1' },
+    },
+  ]);
+
+  // Step failure reporting
+  describe('step failure reporting', () => {
+    test('reports which step failed', async () => {
+      // We can't use scenario() directly here because it registers
+      // describe/test blocks. Instead, test the error message shape
+      // by importing the internals or checking that the scenario
+      // properly reports failures.
+      // For now, verify that a failing trail in a scenario produces
+      // an informative error.
+      const { executeTrail } = await import('@ontrails/core');
+      const result = await executeTrail(failTrail, {}, { topo: app });
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  // Duplicate alias guard
+  describe('duplicate alias guard', () => {
+    test('throws on duplicate step alias', async () => {
+      const steps: ScenarioStep[] = [
+        { as: 'dup', cross: createTrail, input: { name: 'A' } },
+        { as: 'dup', cross: createTrail, input: { name: 'B' } },
+      ];
+
+      await expect(executeScenarioSteps(app, steps)).rejects.toThrow(
+        'duplicate step alias "dup"'
+      );
+    });
+  });
+});
+
+describe('executeScenarioSteps concurrent crossing support', () => {
+  test('matches concurrent fan-out arrays with ok result helpers', async () => {
+    const alphaTrail = trail('scenario.batch.alpha', {
+      blaze: () => Result.ok({ label: 'alpha' }),
+      input: z.object({}),
+      output: z.object({ label: z.string() }),
+      visibility: 'internal',
+    });
+    const betaTrail = trail('scenario.batch.beta', {
+      blaze: () => Result.ok({ label: 'beta' }),
+      input: z.object({}),
+      output: z.object({ label: z.string() }),
+      visibility: 'internal',
+    });
+    const fanoutTrail = trail('scenario.batch.fanout', {
+      blaze: async (_input, ctx) => {
+        const results = await requireCrossFn(ctx)([
+          [alphaTrail, {}],
+          [betaTrail, {}],
+        ] as const);
+        return Result.ok({ results });
+      },
+      crosses: [alphaTrail, betaTrail],
+      input: z.object({}),
+      output: concurrentBatchOutput,
+    });
+    const fanoutApp = topo('scenario-concurrent-fanout-app', {
+      alphaTrail,
+      betaTrail,
+      fanoutTrail,
+    } as Record<string, unknown>);
+
+    await executeScenarioSteps(fanoutApp, [
+      {
+        cross: fanoutTrail,
+        expectedMatch: {
+          results: [
+            okResultMatch({ label: 'alpha' }),
+            okResultMatch({ label: 'beta' }),
+          ],
+        },
+        input: {},
+      },
+    ]);
+  });
+
+  test('matches mixed ok/err batch results for partial failure scenarios', async () => {
+    const successTrail = trail('scenario.batch.partial.success', {
+      blaze: () => Result.ok({ label: 'success' }),
+      input: z.object({}),
+      output: z.object({ label: z.string() }),
+      visibility: 'internal',
+    });
+    const failureTrail = trail('scenario.batch.partial.failure', {
+      blaze: () => Result.err(new Error('branch failure')),
+      input: z.object({}),
+      output: z.object({}),
+      visibility: 'internal',
+    });
+    const partialTrail = trail('scenario.batch.partial.root', {
+      blaze: async (_input, ctx) => {
+        const results = await requireCrossFn(ctx)([
+          [successTrail, {}],
+          [failureTrail, {}],
+        ] as const);
+        return Result.ok({ results });
+      },
+      crosses: [successTrail, failureTrail],
+      input: z.object({}),
+      output: concurrentBatchOutput,
+    });
+    const partialApp = topo('scenario-partial-failure-app', {
+      failureTrail,
+      partialTrail,
+      successTrail,
+    } as Record<string, unknown>);
+
+    await executeScenarioSteps(partialApp, [
+      {
+        cross: partialTrail,
+        expectedMatch: {
+          results: [
+            okResultMatch({ label: 'success' }),
+            errResultMatch({ message: 'branch failure' }),
+          ],
+        },
+        input: {},
+      },
+    ]);
+  });
+
+  test('respects concurrency limits for scenario ctx.cross batch flows', async () => {
+    const slowStarted = createReadyController();
+    const fastStarted = createReadyController();
+    const releaseFirstBatch = createReadyController();
+    const startedIds: string[] = [];
+    const slowTrail = trail('scenario.batch.limited.slow', {
+      blaze: async () => {
+        startedIds.push('slow');
+        slowStarted.resolve(readySignal);
+        await releaseFirstBatch.promise;
+        await Bun.sleep(20);
+        return Result.ok({ id: 'slow' });
+      },
+      input: z.object({}),
+      output: z.object({ id: z.string() }),
+      visibility: 'internal',
+    });
+    const fastTrail = trail('scenario.batch.limited.fast', {
+      blaze: async () => {
+        startedIds.push('fast');
+        fastStarted.resolve(readySignal);
+        await releaseFirstBatch.promise;
+        await Bun.sleep(1);
+        return Result.ok({ id: 'fast' });
+      },
+      input: z.object({}),
+      output: z.object({ id: z.string() }),
+      visibility: 'internal',
+    });
+    const queuedTrail = trail('scenario.batch.limited.queued', {
+      blaze: () => {
+        startedIds.push('queued');
+        return Result.ok({ id: 'queued' });
+      },
+      input: z.object({}),
+      output: z.object({ id: z.string() }),
+      visibility: 'internal',
+    });
+    const limitedTrail = trail('scenario.batch.limited.root', {
+      blaze: async (_input, ctx) => {
+        const run = requireCrossFn(ctx)(
+          [
+            [slowTrail, {}],
+            [fastTrail, {}],
+            [queuedTrail, {}],
+          ] as const,
+          { concurrency: 2 }
+        );
+        await waitForReadyPair(slowStarted.promise, fastStarted.promise);
+        const startedBeforeRelease = [...startedIds];
+        releaseFirstBatch.resolve(readySignal);
+        const results = await run;
+        return Result.ok({
+          startedBeforeRelease,
+          startedOverall: [...startedIds],
+          successIds: results.flatMap((result) =>
+            result.match({
+              err: () => [] as string[],
+              ok: (value) => [value.id],
+            })
+          ),
+        });
+      },
+      crosses: [slowTrail, fastTrail, queuedTrail],
+      input: z.object({}),
+      output: z.object({
+        startedBeforeRelease: z.array(z.string()),
+        startedOverall: z.array(z.string()),
+        successIds: z.array(z.string()),
+      }),
+    });
+    const limitedApp = topo('scenario-concurrency-limited-app', {
+      fastTrail,
+      limitedTrail,
+      queuedTrail,
+      slowTrail,
+    } as Record<string, unknown>);
+
+    await executeScenarioSteps(limitedApp, [
+      {
+        cross: limitedTrail,
+        expected: {
+          startedBeforeRelease: ['slow', 'fast'],
+          startedOverall: ['slow', 'fast', 'queued'],
+          successIds: ['slow', 'fast', 'queued'],
+        },
+        input: {},
+      },
+    ]);
+  });
+});

package/src/all.ts

@@ -2,18 +2,21 @@
  * testAll — single-line governance suite for any Topo.
  *
  * Wraps topo validation, example execution, contract checks, and detour
- * verification into one describe block.
+ * contract validation into one describe block.
  */
 
 import { describe, expect, test } from 'bun:test';
 
 import type { Topo, TrailContext } from '@ontrails/core';
-import { validateTopo } from '@ontrails/core';
+import { validateEstablishedTopo, validateTopo } from '@ontrails/core';
 
+import { createCliHarness } from './harness-cli.js';
+import { createMcpHarness } from './harness-mcp.js';
 import { testContracts } from './contracts.js';
 import type { TestExecutionOptions } from './context.js';
 import { testDetours } from './detours.js';
 import { testExamples } from './examples.js';
+import type { TestAllEstablishedOptions } from './types.js';
 
 /**
  * Run the full governance test suite for a Topo.
@@ -22,7 +25,7 @@ import { testExamples } from './examples.js';
  * - Structural validation via `validateTopo`
  * - Example execution via `testExamples`
  * - Output contract checks via `testContracts`
- * - Detour target verification via `testDetours`
+ * - Detour contract validation via `testDetours`
  *
  * Accepts either a static context or a factory function that produces a
  * fresh context per test (useful when the context contains mutable state
@@ -31,22 +34,53 @@ import { testExamples } from './examples.js';
  * @example
  * ```ts
  * import { testAll } from '@ontrails/testing';
- * import { app } from '../src/app.js';
+ * import { graph } from '../src/app.js';
  *
- * testAll(app);
+ * testAll(graph);
  * ```
  */
-export const testAll = (
+type TestAllInput =
+  | Partial<TrailContext>
+  | TestExecutionOptions
+  | (() => Partial<TrailContext> | TestExecutionOptions);
+
+const formatValidationFailure = (error: Error): string => {
+  const issues = (
+    error as {
+      context?: { issues?: readonly Record<string, unknown>[] };
+    }
+  ).context?.issues;
+
+  if (issues === undefined || issues.length === 0) {
+    return error.message;
+  }
+
+  const details = issues.map((issue) => {
+    const id = typeof issue['id'] === 'string' ? issue['id'] : undefined;
+    const message =
+      typeof issue['message'] === 'string' ? issue['message'] : undefined;
+    const rule = typeof issue['rule'] === 'string' ? issue['rule'] : undefined;
+
+    return [rule, id, message].filter(Boolean).join(': ');
+  });
+
+  return [error.message, ...details].join('\n');
+};
+
+const assertValidTopo = (result: ReturnType<typeof validateTopo>): void => {
+  if (result.isErr()) {
+    throw new Error(formatValidationFailure(result.error));
+  }
+};
+
+const registerGovernanceSuite = (
   topo: Topo,
-  ctxOrFactory?:
-    | Partial<TrailContext>
-    | TestExecutionOptions
-    | (() => Partial<TrailContext> | TestExecutionOptions)
+  ctxOrFactory: TestAllInput | undefined,
+  validate: (topo: Topo) => ReturnType<typeof validateTopo>
 ): void => {
   describe('governance', () => {
     test('topo validates', () => {
-      const result = validateTopo(topo);
-      expect(result.isOk()).toBe(true);
+      expect(() => assertValidTopo(validate(topo))).not.toThrow();
     });
 
     // oxlint-disable-next-line jest/require-hook -- these generate describe/test blocks, not setup code
@@ -57,3 +91,106 @@ export const testAll = (
     testDetours(topo);
   });
 };
+
+export const testAll = (topo: Topo, ctxOrFactory?: TestAllInput): void => {
+  registerGovernanceSuite(topo, ctxOrFactory, validateTopo);
+};
+
+type EstablishedInput =
+  | Partial<TrailContext>
+  | TestAllEstablishedOptions
+  | (() => Partial<TrailContext> | TestAllEstablishedOptions);
+
+const isEstablishedOptions = (
+  input: Partial<TrailContext> | TestAllEstablishedOptions | undefined
+): input is TestAllEstablishedOptions =>
+  input !== undefined &&
+  (Object.hasOwn(input, 'cli') ||
+    Object.hasOwn(input, 'createPermit') ||
+    Object.hasOwn(input, 'ctx') ||
+    Object.hasOwn(input, 'mcp') ||
+    Object.hasOwn(input, 'resources') ||
+    Object.hasOwn(input, 'strictPermits'));
+
+const normalizeEstablishedOptions = (
+  input?: Partial<TrailContext> | TestAllEstablishedOptions
+): TestAllEstablishedOptions =>
+  isEstablishedOptions(input) ? input : { ctx: input };
+
+const toExecutionOptions = (
+  options: TestAllEstablishedOptions
+): TestExecutionOptions => ({
+  ...(options.createPermit === undefined
+    ? {}
+    : { createPermit: options.createPermit }),
+  ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
+  ...(options.resources === undefined ? {} : { resources: options.resources }),
+  ...(options.strictPermits === undefined
+    ? {}
+    : { strictPermits: options.strictPermits }),
+});
+
+const toCliHarnessOptions = (
+  topo: Topo,
+  options: TestAllEstablishedOptions
+) => {
+  const cliOptions = {
+    graph: topo,
+    ...options.cli,
+  };
+
+  if (options.ctx !== undefined) {
+    cliOptions.ctx = options.ctx;
+  }
+
+  return cliOptions;
+};
+
+const toMcpHarnessOptions = (
+  topo: Topo,
+  options: TestAllEstablishedOptions
+) => ({
+  graph: topo,
+  ...options.mcp,
+});
+
+const registerEstablishedSurfaceSuite = (
+  topo: Topo,
+  resolveInput: () =>
+    | Partial<TrailContext>
+    | TestAllEstablishedOptions
+    | undefined
+): void => {
+  describe('surfaces', () => {
+    test('CLI projection validates established topo', () => {
+      const options = normalizeEstablishedOptions(resolveInput());
+      expect(() =>
+        createCliHarness(toCliHarnessOptions(topo, options))
+      ).not.toThrow();
+    });
+
+    test('MCP projection validates established topo', () => {
+      const options = normalizeEstablishedOptions(resolveInput());
+      expect(() =>
+        createMcpHarness(toMcpHarnessOptions(topo, options))
+      ).not.toThrow();
+    });
+  });
+};
+
+export const testAllEstablished = (
+  topo: Topo,
+  optionsOrFactory?: EstablishedInput
+): void => {
+  const resolveInput =
+    typeof optionsOrFactory === 'function'
+      ? optionsOrFactory
+      : () => optionsOrFactory;
+
+  registerGovernanceSuite(
+    topo,
+    () => toExecutionOptions(normalizeEstablishedOptions(resolveInput())),
+    validateEstablishedTopo
+  );
+  registerEstablishedSurfaceSuite(topo, resolveInput);
+};