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

package/src/assertions.ts

@@ -49,6 +49,40 @@ export const expectErr = <T, E>(result: Result<T, E>): E => {
   return (result as unknown as { error: E }).error;
 };
 
+// ---------------------------------------------------------------------------
+// Result Match Tokens
+// ---------------------------------------------------------------------------
+
+export interface OkResultMatch {
+  readonly __resultMatch: 'ok';
+  readonly value?: unknown | undefined;
+}
+
+export interface ErrResultMatch {
+  readonly __resultMatch: 'err';
+  readonly error?: unknown | undefined;
+}
+
+type ResultMatchToken = OkResultMatch | ErrResultMatch;
+
+/**
+ * Create a partial-match token for `Result.ok(...)` values nested inside
+ * arrays or objects, such as the `Result[]` returned by batch `ctx.cross()`.
+ */
+export const okResultMatch = (value?: unknown): OkResultMatch => ({
+  __resultMatch: 'ok',
+  value,
+});
+
+/**
+ * Create a partial-match token for `Result.err(...)` values nested inside
+ * arrays or objects, such as mixed-success batch `ctx.cross()`.
+ */
+export const errResultMatch = (error?: unknown): ErrResultMatch => ({
+  __resultMatch: 'err',
+  error,
+});
+
 // ---------------------------------------------------------------------------
 // Full Match
 // ---------------------------------------------------------------------------
@@ -87,6 +121,225 @@ export const assertSchemaMatch = (
   }
 };
 
+// ---------------------------------------------------------------------------
+// Partial Match
+// ---------------------------------------------------------------------------
+
+/** Format a path for error messages. */
+const formatLoc = (path: readonly string[]): string =>
+  path.length > 0 ? path.join('.') : 'root';
+
+interface ResultLike {
+  readonly error?: unknown;
+  isErr(): boolean;
+  isOk(): boolean;
+  readonly value?: unknown;
+}
+
+const isResultMatchToken = (value: unknown): value is ResultMatchToken =>
+  typeof value === 'object' &&
+  value !== null &&
+  '__resultMatch' in value &&
+  ((value as Record<string, unknown>)['__resultMatch'] === 'ok' ||
+    (value as Record<string, unknown>)['__resultMatch'] === 'err');
+
+const isResultLike = (value: unknown): value is ResultLike =>
+  typeof value === 'object' &&
+  value !== null &&
+  'isOk' in value &&
+  typeof (value as Record<string, unknown>)['isOk'] === 'function' &&
+  'isErr' in value &&
+  typeof (value as Record<string, unknown>)['isErr'] === 'function';
+
+/** Find an unconsumed actual element that deep-matches the expected object. */
+const findObjectMatch = (
+  actual: unknown[],
+  elem: object,
+  consumed: ReadonlySet<number>,
+  path: readonly string[],
+  index: number
+): number =>
+  actual.findIndex((a, idx) => {
+    if (consumed.has(idx)) {
+      return false;
+    }
+    try {
+      // oxlint-disable-next-line no-use-before-define -- mutual recursion with assertSubset
+      assertSubset(a, elem, [...path, `[${String(index)}]`]);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+
+/**
+ * Assert that every element in `expected` exists in `actual` (order-independent).
+ *
+ * Tracks consumed indices so that duplicate expected elements each require a
+ * distinct actual element — `['a', 'a']` does not match `['a']`.
+ */
+const assertArraySubset = (
+  actual: unknown[],
+  expected: unknown[],
+  path: readonly string[],
+  loc: string
+): void => {
+  const consumed = new Set<number>();
+  for (let i = 0; i < expected.length; i += 1) {
+    const elem = expected[i];
+    const matchIndex =
+      typeof elem === 'object' && elem !== null
+        ? findObjectMatch(actual, elem, consumed, path, i)
+        : actual.findIndex((a, idx) => !consumed.has(idx) && a === elem);
+
+    if (matchIndex === -1) {
+      throw new Error(
+        `at ${loc}[${String(i)}]: expected array to contain ${JSON.stringify(elem)}`
+      );
+    }
+    consumed.add(matchIndex);
+  }
+};
+
+/** Assert that every key in `expected` exists in `actual` with a matching value. */
+const assertObjectSubset = (
+  actual: Record<string, unknown>,
+  expected: Record<string, unknown>,
+  path: readonly string[]
+): void => {
+  for (const key of Object.keys(expected)) {
+    if (!(key in actual)) {
+      throw new Error(
+        `at ${[...path, key].join('.')}: key not found in actual`
+      );
+    }
+    // oxlint-disable-next-line no-use-before-define -- mutual recursion with assertSubset
+    assertSubset(actual[key], expected[key], [...path, key]);
+  }
+};
+
+/**
+ * Recursively assert that `actual` is a superset of `expected`.
+ *
+ * - **Scalars:** strict equality.
+ * - **Objects:** every key in `expected` must exist in `actual` with a matching
+ *   value. Extra keys in `actual` are ignored.
+ * - **Arrays:** every element in `expected` must exist in `actual`
+ *   (order-independent subset check).
+ * - **Nested objects:** recursive subset matching.
+ */
+// oxlint-disable-next-line max-statements -- recursive dispatch across four type branches
+const assertSubset = (
+  actual: unknown,
+  expected: unknown,
+  path: readonly string[]
+): void => {
+  const loc = formatLoc(path);
+
+  if (expected === null || expected === undefined) {
+    if (actual !== expected) {
+      throw new Error(
+        `at ${loc}: expected ${String(expected)}, got ${String(actual)}`
+      );
+    }
+    return;
+  }
+
+  if (isResultMatchToken(expected)) {
+    // oxlint-disable-next-line no-use-before-define -- result token matching delegates back into assertSubset
+    assertResultTokenMatch(actual, expected, path);
+    return;
+  }
+
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual)) {
+      throw new TypeError(`at ${loc}: expected an array, got ${typeof actual}`);
+    }
+    assertArraySubset(actual, expected, path, loc);
+    return;
+  }
+
+  if (typeof expected === 'object') {
+    if (
+      typeof actual !== 'object' ||
+      actual === null ||
+      Array.isArray(actual)
+    ) {
+      throw new Error(`at ${loc}: expected an object, got ${typeof actual}`);
+    }
+    assertObjectSubset(
+      actual as Record<string, unknown>,
+      expected as Record<string, unknown>,
+      path
+    );
+    return;
+  }
+
+  if (actual !== expected) {
+    throw new Error(
+      `at ${loc}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`
+    );
+  }
+};
+
+const assertOkResultTokenMatch = (
+  actual: ResultLike,
+  expected: OkResultMatch,
+  loc: string,
+  path: readonly string[]
+): void => {
+  if (!actual.isOk()) {
+    throw new Error(`at ${loc}: expected Result.ok(...), got Result.err(...)`);
+  }
+  if (expected.value !== undefined) {
+    assertSubset(actual.value, expected.value, [...path, 'value']);
+  }
+};
+
+const assertErrResultTokenMatch = (
+  actual: ResultLike,
+  expected: ErrResultMatch,
+  loc: string,
+  path: readonly string[]
+): void => {
+  if (!actual.isErr()) {
+    throw new Error(`at ${loc}: expected Result.err(...), got Result.ok(...)`);
+  }
+  if (expected.error !== undefined) {
+    assertSubset(actual.error, expected.error, [...path, 'error']);
+  }
+};
+
+const assertResultTokenMatch = (
+  actual: unknown,
+  expected: ResultMatchToken,
+  path: readonly string[]
+): void => {
+  const loc = formatLoc(path);
+  if (!isResultLike(actual)) {
+    throw new TypeError(`at ${loc}: expected a Result-like value`);
+  }
+
+  if (expected.__resultMatch === 'ok') {
+    assertOkResultTokenMatch(actual, expected, loc, path);
+    return;
+  }
+
+  assertErrResultTokenMatch(actual, expected, loc, path);
+};
+
+/**
+ * Assert that the result is ok and its value is a superset of the expected
+ * partial output. Declared fields must match; extra fields are ignored.
+ */
+export const assertPartialMatch = (
+  result: Result<unknown, Error>,
+  expectedMatch: unknown
+): void => {
+  const value = expectOk(result);
+  assertSubset(value, expectedMatch, []);
+};
+
 // ---------------------------------------------------------------------------
 // Error Match
 // ---------------------------------------------------------------------------

package/src/context.ts

@@ -4,11 +4,16 @@
 
 import type {
   CrossFn,
-  ProvisionOverrideMap,
+  ResourceOverrideMap,
   Topo,
   TrailContext,
 } from '@ontrails/core';
-import { Result, createProvisionLookup } from '@ontrails/core';
+import {
+  Result,
+  buildCrossValidationSchema,
+  createResourceLookup,
+  passthroughTrace,
+} from '@ontrails/core';
 
 import { createTestLogger } from './logger.js';
 import type { TestTrailContextOptions } from './types.js';
@@ -39,10 +44,11 @@ export const createTestContext = (
     extensions: undefined,
     logger: overrides?.logger ?? createTestLogger(),
     requestId: overrides?.requestId ?? 'test-request-001',
+    trace: overrides?.trace ?? passthroughTrace,
     workspaceRoot: cwd,
   } as MutableTrailContext;
-  const lookup = createProvisionLookup(() => ctx);
-  ctx.provision = lookup;
+  const lookup = createResourceLookup(() => ctx);
+  ctx.resource = lookup;
   return ctx;
 };
 
@@ -54,14 +60,14 @@ export interface CreateCrossContextOptions {
   readonly responses?: Record<string, Result<unknown, Error>> | undefined;
 }
 
-/** Minimal permit shape returned by the mint function. */
-export interface MintedPermit {
+/** Minimal permit shape returned by the create function. */
+export interface MinimalPermit {
   readonly id: string;
   readonly scopes: readonly string[];
 }
 
-/** Trail shape consumed by the mint function — avoids importing permits. */
-export interface MintableTrail {
+/** Trail shape consumed by the create function — avoids importing permits. */
+export interface PermittedTrail {
   readonly permit?:
     | { readonly scopes: readonly string[] }
     | 'public'
@@ -70,21 +76,21 @@ export interface MintableTrail {
 
 export interface TestExecutionOptions {
   readonly ctx?: Partial<TrailContext> | undefined;
-  readonly provisions?: ProvisionOverrideMap | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
   /**
-   * When true, disables automatic permit minting. Tests must provide
+   * When true, disables automatic permit creation. Tests must provide
    * explicit permits.
    */
   readonly strictPermits?: boolean | undefined;
   /**
-   * Optional function to mint a test permit for a trail. When provided,
+   * Optional function to create a test permit for a trail. When provided,
    * called for each trail with a non-public `permit` requirement.
-   * Returning `undefined` skips minting for that trail.
+   * Returning `undefined` skips creation for that trail.
    *
    * A default inline implementation is used when this is not provided,
    * keeping the testing package free of a hard dependency on `@ontrails/permits`.
    */
-  readonly mintPermit?: (trail: MintableTrail) => MintedPermit | undefined;
+  readonly createPermit?: (trail: PermittedTrail) => MinimalPermit | undefined;
 }
 
 /**
@@ -105,7 +111,10 @@ export const createCrossContext = (
   options?: CreateCrossContextOptions
 ): CrossFn => {
   const responses = options?.responses ?? {};
-  return <O>(id: string, _input: unknown): Promise<Result<O, Error>> => {
+  const respondToCross = <O>(
+    idOrTrail: string | { readonly id: string }
+  ): Promise<Result<O, Error>> => {
+    const id = typeof idOrTrail === 'string' ? idOrTrail : idOrTrail.id;
     const response = responses[id];
     if (response === undefined) {
       return Promise.resolve(
@@ -117,15 +126,31 @@ export const createCrossContext = (
     }
     return Promise.resolve(response as Result<O, Error>);
   };
+  const cross = (async (
+    idOrTrail:
+      | string
+      | { readonly id: string }
+      | readonly (readonly [string | { readonly id: string }, unknown])[],
+    _input?: unknown
+  ) => {
+    if (Array.isArray(idOrTrail)) {
+      return await Promise.all(
+        idOrTrail.map(([target]) => respondToCross(target))
+      );
+    }
+
+    return await respondToCross(idOrTrail as string | { readonly id: string });
+  }) as CrossFn;
+  return cross;
 };
 
 /**
- * Default permit minter — reads `trail.permit.scopes` and produces a
+ * Default permit creator — reads `trail.permit.scopes` and produces a
  * minimal permit object. No dependency on `@ontrails/permits`.
  */
-export const defaultMintPermit = (
-  trail: MintableTrail
-): MintedPermit | undefined => {
+export const defaultCreatePermit = (
+  trail: PermittedTrail
+): MinimalPermit | undefined => {
   if (!trail.permit || trail.permit === 'public') {
     return undefined;
   }
@@ -137,41 +162,42 @@ const isTestExecutionOptions = (
 ): input is TestExecutionOptions =>
   input !== undefined &&
   (Object.hasOwn(input, 'ctx') ||
-    Object.hasOwn(input, 'provisions') ||
+    Object.hasOwn(input, 'resources') ||
     Object.hasOwn(input, 'strictPermits') ||
-    Object.hasOwn(input, 'mintPermit'));
+    Object.hasOwn(input, 'createPermit'));
 
 export const normalizeTestExecutionOptions = (
   input?: Partial<TrailContext> | TestExecutionOptions
 ): TestExecutionOptions =>
   isTestExecutionOptions(input) ? input : { ctx: input };
 
-export const mergeProvisionOverrides = (
-  autoResolved: ProvisionOverrideMap,
+export const mergeResourceOverrides = (
+  autoResolved: ResourceOverrideMap,
   ctx: Partial<TrailContext> | undefined,
-  explicit: ProvisionOverrideMap | undefined
-): ProvisionOverrideMap => ({
+  explicit: ResourceOverrideMap | undefined
+): ResourceOverrideMap => ({
   ...autoResolved,
   ...ctx?.extensions,
   ...explicit,
 });
 
-const buildMockProvisions = async (
-  app: Topo
-): Promise<ProvisionOverrideMap> => {
-  const provisions: Record<string, unknown> = {};
-  for (const declaredProvision of app.listProvisions()) {
-    if (!declaredProvision.mock) {
+const buildMockResources = async (app: Topo): Promise<ResourceOverrideMap> => {
+  const resources: Record<string, unknown> = {};
+  for (const declaredResource of app.listResources()) {
+    if (!declaredResource.mock) {
       continue;
     }
-    provisions[declaredProvision.id] = await declaredProvision.mock();
+    resources[declaredResource.id] = await declaredResource.mock();
   }
-  return provisions;
+  return resources;
 };
 
-export const resolveMockProvisions = async (
+export const createMockResources = async (
   app: Topo
-): Promise<ProvisionOverrideMap> => await buildMockProvisions(app);
+): Promise<ResourceOverrideMap> => await buildMockResources(app);
+
+// Re-export from core so existing consumers of this module continue to work.
+export { buildCrossValidationSchema };
 
 /**
  * Merge a Partial<TrailContext> into a test context.
@@ -179,20 +205,20 @@ export const resolveMockProvisions = async (
  */
 export const mergeTestContext = (
   ctx?: Partial<TrailContext>,
-  provisions?: ProvisionOverrideMap
+  resources?: ResourceOverrideMap
 ): TrailContext => {
   const base = createTestContext();
   const extensions = {
     ...base.extensions,
     ...ctx?.extensions,
-    ...provisions,
+    ...resources,
   };
   const merged = {
     ...base,
     ...ctx,
     extensions: Object.keys(extensions).length === 0 ? undefined : extensions,
   } as MutableTrailContext;
-  const lookup = createProvisionLookup(() => merged);
-  merged.provision = lookup;
+  const lookup = createResourceLookup(() => merged);
+  merged.resource = lookup;
   return merged;
 };

package/src/contracts.ts

@@ -14,12 +14,13 @@ import type { z } from 'zod';
 
 import { expectOk } from './assertions.js';
 import {
-  mergeProvisionOverrides,
+  mergeResourceOverrides,
   mergeTestContext,
   normalizeTestExecutionOptions,
-  resolveMockProvisions,
+  createMockResources,
 } from './context.js';
 import type { TestExecutionOptions } from './context.js';
+import { deriveTrailExamples } from './effective-examples.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -71,14 +72,19 @@ export const testContracts = (
 ): void => {
   const resolveInput =
     typeof ctxOrFactory === 'function' ? ctxOrFactory : () => ctxOrFactory;
-  const allEntries = app.list() as Trail<unknown, unknown>[];
+  const allEntries = (app.list() as Trail<unknown, unknown, unknown>[]).map(
+    (trailDef) => ({
+      ...trailDef,
+      examples: deriveTrailExamples(trailDef),
+    })
+  );
 
   describe('contracts', () => {
     describe.each(allEntries)('$id', (t) => {
       if (t.output === undefined) {
         return;
       }
-      if (t.examples === undefined || t.examples.length === 0) {
+      if (t.examples.length === 0) {
         return;
       }
       if (needsCrossContext(t, resolveInput)) {
@@ -92,10 +98,10 @@ export const testContracts = (
         'contract: $name',
         async (example: TrailExample<unknown, unknown>) => {
           const resolved = normalizeTestExecutionOptions(resolveInput());
-          const provisions = mergeProvisionOverrides(
-            await resolveMockProvisions(app),
+          const resources = mergeResourceOverrides(
+            await createMockResources(app),
             resolved.ctx,
-            resolved.provisions
+            resolved.resources
           );
           const testCtx = mergeTestContext(resolved.ctx);
 
@@ -104,7 +110,7 @@ export const testContracts = (
 
           const result = await executeTrail(t, example.input, {
             ctx: testCtx,
-            provisions,
+            resources,
           });
           const resultValue = expectOk(result);