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

package/src/__tests__/follows.test.ts

@@ -1,163 +0,0 @@
-import { describe } from 'bun:test';
-
-import type { AnyTrail, TrailContext } from '@ontrails/core';
-import { Result, trail } from '@ontrails/core';
-import { z } from 'zod';
-
-import { testFollows } from '../follows.js';
-
-// ---------------------------------------------------------------------------
-// Test trails (followed by composition trail)
-// ---------------------------------------------------------------------------
-
-const addTrail = trail('entity.add', {
-  description: 'Add an entity',
-  examples: [
-    { input: { name: 'Alpha' }, name: 'success' },
-    {
-      description: 'duplicate name',
-      error: 'AlreadyExistsError',
-      input: { name: '' },
-      name: 'duplicate',
-    },
-  ],
-  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',
-  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 }),
-});
-
-// ---------------------------------------------------------------------------
-// Composition trail
-// ---------------------------------------------------------------------------
-
-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
-  ) => {
-    if (!ctx.follow) {
-      return Result.err(new Error('follow not available'));
-    }
-    const addResult = await ctx.follow<{ id: string; name: string }>(
-      'entity.add',
-      { name: input.name }
-    );
-    if (addResult.isErr()) {
-      return Result.err(addResult.error);
-    }
-
-    const relateResult = await ctx.follow<{ from: string; to: string }>(
-      'entity.relate',
-      { from: addResult.value.name, to: input.relatedTo }
-    );
-    if (relateResult.isErr()) {
-      return Result.err(relateResult.error);
-    }
-
-    return Result.ok({
-      name: addResult.value.name,
-      relatedTo: relateResult.value.to,
-    });
-  },
-});
-
-const trailsMap = new Map<string, AnyTrail>([
-  ['entity.add', addTrail],
-  ['entity.relate', relateTrail],
-]);
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-const opts = { trails: trailsMap };
-
-describe('testFollows: expectOk', () => {
-  // eslint-disable-next-line jest/require-hook
-  testFollows(
-    onboardTrail,
-    [
-      {
-        description: 'basic onboard succeeds',
-        expectOk: true,
-        input: { name: 'Alpha', relatedTo: 'Beta' },
-      },
-    ],
-    opts
-  );
-});
-
-describe('testFollows: expectFollowed', () => {
-  // eslint-disable-next-line jest/require-hook
-  testFollows(
-    onboardTrail,
-    [
-      {
-        description: 'follows add then relate in order',
-        expectFollowed: ['entity.add', 'entity.relate'],
-        expectOk: true,
-        input: { name: 'Alpha', relatedTo: 'Beta' },
-      },
-    ],
-    opts
-  );
-});
-
-describe('testFollows: expectFollowedCount', () => {
-  // eslint-disable-next-line jest/require-hook
-  testFollows(
-    onboardTrail,
-    [
-      {
-        description: 'each trail followed exactly once',
-        expectFollowedCount: { 'entity.add': 1, 'entity.relate': 1 },
-        expectOk: true,
-        input: { name: 'Alpha', relatedTo: 'Beta' },
-      },
-    ],
-    opts
-  );
-});
-
-describe('testFollows: injectFromExample', () => {
-  // eslint-disable-next-line jest/require-hook
-  testFollows(
-    onboardTrail,
-    [
-      {
-        description: 'inject duplicate error from add trail example',
-        expectErr: Error,
-        expectErrMessage: 'AlreadyExistsError',
-        injectFromExample: { 'entity.add': 'duplicate' },
-        input: { name: 'Alpha', relatedTo: 'Beta' },
-      },
-    ],
-    opts
-  );
-});
-
-describe('testFollows: expectValue', () => {
-  // eslint-disable-next-line jest/require-hook
-  testFollows(
-    onboardTrail,
-    [
-      {
-        description: 'exact value match',
-        expectValue: { name: 'Alpha', relatedTo: 'Beta' },
-        input: { name: 'Alpha', relatedTo: 'Beta' },
-      },
-    ],
-    opts
-  );
-});

package/src/__tests__/logger.test.ts

@@ -1,136 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import { createTestLogger } from '../logger.js';
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('createTestLogger: basic operations', () => {
-  test('captures info entries', () => {
-    const logger = createTestLogger();
-    logger.info('hello');
-    logger.warn('world');
-    expect(logger.entries).toHaveLength(2);
-    const [first] = logger.entries;
-    expect(first).toBeDefined();
-    expect(first?.level).toBe('info');
-    expect(first?.message).toBe('hello');
-  });
-
-  test('captures warn entries', () => {
-    const logger = createTestLogger();
-    logger.info('hello');
-    logger.warn('world');
-    const [, second] = logger.entries;
-    expect(second).toBeDefined();
-    expect(second?.level).toBe('warn');
-    expect(second?.message).toBe('world');
-  });
-
-  test('entries contain all logged records', () => {
-    const logger = createTestLogger();
-    logger.trace('t');
-    logger.debug('d');
-    logger.info('i');
-    logger.warn('w');
-    logger.error('e');
-    logger.fatal('f');
-    expect(logger.entries).toHaveLength(6);
-  });
-
-  test('clear() empties the entries array', () => {
-    const logger = createTestLogger();
-    logger.info('one');
-    logger.info('two');
-    expect(logger.entries).toHaveLength(2);
-    logger.clear();
-    expect(logger.entries).toHaveLength(0);
-  });
-
-  test('find() filters entries by predicate', () => {
-    const logger = createTestLogger();
-    logger.info('alpha');
-    logger.warn('beta');
-    logger.info('gamma');
-
-    const warnings = logger.find((r) => r.level === 'warn');
-    expect(warnings).toHaveLength(1);
-    expect(warnings[0]?.message).toBe('beta');
-  });
-});
-
-describe('createTestLogger: assertLogged', () => {
-  test('passes when matching entry exists', () => {
-    const logger = createTestLogger();
-    logger.info('operation completed');
-    expect(() => logger.assertLogged('info', 'completed')).not.toThrow();
-  });
-
-  test('fails when no matching entry exists', () => {
-    const logger = createTestLogger();
-    logger.info('something else');
-    expect(() => logger.assertLogged('error', 'not found')).toThrow(
-      /Expected a log entry/
-    );
-  });
-});
-
-describe('createTestLogger: child loggers', () => {
-  test('child() captures to the same entries array', () => {
-    const logger = createTestLogger();
-    const child = logger.child({ component: 'db' });
-
-    logger.info('parent message');
-    child.info('child message');
-
-    expect(logger.entries).toHaveLength(2);
-    expect(logger.entries[0]?.message).toBe('parent message');
-    expect(logger.entries[1]?.message).toBe('child message');
-    expect(logger.entries[1]?.metadata).toEqual({ component: 'db' });
-  });
-
-  test('child logger inherits parent metadata', () => {
-    const logger = createTestLogger();
-    const child = logger.child({ requestId: 'abc' });
-    const grandchild = child.child({ trailId: 'greet' });
-
-    grandchild.info('deep log');
-
-    expect(logger.entries).toHaveLength(1);
-    expect(logger.entries[0]?.metadata).toEqual({
-      requestId: 'abc',
-      trailId: 'greet',
-    });
-  });
-});
-
-describe('createTestLogger: configuration', () => {
-  test('respects minimum log level', () => {
-    const logger = createTestLogger({ level: 'warn' });
-    logger.debug('should be filtered');
-    logger.info('also filtered');
-    logger.warn('should appear');
-    logger.error('also appears');
-    expect(logger.entries).toHaveLength(2);
-    expect(logger.entries[0]?.level).toBe('warn');
-    expect(logger.entries[1]?.level).toBe('error');
-  });
-
-  test('has name property', () => {
-    const logger = createTestLogger();
-    expect(logger.name).toBe('test');
-  });
-
-  test('entries have timestamps', () => {
-    const logger = createTestLogger();
-    logger.info('timestamped');
-    expect(logger.entries[0]?.timestamp).toBeInstanceOf(Date);
-  });
-
-  test('entries have category matching logger name', () => {
-    const logger = createTestLogger();
-    logger.info('categorized');
-    expect(logger.entries[0]?.category).toBe('test');
-  });
-});

package/src/__tests__/trail.test.ts

@@ -1,99 +0,0 @@
-import { describe } from 'bun:test';
-
-import { NotFoundError, Result, ValidationError, trail } from '@ontrails/core';
-import { z } from 'zod';
-
-import { testTrail } from '../trail.js';
-
-// ---------------------------------------------------------------------------
-// Test trails
-// ---------------------------------------------------------------------------
-
-const greetTrail = trail('greet', {
-  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', {
-  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 });
-  },
-});
-
-// ---------------------------------------------------------------------------
-// Tests
-//
-// Each call to testTrail registers describe/test blocks.
-// We call them at the describe scope so bun:test can discover them.
-// ---------------------------------------------------------------------------
-
-describe('testTrail: expectOk', () => {
-  // eslint-disable-next-line jest/require-hook
-  testTrail(greetTrail, [
-    { description: 'valid greeting', expectOk: true, input: { name: 'Bob' } },
-  ]);
-});
-
-describe('testTrail: expectValue', () => {
-  // eslint-disable-next-line jest/require-hook
-  testTrail(greetTrail, [
-    {
-      description: 'exact match',
-      expectValue: { greeting: 'Hello, Charlie' },
-      input: { name: 'Charlie' },
-    },
-  ]);
-});
-
-describe('testTrail: expectErr', () => {
-  // eslint-disable-next-line jest/require-hook
-  testTrail(failTrail, [
-    {
-      description: 'not found error',
-      expectErr: NotFoundError,
-      input: { id: 'missing' },
-    },
-  ]);
-});
-
-describe('testTrail: expectErrMessage', () => {
-  // eslint-disable-next-line jest/require-hook
-  testTrail(failTrail, [
-    {
-      description: 'error message contains substring',
-      expectErr: NotFoundError,
-      expectErrMessage: 'Not found',
-      input: { id: 'missing' },
-    },
-  ]);
-});
-
-describe('testTrail: invalid input with ValidationError', () => {
-  // eslint-disable-next-line jest/require-hook
-  testTrail(greetTrail, [
-    {
-      description: 'invalid input caught by validation',
-      expectErr: ValidationError,
-      input: { name: 123 },
-    },
-  ]);
-});
-
-describe('testTrail: multiple scenarios', () => {
-  // eslint-disable-next-line jest/require-hook
-  testTrail(greetTrail, [
-    { description: 'scenario 1', expectOk: true, input: { name: 'A' } },
-    { description: 'scenario 2', expectOk: true, input: { name: 'B' } },
-    {
-      description: 'scenario 3',
-      expectValue: { greeting: 'Hello, C' },
-      input: { name: 'C' },
-    },
-  ]);
-});

package/src/follows.ts

@@ -1,283 +0,0 @@
-/**
- * testFollows — composition-aware scenario testing for trails with follow.
- *
- * Tests the follow graph: which trails were followed, in what order,
- * and supports failure injection from followed trail examples.
- */
-
-import { describe, expect, test } from 'bun:test';
-
-import type { AnyTrail, FollowFn, TrailContext } from '@ontrails/core';
-import {
-  InternalError,
-  Result,
-  ValidationError,
-  validateInput,
-} from '@ontrails/core';
-
-import {
-  assertErrorMatch,
-  assertFullMatch,
-  assertSchemaMatch,
-  expectOk,
-} from './assertions.js';
-import { mergeTestContext } from './context.js';
-import type { FollowScenario } from './types.js';
-
-// ---------------------------------------------------------------------------
-// Follow trace
-// ---------------------------------------------------------------------------
-
-interface FollowRecord {
-  readonly id: string;
-  readonly input: unknown;
-}
-
-// ---------------------------------------------------------------------------
-// Injection helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Find an error example on a trail by name or description substring.
- */
-const findErrorExample = (
-  trailDef: AnyTrail,
-  description: string
-): string | undefined => {
-  const example = trailDef.examples?.find(
-    (ex) =>
-      ex.error !== undefined &&
-      (ex.description?.includes(description) || ex.name.includes(description))
-  );
-  return example?.error;
-};
-
-/**
- * Try to inject an error from a followed trail's example.
- * Returns undefined when no injection is configured for this trail ID.
- */
-const tryInjectError = (
-  id: string,
-  scenario: FollowScenario,
-  trailsMap: ReadonlyMap<string, AnyTrail> | undefined
-): Result<unknown, Error> | undefined => {
-  const injection = scenario.injectFromExample?.[id];
-  if (injection === undefined) {
-    return undefined;
-  }
-
-  const trailDef = trailsMap?.get(id);
-  if (trailDef === undefined) {
-    return Result.err(
-      new InternalError(`Cannot inject: trail "${id}" not in topo`)
-    );
-  }
-  const errorName = findErrorExample(trailDef, injection);
-  if (errorName === undefined) {
-    return Result.err(
-      new InternalError(
-        `No error example matching "${injection}" on trail "${id}"`
-      )
-    );
-  }
-  return Result.err(new Error(errorName));
-};
-
-/**
- * Execute a trail from the map, validating input first.
- */
-const executeFromMap = (
-  id: string,
-  input: unknown,
-  trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
-  ctx: TrailContext
-): Result<unknown, Error> | Promise<Result<unknown, Error>> | undefined => {
-  const trailDef = trailsMap?.get(id);
-  if (trailDef === undefined) {
-    return undefined;
-  }
-
-  const validated = validateInput(trailDef.input, input);
-  if (validated.isErr()) {
-    return validated;
-  }
-  return trailDef.run(validated.value, ctx);
-};
-
-// ---------------------------------------------------------------------------
-// Follow factory
-// ---------------------------------------------------------------------------
-
-/**
- * Build a recording follow function that optionally injects errors.
- */
-const createRecordingFollow = (
-  trace: FollowRecord[],
-  scenario: FollowScenario,
-  trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
-  baseFollow: FollowFn | undefined,
-  ctx: TrailContext
-): FollowFn => {
-  // The generic O on FollowFn is erased at runtime; the cast is safe
-  // because callers narrow via isOk/isErr before accessing the value.
-  const follow = (id: string, input: unknown) => {
-    trace.push({ id, input });
-
-    const injected = tryInjectError(id, scenario, trailsMap);
-    if (injected !== undefined) {
-      return Promise.resolve(injected);
-    }
-
-    if (baseFollow !== undefined) {
-      return baseFollow(id, input);
-    }
-
-    const executed = executeFromMap(id, input, trailsMap, ctx);
-    if (executed !== undefined) {
-      return Promise.resolve(executed);
-    }
-
-    return Promise.resolve(Result.ok());
-  };
-  return follow as FollowFn;
-};
-
-// ---------------------------------------------------------------------------
-// Scenario assertions
-// ---------------------------------------------------------------------------
-
-const assertScenarioResult = (
-  result: Result<unknown, Error>,
-  scenario: FollowScenario,
-  trailDef: AnyTrail
-): void => {
-  if (scenario.expectValue !== undefined) {
-    assertFullMatch(result, scenario.expectValue);
-  } else if (scenario.expectErr !== undefined) {
-    assertErrorMatch(result, scenario.expectErr, scenario.expectErrMessage);
-  } else if (scenario.expectErrMessage !== undefined) {
-    expect(result.isErr()).toBe(true);
-    if (result.isErr()) {
-      expect(result.error.message).toContain(scenario.expectErrMessage);
-    }
-  } else if (scenario.expectOk === true) {
-    expect(result.isOk()).toBe(true);
-    assertSchemaMatch(result, trailDef.output);
-  }
-};
-
-const assertFollowTrace = (
-  trace: readonly FollowRecord[],
-  scenario: FollowScenario
-): void => {
-  if (scenario.expectFollowed !== undefined) {
-    const followedIds = trace.map((r) => r.id);
-    expect(followedIds).toEqual([...scenario.expectFollowed]);
-  }
-  if (scenario.expectFollowedCount !== undefined) {
-    const counts: Record<string, number> = {};
-    for (const record of trace) {
-      counts[record.id] = (counts[record.id] ?? 0) + 1;
-    }
-    expect(counts).toEqual({ ...scenario.expectFollowedCount });
-  }
-};
-
-const handleValidationError = (
-  validated: Result<unknown, Error>,
-  scenario: FollowScenario
-): boolean => {
-  if (!validated.isErr()) {
-    return false;
-  }
-  if (scenario.expectErr === ValidationError) {
-    expect(validated.error).toBeInstanceOf(ValidationError);
-    if (scenario.expectErrMessage !== undefined) {
-      expect(validated.error.message).toContain(scenario.expectErrMessage);
-    }
-    return true;
-  }
-  throw new Error(
-    `Input validation failed unexpectedly: ${validated.error.message}`
-  );
-};
-
-// ---------------------------------------------------------------------------
-// Scenario runner
-// ---------------------------------------------------------------------------
-
-const buildTestContext = (
-  scenario: FollowScenario,
-  ctx: Partial<TrailContext> | undefined,
-  trailsMap: ReadonlyMap<string, AnyTrail> | undefined
-): { trace: FollowRecord[]; testCtx: TrailContext } => {
-  const trace: FollowRecord[] = [];
-  const baseCtx = mergeTestContext(ctx);
-  const follow = createRecordingFollow(
-    trace,
-    scenario,
-    trailsMap,
-    baseCtx.follow,
-    baseCtx
-  );
-  return { testCtx: { ...baseCtx, follow }, trace };
-};
-
-const runScenario = async (
-  trailDef: AnyTrail,
-  scenario: FollowScenario,
-  ctx: Partial<TrailContext> | undefined,
-  trailsMap: ReadonlyMap<string, AnyTrail> | undefined
-): Promise<void> => {
-  const validated = validateInput(trailDef.input, scenario.input);
-  if (handleValidationError(validated, scenario)) {
-    return;
-  }
-
-  const { trace, testCtx } = buildTestContext(scenario, ctx, trailsMap);
-  const result = await trailDef.run(expectOk(validated), testCtx);
-  assertFollowTrace(trace, scenario);
-  assertScenarioResult(result, scenario, trailDef);
-};
-
-// ---------------------------------------------------------------------------
-// testFollows
-// ---------------------------------------------------------------------------
-
-/** Options for testFollows that provide trail definitions for injection. */
-export interface TestFollowOptions {
-  /** Partial context overrides. */
-  readonly ctx?: Partial<TrailContext> | undefined;
-  /** Map of trail ID to trail definition, used for injectFromExample. */
-  readonly trails?: ReadonlyMap<string, AnyTrail> | undefined;
-}
-
-/**
- * Generate a describe block for a composition trail with one test per scenario.
- *
- * @example
- * ```ts
- * testFollows(onboardTrail, [
- *   {
- *     description: "follows add then relate",
- *     input: { name: "Alpha" },
- *     expectOk: true,
- *     expectFollowed: ["entity.add", "entity.relate"],
- *   },
- * ]);
- * ```
- */
-export const testFollows = (
-  trailDef: AnyTrail,
-  scenarios: readonly FollowScenario[],
-  options?: TestFollowOptions
-): void => {
-  describe(trailDef.id, () => {
-    test.each([...scenarios])(
-      '$description',
-      async (scenario: FollowScenario) => {
-        await runScenario(trailDef, scenario, options?.ctx, options?.trails);
-      }
-    );
-  });
-};

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src"],
-  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
-}

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/all.ts","./src/assertions.ts","./src/context.ts","./src/contracts.ts","./src/detours.ts","./src/examples.ts","./src/follows.ts","./src/harness-cli.ts","./src/harness-mcp.ts","./src/index.ts","./src/logger.ts","./src/trail.ts","./src/types.ts"],"version":"5.9.3"}