@ontrails/testing 1.0.0-beta.0 → 1.0.0-beta.1

package/.turbo/turbo-lint.log

@@ -1,3 +1,3 @@
 $ oxlint ./src
 Found 0 warnings and 0 errors.
-Finished in 109ms on 20 files with 93 rules using 24 threads.
+Finished in 27ms on 20 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @ontrails/testing
 
+## 1.0.0-beta.1
+
+### Patch Changes
+
+- Fix two blocking bugs from real-world migration:
+  - Published packages now resolve correctly (workspace:^ instead of workspace:\*)
+  - Error forwarding works across different success types (Err no longer carries phantom T)
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.1
+  - @ontrails/cli@1.0.0-beta.1
+  - @ontrails/mcp@1.0.0-beta.1
+  - @ontrails/logging@1.0.0-beta.1
+
 ## 1.0.0-beta.0
 
 ### Minor Changes

package/README.md

@@ -1,40 +1,8 @@
 # @ontrails/testing
 
-Contract-driven testing utilities for Trails. Write examples for agent fluency -- get test cases for free.
+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.
 
-## Installation
-
-```bash
-bun add -d @ontrails/testing
-```
-
-Peer dependencies: `@ontrails/core`, `@ontrails/cli`, `@ontrails/mcp`, `@ontrails/logging`, `zod`.
-
-## Quick Start
-
-```typescript
-import { testExamples } from '@ontrails/testing';
-import { app } from '../app';
-
-testExamples(app);
-```
-
-One line. The entire topo is tested. Every trail, every example: input validation, implementation execution, output verification.
-
-```text
- PASS  src/__tests__/app.test.ts
-  greet
-    example: Basic greeting
-    example: Loud greeting
-  entity.show
-    example: Show entity by name
-```
-
-## API Overview
-
-### `testAll(topo, ctx?)`
-
-Single-line governance suite. Wraps topo validation, example execution, contract checks, and detour verification into one `governance` describe block:
+## Usage
 
 ```typescript
 import { testAll } from '@ontrails/testing';
@@ -43,26 +11,38 @@ import { app } from '../app';
 testAll(app);
 ```
 
-For most apps, `testAll` is the only test call you need.
+That single call covers example execution, contract validation, detour checks, and topo validation. For most apps, this is all you need.
 
-### `testExamples(app, ctx?)`
+If you want finer control:
 
-For each trail with `examples`, generates `describe`/`test` blocks using the Bun test runner.
+```typescript
+import { testExamples, testContracts, testDetours } from '@ontrails/testing';
 
-Per example:
+testExamples(app);   // Run every trail's examples as tests
+testContracts(app);  // Validate outputs against declared schemas
+testDetours(app);    // Verify detour targets exist
+```
 
-1. Validates `example.input` against the trail's Zod schema
-2. Calls the implementation with validated input
-3. Applies progressive assertion (see below)
-4. Validates output against the trail's output schema (if present)
+## API
 
-Trails with no examples produce no tests.
+| Export | What it does |
+| --- | --- |
+| `testAll(topo, ctx?)` | Single-line governance 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 |
+| `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 |
 
-The runtime implementation is always awaited, so `testExamples()` behaves the same for sync-authored and async-authored trails.
+See the [API Reference](../../docs/api-reference.md) for the full list.
 
-### `testTrail(trail, scenarios, ctx?)`
+## testTrail
 
-Custom scenarios for edge cases, boundary values, and regressions that do not belong in agent-facing examples:
+For edge cases that do not belong in agent-facing examples:
 
 ```typescript
 import { testTrail } from '@ontrails/testing';
@@ -71,151 +51,41 @@ import { ValidationError, NotFoundError } from '@ontrails/core';
 testTrail(showTrail, [
   { description: 'empty name', input: { name: '' }, expectOk: true },
   { description: 'missing name', input: {}, expectErr: ValidationError },
-  {
-    description: 'exact match',
-    input: { name: 'Alpha' },
-    expectValue: { name: 'Alpha', type: 'concept' },
-  },
-  {
-    description: 'not found',
-    input: { name: 'missing' },
-    expectErr: NotFoundError,
-    expectErrMessage: 'not found',
-  },
+  { description: 'not found', input: { name: 'missing' }, expectErr: NotFoundError },
 ]);
 ```
 
-### `testHike(hike, scenarios, ctx?)`
+## testHike
 
-Tests a hike's composition graph -- follow chains, failure injection, and multi-trail interactions:
+Where `testTrail` exercises a single trail, `testHike` exercises the follow graph:
 
 ```typescript
 import { testHike } from '@ontrails/testing';
 
 testHike(onboardHike, [
-  { description: 'successful onboard', input: { name: 'Delta', type: 'tool' }, expectOk: true },
-  { description: 'fails when add fails', input: { name: 'Alpha' }, expectErr: AlreadyExistsError },
+  { description: 'happy path', input: { name: 'Delta', type: 'tool' }, expectOk: true },
+  { description: 'add fails', input: { name: 'Alpha' }, expectErr: AlreadyExistsError },
 ]);
 ```
 
-Where `testTrail` exercises a single trail in isolation, `testHike` exercises the follow graph and verifies that upstream failures propagate correctly.
-
-### `testContracts(app, ctx?)`
-
-Catches implementation-schema drift. Runs every example through the implementation, then validates the result against the trail's `output` schema. Reports detailed Zod errors on mismatch.
+## Surface harnesses
 
 ```typescript
-import { testContracts } from '@ontrails/testing';
-
-testContracts(app);
-// Fails if any implementation returns data that doesn't match its declared output schema
-```
-
-### `testDetours(app)`
-
-Structural validation of detour declarations. Verifies every detour target trail exists in the topo. No implementation execution needed.
-
-```typescript
-import { testDetours } from '@ontrails/testing';
-
-testDetours(app);
-// Fails: Trail "entity.show" has detour target "entity.search" which does not exist in the topo
-```
-
-### Progressive Assertion
-
-What `testExamples` checks depends on what the example declares:
-
-**Full match** -- example has `expected`:
-
-```typescript
-{
-  name: 'Found',
-  input: { name: 'Alpha' },
-  expected: { name: 'Alpha', type: 'concept' },
-}
-```
-
-Asserts `result.isOk()` and `result.value` deep-equals `expected`.
-
-**Schema-only match** -- example has no `expected` and no `error`:
-
-```typescript
-{ name: 'Returns something valid', input: { name: 'Alpha' } }
-```
-
-Asserts `result.isOk()` and validates against the trail's output schema.
-
-**Error match** -- example has `error`:
-
-```typescript
-{ name: 'Not found', input: { name: 'missing' }, error: 'NotFoundError' }
-```
-
-Asserts `result.isErr()` and `instanceof` check.
-
-### Test Context and Mocks
-
-```typescript
-import { createTestContext, createTestLogger } from '@ontrails/testing';
-
-// TrailContext with sensible test defaults
-const ctx = createTestContext({
-  requestId: 'test-001',
-  env: { TRAILS_ENV: 'test' },
-});
-
-// Logger that captures entries in memory
-const logger = createTestLogger();
-logger.info('hello');
-logger.entries; // All captured records
-logger.assertLogged('info', 'hello'); // Passes if any entry matches
-logger.clear(); // Reset
-```
-
-### Surface Harnesses
-
-**CLI harness** -- execute commands in-process and capture stdout/stderr:
-
-```typescript
-import { createCliHarness } from '@ontrails/testing';
-
-const harness = createCliHarness({ app });
-const result = await harness.run('entity show --name Alpha --output json');
+import { createCliHarness, createMcpHarness } from '@ontrails/testing';
 
+// CLI
+const cli = createCliHarness({ app });
+const result = await cli.run('entity show --name Alpha --output json');
 expect(result.exitCode).toBe(0);
-expect(result.json).toMatchObject({ name: 'Alpha' });
-```
-
-**MCP harness** -- invoke tools directly without transport:
-
-```typescript
-import { createMcpHarness } from '@ontrails/testing';
-
-const harness = createMcpHarness({ app });
-const result = await harness.callTool('myapp_entity_show', { name: 'Alpha' });
 
-expect(result.isError).toBe(false);
+// MCP
+const mcp = createMcpHarness({ app });
+const tool = await mcp.callTool('myapp_entity_show', { name: 'Alpha' });
+expect(tool.isError).toBe(false);
 ```
 
-## Exports
+## Installation
 
-```typescript
-import {
-  testAll,
-  testExamples,
-  testTrail,
-  testHike,
-  testContracts,
-  testDetours,
-  createTestContext,
-  createTestLogger,
-  createCliHarness,
-  createMcpHarness,
-} from '@ontrails/testing';
+```bash
+bun add -d @ontrails/testing
 ```
-
-## Further Reading
-
-- [Testing Guide](../../docs/testing.md)
-- [Getting Started](../../docs/getting-started.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/testing",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,10 +14,10 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "peerDependencies": {
-    "@ontrails/cli": "workspace:*",
-    "@ontrails/core": "workspace:*",
-    "@ontrails/logging": "workspace:*",
-    "@ontrails/mcp": "workspace:*",
+    "@ontrails/cli": "workspace:^",
+    "@ontrails/core": "workspace:^",
+    "@ontrails/logging": "workspace:^",
+    "@ontrails/mcp": "workspace:^",
     "zod": "catalog:"
   }
 }