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

package/README.md

@@ -1,14 +1,14 @@
 # @ontrails/testing
 
-Contract-driven testing for Trails. Add examples to your trails, then `testAll(app)` runs them as assertions, validates output schemas, checks composition graphs, and verifies structural integrity. One line of test code, full governance.
+Contract-driven testing for Trails. Add examples to your trails, then `testAll(graph)` runs them as assertions, validates output schemas, checks composition graphs, and verifies structural integrity. One line of test code, full contract coverage.
 
 ## Usage
 
 ```typescript
 import { testAll } from '@ontrails/testing';
-import { app } from '../app';
+import { graph } from '../app';
 
-testAll(app);
+testAll(graph);
 ```
 
 That single call covers example execution, contract validation, detour checks, and topo validation. For most apps, this is all you need.
@@ -18,25 +18,23 @@ If you want finer control:
 ```typescript
 import { testExamples, testContracts, testDetours } from '@ontrails/testing';
 
-testExamples(app);   // Run every trail's examples as tests
-testContracts(app);  // Validate outputs against declared schemas
-testDetours(app);    // Verify detour targets exist
+testExamples(graph);   // Run every trail's examples as tests
+testContracts(graph);  // Validate outputs against declared schemas
+testDetours(graph);    // Validate detour constructor, recover, and ordering semantics
 ```
 
 ## API
 
 | Export | What it does |
 | --- | --- |
-| `testAll(topo, ctx?)` | Single-line governance suite: validation + examples + contracts + detours |
+| `testAll(topo, ctx?)` | Single-line contract suite: validation + examples + contracts + detours |
 | `testExamples(topo, ctx?)` | Run trail examples as `describe`/`test` blocks |
-| `testTrail(trail, scenarios)` | Custom scenarios for edge cases and error paths |
-| `testHike(hike, scenarios)` | Test composition graphs -- follow chains, failure injection |
-| `testContracts(topo, ctx?)` | Validate implementation output against declared schemas |
-| `testDetours(topo)` | Verify every detour target exists in the topo |
+| `testTrail(trail, scenarios)` | Custom scenarios for edge cases, error paths, and composition chains |
+| `testContracts(topo, ctx?)` | Validate output against declared schemas |
+| `testDetours(topo)` | Validate detour constructor, recover, and shadowing semantics |
+| `createComposeContext(options?)` | Mock `ComposeFn` for testing composite trails; returns preconfigured `Result` values keyed by trail ID |
 | `createTestContext(options?)` | `TrailContext` with sensible test defaults |
 | `createTestLogger()` | Logger that captures entries in memory for assertions |
-| `createCliHarness(options)` | Execute CLI commands in-process, capture stdout/stderr |
-| `createMcpHarness(options)` | Invoke MCP tools directly without transport |
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
@@ -55,37 +53,103 @@ testTrail(showTrail, [
 ]);
 ```
 
-## testHike
+## Testing composition (trails with composes)
 
-Where `testTrail` exercises a single trail, `testHike` exercises the follow graph:
+`testTrail` works the same for trails with `composes` -- it exercises the composition graph:
 
 ```typescript
-import { testHike } from '@ontrails/testing';
+import { testTrail } from '@ontrails/testing';
 
-testHike(onboardHike, [
+testTrail(onboardTrail, [
   { description: 'happy path', input: { name: 'Delta', type: 'tool' }, expectOk: true },
   { description: 'add fails', input: { name: 'Alpha' }, expectErr: AlreadyExistsError },
 ]);
 ```
 
-## Surface harnesses
+When you need to isolate a composite trail and stub out its dependencies, use `createComposeContext`:
+
+```typescript
+import { createComposeContext, testTrail } from '@ontrails/testing';
+import { Result } from '@ontrails/core';
+
+const compose = createComposeContext({
+  responses: {
+    'entity.add': Result.ok({ id: '1', name: 'Delta', type: 'tool' }),
+    'search': Result.ok({ results: [] }),
+  },
+});
+testTrail(onboardTrail, [
+  {
+    description: 'uses mocked composes',
+    input: { name: 'Delta', type: 'tool' },
+    expectOk: true,
+  },
+], { compose });
+```
+
+Calls to unregistered trail IDs return `Result.err` with a descriptive message, so missing stubs fail loudly.
+
+## Surface Harnesses
+
+Surface harnesses live on explicit subpaths so projects that only import contract helpers from `@ontrails/testing` do not need CLI, MCP, or HTTP peers. Install the peer package for the subpath you use:
+
+- `@ontrails/testing/cli` requires `@ontrails/cli`
+- `@ontrails/testing/mcp` requires `@ontrails/mcp`
+- `@ontrails/testing/http` requires `@ontrails/http`
+- `@ontrails/testing/established` and `@ontrails/testing/surface-parity`
+  require all three shipped surface peers
 
 ```typescript
-import { createCliHarness, createMcpHarness } from '@ontrails/testing';
+import { createCliHarness } from '@ontrails/testing/cli';
+import { createHttpHarness } from '@ontrails/testing/http';
+import { createMcpHarness } from '@ontrails/testing/mcp';
 
 // CLI
-const cli = createCliHarness({ app });
+const cli = createCliHarness({ graph });
 const result = await cli.run('entity show --name Alpha --output json');
 expect(result.exitCode).toBe(0);
 
 // MCP
-const mcp = createMcpHarness({ app });
+const mcp = createMcpHarness({ graph });
 const tool = await mcp.callTool('myapp_entity_show', { name: 'Alpha' });
 expect(tool.isError).toBe(false);
+
+// HTTP
+const http = createHttpHarness({ graph });
+const response = await http.get('/entity/show', { name: 'Alpha' });
+expect(response.status).toBe(200);
+```
+
+Use `testAllEstablished()` from `@ontrails/testing/established` when an established app should run the root contract suite and validate CLI, MCP, and HTTP projections in one call.
+
+## Surface Parity
+
+`testSurfaceParity()` is a focused gate for established apps that want to prove their examples behave the same through every shipped surface.
+
+```typescript
+import { testSurfaceParity } from '@ontrails/testing/surface-parity';
+import { graph } from '../app';
+
+const createDeterministicTestDb = () => ({});
+
+testSurfaceParity(graph, {
+  createResources: () => ({
+    'db.main': createDeterministicTestDb(),
+  }),
+  exclusions: [
+    {
+      example: 'Creates generated data',
+      reason: 'output includes generated IDs that intentionally differ per surface run',
+      trailId: 'entity.add',
+    },
+  ],
+});
 ```
 
+The helper compares normalized success payloads and normalized TrailsError category/code pairs. CLI command names, MCP tool names, HTTP method/path values, transport envelopes, activation consumers, internal trails, and planned WebSocket work stay outside the equality check. Use `createResources` when examples need deterministic fixtures for each surface invocation, and use exclusions for intentional semantic differences that should not be silently skipped.
+
 ## Installation
 
 ```bash
-bun add -d @ontrails/testing
+bun add -d @ontrails/testing@beta
 ```

package/package.json

@@ -1,9 +1,22 @@
 {
   "name": "@ontrails/testing",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.32",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./cli": "./src/cli.ts",
+    "./established": "./src/all-established.ts",
+    "./http": "./src/http.ts",
+    "./mcp": "./src/mcp.ts",
+    "./surface-parity": "./src/surface-parity.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -13,11 +26,27 @@
     "lint": "oxlint ./src",
     "clean": "rm -rf dist *.tsbuildinfo"
   },
+  "devDependencies": {
+    "@ontrails/drizzle": "^1.0.0-beta.32",
+    "@ontrails/store": "^1.0.0-beta.32"
+  },
   "peerDependencies": {
-    "@ontrails/cli": "^1.0.0-beta.0",
-    "@ontrails/core": "^1.0.0-beta.0",
-    "@ontrails/logging": "^1.0.0-beta.0",
-    "@ontrails/mcp": "^1.0.0-beta.0",
+    "@ontrails/cli": "^1.0.0-beta.32",
+    "@ontrails/core": "^1.0.0-beta.32",
+    "@ontrails/http": "^1.0.0-beta.32",
+    "@ontrails/mcp": "^1.0.0-beta.32",
+    "@ontrails/observe": "^1.0.0-beta.32",
     "zod": "^4.3.5"
+  },
+  "peerDependenciesMeta": {
+    "@ontrails/cli": {
+      "optional": true
+    },
+    "@ontrails/http": {
+      "optional": true
+    },
+    "@ontrails/mcp": {
+      "optional": true
+    }
   }
 }

package/src/all-established.ts

@@ -0,0 +1,168 @@
+/**
+ * testAllEstablished - contract suite plus shipped surface projection checks.
+ *
+ * This helper intentionally lives behind a surface subpath so root
+ * `@ontrails/testing` imports do not pull CLI, MCP, or HTTP peers into
+ * contract-only consumers.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import type { Topo, TrailContext } from '@ontrails/core';
+import { validateEstablishedTopo } from '@ontrails/core';
+
+import { registerContractSuite } from './all.js';
+import type { TestExecutionOptions } from './context.js';
+import { createCliHarness } from './harness-cli.js';
+import type { CliHarnessOptions } from './harness-cli.js';
+import { createHttpHarness } from './harness-http.js';
+import type { HttpHarnessOptions } from './harness-http.js';
+import { createMcpHarness } from './harness-mcp.js';
+import type { McpHarnessOptions } from './harness-mcp.js';
+
+export interface TestAllEstablishedOptions {
+  readonly cli?: Omit<CliHarnessOptions, 'graph'> | undefined;
+  readonly createPermit?:
+    | ((trail: {
+        readonly permit?:
+          | { readonly scopes: readonly string[] }
+          | 'public'
+          | undefined;
+      }) =>
+        | {
+            readonly id: string;
+            readonly scopes: readonly string[];
+          }
+        | undefined)
+    | undefined;
+  readonly ctx?: Partial<TrailContext> | undefined;
+  readonly http?: Omit<HttpHarnessOptions, 'graph'> | undefined;
+  readonly mcp?: Omit<McpHarnessOptions, 'graph'> | undefined;
+  readonly resources?: Record<string, unknown> | undefined;
+  readonly strictPermits?: boolean | undefined;
+}
+
+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, 'http') ||
+    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 toHttpHarnessOptions = (
+  topo: Topo,
+  options: TestAllEstablishedOptions
+) => {
+  const httpOptions = {
+    graph: topo,
+    ...options.http,
+  };
+
+  if (options.ctx !== undefined) {
+    httpOptions.ctx = options.ctx;
+  }
+
+  return httpOptions;
+};
+
+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();
+    });
+
+    test('HTTP projection validates established topo', () => {
+      const options = normalizeEstablishedOptions(resolveInput());
+      expect(() =>
+        createHttpHarness(toHttpHarnessOptions(topo, options))
+      ).not.toThrow();
+    });
+  });
+};
+
+export const testAllEstablished = (
+  topo: Topo,
+  optionsOrFactory?: EstablishedInput
+): void => {
+  const resolveInput =
+    typeof optionsOrFactory === 'function'
+      ? optionsOrFactory
+      : () => optionsOrFactory;
+
+  registerContractSuite(
+    topo,
+    () => toExecutionOptions(normalizeEstablishedOptions(resolveInput())),
+    validateEstablishedTopo
+  );
+  registerEstablishedSurfaceSuite(topo, resolveInput);
+};
+
+export type { TestAllInput } from './all.js';

package/src/all.ts

@@ -1,8 +1,8 @@
 /**
- * testAll — single-line governance suite for any Topo.
+ * testAll — single-line contract 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';
@@ -11,17 +11,18 @@ import type { Topo, TrailContext } from '@ontrails/core';
 import { validateTopo } from '@ontrails/core';
 
 import { testContracts } from './contracts.js';
+import type { TestExecutionOptions } from './context.js';
 import { testDetours } from './detours.js';
 import { testExamples } from './examples.js';
 
 /**
- * Run the full governance test suite for a Topo.
+ * Run the full contract test suite for a Topo.
  *
- * Generates a `governance` describe block containing:
+ * Generates a `contract` describe block containing:
  * - 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
@@ -30,19 +31,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 = (
+export 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));
+  }
+};
+
+export const registerContractSuite = (
   topo: Topo,
-  ctxOrFactory?: Partial<TrailContext> | (() => Partial<TrailContext>)
+  ctxOrFactory: TestAllInput | undefined,
+  validate: (topo: Topo) => ReturnType<typeof validateTopo>
 ): void => {
-  describe('governance', () => {
+  describe('contract', () => {
     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
@@ -53,3 +88,7 @@ export const testAll = (
     testDetours(topo);
   });
 };
+
+export const testAll = (topo: Topo, ctxOrFactory?: TestAllInput): void => {
+  registerContractSuite(topo, ctxOrFactory, validateTopo);
+};