@ontrails/testing 1.0.0-beta.0

package/src/__tests__/contracts.test.ts

@@ -0,0 +1,68 @@
+import { describe, test } from 'bun:test';
+
+import { Result, trail, topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { testContracts } from '../contracts.js';
+
+// ---------------------------------------------------------------------------
+// Test trails
+// ---------------------------------------------------------------------------
+
+/** Trail whose implementation matches the output schema. */
+const validTrail = trail('valid', {
+  examples: [
+    {
+      expected: { id: 1, name: 'Alpha' },
+      input: { name: 'Alpha' },
+      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() }),
+});
+
+/** 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() }),
+});
+
+/** 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() }),
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('testContracts: valid output matches schema', () => {
+  // eslint-disable-next-line jest/require-hook
+  testContracts(topo('test-app', { validTrail } as Record<string, unknown>));
+});
+
+describe('testContracts: skips trails without output schemas', () => {
+  // eslint-disable-next-line jest/require-hook
+  testContracts(topo('test-app', { noSchemaTrail } as Record<string, unknown>));
+
+  test('no-op marker', () => {
+    // Trail without output schema is skipped -- no contract tests generated
+  });
+});
+
+describe('testContracts: skips trails without examples', () => {
+  // eslint-disable-next-line jest/require-hook
+  testContracts(
+    topo('test-app', { noExamplesTrail } as Record<string, unknown>)
+  );
+
+  test('no-op marker', () => {
+    // Trail without examples is skipped -- no contract tests generated
+  });
+});

package/src/__tests__/detours.test.ts

@@ -0,0 +1,55 @@
+import { describe, test } from 'bun:test';
+
+import { Result, trail, topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { testDetours } from '../detours.js';
+
+// ---------------------------------------------------------------------------
+// Test trails
+// ---------------------------------------------------------------------------
+
+const showTrail = trail('entity.show', {
+  detours: {
+    related: ['entity.list'],
+  },
+  implementation: (input: { id: string }) => Result.ok({ id: input.id }),
+  input: z.object({ id: z.string() }),
+});
+
+const listTrail = trail('entity.list', {
+  implementation: () => Result.ok([]),
+  input: z.object({}),
+});
+
+const noDetoursTrail = trail('entity.plain', {
+  implementation: () => Result.ok('ok'),
+  input: z.object({}),
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('testDetours: all targets exist', () => {
+  // eslint-disable-next-line jest/require-hook
+  testDetours(
+    topo('test-app', {
+      listTrail,
+      showTrail,
+    } as Record<string, unknown>)
+  );
+});
+
+describe('testDetours: skips trails without detours', () => {
+  // eslint-disable-next-line jest/require-hook
+  testDetours(
+    topo('test-app', {
+      noDetoursTrail,
+    } as Record<string, unknown>)
+  );
+
+  test('no-op marker', () => {
+    // Trail without detours is skipped -- no detour tests generated
+  });
+});

package/src/__tests__/examples.test.ts

@@ -0,0 +1,176 @@
+import { describe, test } from 'bun:test';
+
+import { NotFoundError, Result, hike, trail, topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { testExamples } from '../examples.js';
+
+// ---------------------------------------------------------------------------
+// Test trails
+// ---------------------------------------------------------------------------
+
+const greetTrail = trail('greet', {
+  description: 'Greet someone',
+  examples: [
+    {
+      expected: { greeting: 'Hello, Alice' },
+      input: { name: 'Alice' },
+      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() }),
+});
+
+const searchTrail = trail('search', {
+  description: 'Search for things',
+  examples: [
+    {
+      input: { query: 'test' },
+      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()) }),
+});
+
+const entityTrail = trail('entity.show', {
+  description: 'Show entity',
+  examples: [
+    {
+      expected: { id: 1, name: 'Alpha' },
+      input: { name: 'Alpha' },
+      name: 'Show entity by name',
+    },
+    {
+      error: 'NotFoundError',
+      input: { name: 'missing' },
+      name: 'Entity not found returns NotFoundError',
+    },
+  ],
+  implementation: (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() }),
+});
+
+// ---------------------------------------------------------------------------
+// Test hikes (for follows 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() }),
+});
+
+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() }),
+});
+
+const onboardHike = hike('entity.onboard', {
+  description: 'Onboard a new entity',
+  examples: [
+    {
+      expected: { id: '1', name: 'Alpha' },
+      input: { name: 'Alpha' },
+      name: 'Onboard Alpha',
+    },
+  ],
+  follows: ['entity.add', 'entity.relate'],
+  implementation: async (input: { name: string }, ctx) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('follow not available'));
+    }
+    const addResult = await ctx.follow('entity.add', input);
+    if (addResult.isErr()) {
+      return addResult;
+    }
+    const relateResult = await ctx.follow('entity.relate', {
+      from: 'root',
+      to: (addResult.value as { id: string }).id,
+    });
+    if (relateResult.isErr()) {
+      return relateResult;
+    }
+    return Result.ok({ id: '1', name: input.name });
+  },
+  input: z.object({ name: z.string() }),
+  output: z.object({ id: z.string(), name: z.string() }),
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('testExamples', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('test-app', {
+      entityTrail,
+      greetTrail,
+      noExamplesTrail,
+      searchTrail,
+    } as Record<string, unknown>)
+  );
+
+  // Also test with custom context (static form)
+  describe('with custom context', () => {
+    // eslint-disable-next-line jest/require-hook
+    testExamples(topo('ctx-app', { greetTrail } as Record<string, unknown>), {
+      requestId: 'custom-request',
+    });
+  });
+
+  // Test with factory form (each test gets a fresh context)
+  describe('with context factory', () => {
+    // eslint-disable-next-line jest/require-hook
+    testExamples(
+      topo('factory-app', { greetTrail } as Record<string, unknown>),
+      () => ({ requestId: `factory-${crypto.randomUUID()}` })
+    );
+  });
+});
+
+describe('testExamples skips trails with no examples', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('skip-app', {
+      noExamplesTrail,
+    } as Record<string, unknown>)
+  );
+
+  test('no-op marker', () => {
+    // This test exists so the describe block is not empty
+  });
+});
+
+describe('testExamples follows coverage for hikes', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('hike-app', {
+      addTrail,
+      onboardHike,
+      relateTrail,
+    } as Record<string, unknown>)
+  );
+});

package/src/__tests__/hike.test.ts

@@ -0,0 +1,164 @@
+import { describe } from 'bun:test';
+
+import type { AnyTrail, TrailContext } from '@ontrails/core';
+import { Result, hike, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { testHike } from '../hike.js';
+
+// ---------------------------------------------------------------------------
+// Test trails (followed by hikes)
+// ---------------------------------------------------------------------------
+
+const addTrail = trail('entity.add', {
+  description: 'Add an entity',
+  examples: [
+    { input: { name: 'Alpha' }, name: 'success' },
+    {
+      description: 'duplicate name',
+      error: 'AlreadyExistsError',
+      input: { name: '' },
+      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() }),
+});
+
+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() }),
+});
+
+// ---------------------------------------------------------------------------
+// Test hike
+// ---------------------------------------------------------------------------
+
+const onboardHike = hike('entity.onboard', {
+  follows: ['entity.add', 'entity.relate'],
+  implementation: 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,
+    });
+  },
+  input: z.object({ name: z.string(), relatedTo: z.string() }),
+  output: z.object({ name: z.string(), relatedTo: z.string() }),
+});
+
+const trailsMap = new Map<string, AnyTrail>([
+  ['entity.add', addTrail],
+  ['entity.relate', relateTrail],
+]);
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+const opts = { trails: trailsMap };
+
+describe('testHike: expectOk', () => {
+  // eslint-disable-next-line jest/require-hook
+  testHike(
+    onboardHike,
+    [
+      {
+        description: 'basic onboard succeeds',
+        expectOk: true,
+        input: { name: 'Alpha', relatedTo: 'Beta' },
+      },
+    ],
+    opts
+  );
+});
+
+describe('testHike: expectFollowed', () => {
+  // eslint-disable-next-line jest/require-hook
+  testHike(
+    onboardHike,
+    [
+      {
+        description: 'follows add then relate in order',
+        expectFollowed: ['entity.add', 'entity.relate'],
+        expectOk: true,
+        input: { name: 'Alpha', relatedTo: 'Beta' },
+      },
+    ],
+    opts
+  );
+});
+
+describe('testHike: expectFollowedCount', () => {
+  // eslint-disable-next-line jest/require-hook
+  testHike(
+    onboardHike,
+    [
+      {
+        description: 'each trail followed exactly once',
+        expectFollowedCount: { 'entity.add': 1, 'entity.relate': 1 },
+        expectOk: true,
+        input: { name: 'Alpha', relatedTo: 'Beta' },
+      },
+    ],
+    opts
+  );
+});
+
+describe('testHike: injectFromExample', () => {
+  // eslint-disable-next-line jest/require-hook
+  testHike(
+    onboardHike,
+    [
+      {
+        description: 'inject duplicate error from add trail example',
+        expectErr: Error,
+        expectErrMessage: 'AlreadyExistsError',
+        injectFromExample: { 'entity.add': 'duplicate' },
+        input: { name: 'Alpha', relatedTo: 'Beta' },
+      },
+    ],
+    opts
+  );
+});
+
+describe('testHike: expectValue', () => {
+  // eslint-disable-next-line jest/require-hook
+  testHike(
+    onboardHike,
+    [
+      {
+        description: 'exact value match',
+        expectValue: { name: 'Alpha', relatedTo: 'Beta' },
+        input: { name: 'Alpha', relatedTo: 'Beta' },
+      },
+    ],
+    opts
+  );
+});

package/src/__tests__/logger.test.ts

@@ -0,0 +1,136 @@
+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

@@ -0,0 +1,99 @@
+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', {
+  implementation: (input: { name: string }) =>
+    Result.ok({ greeting: `Hello, ${input.name}` }),
+  input: z.object({ name: z.string() }),
+  output: z.object({ greeting: z.string() }),
+});
+
+const failTrail = trail('fail', {
+  implementation: (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() }),
+});
+
+// ---------------------------------------------------------------------------
+// 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' },
+    },
+  ]);
+});