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

package/src/harness-http.ts

@@ -0,0 +1,263 @@
+/**
+ * HTTP integration test harness.
+ *
+ * Builds framework-agnostic HTTP routes from a graph and executes them
+ * directly, without Hono or a listening server.
+ */
+
+import { deriveHttpRoutes } from '@ontrails/http';
+import type { HttpMethod, HttpRouteDefinition } from '@ontrails/http';
+import type { TrailContext, TrailContextInit } from '@ontrails/core';
+import { NotFoundError, projectPublicSurfaceError } from '@ontrails/core';
+
+import { mergeTestContext } from './context.js';
+import type {
+  HttpHarness,
+  HttpHarnessOptions,
+  HttpHarnessRequest,
+  HttpHarnessRequestOptions,
+  HttpHarnessResult,
+} from './types.js';
+
+const TEST_ORIGIN = 'http://ontrails.test';
+
+const normalizeMethod = (method: HttpMethod): HttpMethod =>
+  method.toUpperCase() as HttpMethod;
+
+const collectQueryParams = (url: URL): Record<string, unknown> => {
+  const query: Record<string, unknown> = {};
+  const seen = new Set<string>();
+
+  for (const key of url.searchParams.keys()) {
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    const values = url.searchParams.getAll(key);
+    query[key] = values.length > 1 ? values : values[0];
+  }
+
+  return query;
+};
+
+const findRoute = (
+  routes: readonly HttpRouteDefinition[],
+  method: HttpMethod,
+  path: string
+): HttpRouteDefinition | undefined =>
+  routes.find((route) => route.method === method && route.path === path);
+
+const mapError = (error: Error): HttpHarnessResult => {
+  const projection = projectPublicSurfaceError('http', error);
+  const body = {
+    error: {
+      category: projection.category,
+      code: projection.name,
+      message: projection.message,
+    },
+  };
+  return {
+    body,
+    error: body.error,
+    ok: false,
+    status: projection.code,
+  };
+};
+
+const mapSuccess = (data: unknown): HttpHarnessResult => ({
+  body: { data },
+  data,
+  ok: true,
+  status: 200,
+});
+
+const isWebhookParseResult = (
+  input: unknown
+): input is {
+  readonly error?: Error | undefined;
+  isErr(): boolean;
+  readonly value?: unknown | undefined;
+} =>
+  typeof input === 'object' &&
+  input !== null &&
+  'isErr' in input &&
+  typeof input.isErr === 'function';
+
+const mergeContextInit = (
+  base: TrailContextInit | undefined,
+  ctx: Partial<TrailContext> | undefined
+): TrailContextInit => ({
+  ...base,
+  ...mergeTestContext({ ...base, ...ctx }),
+});
+
+const createHarnessContextFactory = (
+  options: HttpHarnessOptions
+): (() => TrailContextInit | Promise<TrailContextInit>) => {
+  const { createContext, ctx } = options;
+  return async () => {
+    const base = await createContext?.();
+    return mergeContextInit(base, ctx);
+  };
+};
+
+const buildInput = (
+  route: HttpRouteDefinition,
+  url: URL,
+  request: HttpHarnessRequest
+): unknown => {
+  if (route.inputSource === 'query') {
+    return {
+      ...collectQueryParams(url),
+      ...request.query,
+    };
+  }
+  return request.body ?? {};
+};
+
+const executeRouteWithInput = async (
+  route: HttpRouteDefinition,
+  input: unknown,
+  request: HttpHarnessRequest
+): Promise<HttpHarnessResult> => {
+  const result = await route.execute(
+    input,
+    request.requestId,
+    request.abortSignal,
+    { headers: request.headers }
+  );
+
+  if (result.isErr()) {
+    return mapError(result.error);
+  }
+
+  return mapSuccess(result.value);
+};
+
+const executeRoute = async (
+  route: HttpRouteDefinition,
+  url: URL,
+  request: HttpHarnessRequest
+): Promise<HttpHarnessResult> => {
+  const parsedInput = buildInput(route, url, request);
+  if (route.inputSource === 'webhook' && route.parseWebhookInput) {
+    const parsed = route.parseWebhookInput(parsedInput);
+    if (isWebhookParseResult(parsed)) {
+      if (parsed.isErr()) {
+        return mapError(parsed.error ?? new Error('Invalid webhook input'));
+      }
+      return await executeRouteWithInput(route, parsed.value, request);
+    }
+    return await executeRouteWithInput(route, parsed, request);
+  }
+
+  return await executeRouteWithInput(route, parsedInput, request);
+};
+
+// ---------------------------------------------------------------------------
+// createHttpHarness
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an HTTP harness for integration testing.
+ *
+ * @example
+ * ```ts
+ * import { createHttpHarness } from '@ontrails/testing';
+ *
+ * const http = createHttpHarness({ graph });
+ * const result = await http.get('/entity/show', { name: 'Alpha' });
+ * expect(result.status).toBe(200);
+ * ```
+ */
+export const createHttpHarness = (
+  harnessOptions: HttpHarnessOptions
+): HttpHarness => {
+  const { ctx: _ctx, graph, ...deriveOptions } = harnessOptions;
+  const routesResult = deriveHttpRoutes(graph, {
+    ...deriveOptions,
+    createContext: createHarnessContextFactory(harnessOptions),
+  });
+  if (routesResult.isErr()) {
+    throw routesResult.error;
+  }
+  const routes = routesResult.value;
+
+  const request = async (
+    rawRequest: HttpHarnessRequest
+  ): Promise<HttpHarnessResult> => {
+    const method = normalizeMethod(rawRequest.method);
+    const url = new URL(rawRequest.path, TEST_ORIGIN);
+    const route = findRoute(routes, method, url.pathname);
+
+    if (!route) {
+      return mapError(
+        new NotFoundError(`No HTTP route found for ${method} ${url.pathname}`)
+      );
+    }
+
+    return await executeRoute(route, url, { ...rawRequest, method });
+  };
+
+  return {
+    delete: async (
+      path: string,
+      body?: unknown,
+      requestOptions?: HttpHarnessRequestOptions
+    ) =>
+      await request({
+        ...requestOptions,
+        body,
+        method: 'DELETE',
+        path,
+      }),
+    get: async (
+      path: string,
+      query?: Record<string, unknown>,
+      requestOptions?: HttpHarnessRequestOptions
+    ) =>
+      await request({
+        ...requestOptions,
+        method: 'GET',
+        path,
+        query: {
+          ...requestOptions?.query,
+          ...query,
+        },
+      }),
+    patch: async (
+      path: string,
+      body?: unknown,
+      requestOptions?: HttpHarnessRequestOptions
+    ) =>
+      await request({
+        ...requestOptions,
+        body,
+        method: 'PATCH',
+        path,
+      }),
+    post: async (
+      path: string,
+      body?: unknown,
+      requestOptions?: HttpHarnessRequestOptions
+    ) =>
+      await request({
+        ...requestOptions,
+        body,
+        method: 'POST',
+        path,
+      }),
+    put: async (
+      path: string,
+      body?: unknown,
+      requestOptions?: HttpHarnessRequestOptions
+    ) =>
+      await request({
+        ...requestOptions,
+        body,
+        method: 'PUT',
+        path,
+      }),
+    request,
+  };
+};

package/src/harness-mcp.ts

@@ -63,6 +63,8 @@ export const createMcpHarness = (options: McpHarnessOptions): McpHarness => {
       return {
         content: result.content,
         isError: result.isError ?? false,
+        meta: result._meta,
+        structuredContent: result.structuredContent,
       };
     },
   };

package/src/index.ts

@@ -6,6 +6,10 @@ export { testCrosses } from './crosses.js';
 export { testTrail } from './trail.js';
 export { testContracts } from './contracts.js';
 export { testDetours } from './detours.js';
+export {
+  runSurfaceParityExample,
+  testSurfaceParity,
+} from './surface-parity.js';
 
 // Assertions
 export {
@@ -30,8 +34,9 @@ export {
 } from './context.js';
 export { createTestLogger } from './logger.js';
 
-// Trailhead harnesses
+// Surface harnesses
 export { createCliHarness } from './harness-cli.js';
+export { createHttpHarness } from './harness-http.js';
 export { createMcpHarness } from './harness-mcp.js';
 
 // Types
@@ -54,7 +59,19 @@ export type {
   CliHarness,
   CliHarnessOptions,
   CliHarnessResult,
+  HttpHarness,
+  HttpHarnessErrorBody,
+  HttpHarnessOptions,
+  HttpHarnessRequest,
+  HttpHarnessRequestOptions,
+  HttpHarnessResult,
+  HttpHarnessSuccessBody,
   McpHarness,
   McpHarnessOptions,
   McpHarnessResult,
+  NormalizedSurfaceParityResult,
+  SurfaceParityExclusion,
+  SurfaceParityOptions,
+  SurfaceParitySurface,
 } from './types.js';
+export type { SurfaceParityComparison } from './surface-parity.js';

package/src/logger.ts

@@ -2,10 +2,12 @@
  * Test logger that captures log records for assertion.
  */
 
-import type { LogLevel, LogMetadata, LogRecord } from '@ontrails/logging';
+import type { LogLevel, LogRecord } from '@ontrails/observe';
 
 import type { TestLogger } from './types.js';
 
+type LogMetadata = Readonly<Record<string, unknown>>;
+
 // ---------------------------------------------------------------------------
 // Level ordering for filtering
 // ---------------------------------------------------------------------------

package/src/scenario.ts

@@ -18,15 +18,13 @@ import type {
 } from '@ontrails/core';
 import {
   buildCrossValidationSchema,
+  claimNextCrossBatchIndex,
+  createCrossBatchValidationResults,
   executeTrail,
   InternalError,
+  normalizeCrossBatchConcurrency,
   Result as R,
 } from '@ontrails/core';
-import {
-  claimNextCrossBatchIndex,
-  createCrossBatchValidationResults,
-  normalizeCrossBatchConcurrency,
-} from '@ontrails/core/internal/cross-batch';
 
 import { assertPartialMatch, expectOk } from './assertions.js';
 import { createTestContext, createMockResources } from './context.js';

package/src/signals.ts

@@ -0,0 +1,221 @@
+import { isDeepStrictEqual } from 'node:util';
+
+import type {
+  FireFn,
+  TrailContext,
+  TrailExample,
+  TrailExampleSignalAssertion,
+} from '@ontrails/core';
+import { summarizeSignalPayload } from '@ontrails/core';
+
+export interface RecordedSignal {
+  readonly payload: unknown;
+  readonly signalId: string;
+}
+
+export interface SignalAssertionHarness {
+  readonly assert: () => void;
+  readonly ctx: TrailContext;
+}
+
+const noop = (): void => undefined;
+
+const resolveSignalId = (signal: unknown): string => {
+  if (typeof signal === 'string') {
+    return signal;
+  }
+  if (
+    typeof signal === 'object' &&
+    signal !== null &&
+    'id' in signal &&
+    typeof (signal as { readonly id: unknown }).id === 'string'
+  ) {
+    return (signal as { readonly id: string }).id;
+  }
+  return '<unknown signal>';
+};
+
+const assertionSignalId = (assertion: TrailExampleSignalAssertion): string =>
+  resolveSignalId(assertion.signal);
+
+const formatPayloadSummary = (payload: unknown): string => {
+  const summary = summarizeSignalPayload(payload);
+  const parts = [
+    `redacted=${summary.redacted}`,
+    `shape=${summary.shape}`,
+    `digest=${summary.digest}`,
+  ];
+  if (summary.topLevelEntryCount !== undefined) {
+    parts.push(`topLevelEntryCount=${summary.topLevelEntryCount}`);
+  }
+  return `{${parts.join(' ')}}`;
+};
+
+const formatAssertion = (assertion: TrailExampleSignalAssertion): string => {
+  const parts = [`signal=${assertionSignalId(assertion)}`];
+  if (assertion.payload !== undefined) {
+    parts.push(`payloadSummary=${formatPayloadSummary(assertion.payload)}`);
+  }
+  if (assertion.payloadMatch !== undefined) {
+    parts.push(
+      `payloadMatchSummary=${formatPayloadSummary(assertion.payloadMatch)}`
+    );
+  }
+  if (assertion.times !== undefined) {
+    parts.push(`times=${assertion.times}`);
+  }
+  return parts.join(' ');
+};
+
+const formatObserved = (observed: readonly RecordedSignal[]): string => {
+  if (observed.length === 0) {
+    return '<none>';
+  }
+  return observed
+    .map(
+      (record) =>
+        `${record.signalId} payloadSummary=${formatPayloadSummary(record.payload)}`
+    )
+    .join('; ');
+};
+
+const subsetArrayMatches = (
+  actual: readonly unknown[],
+  expected: readonly unknown[]
+): boolean => {
+  const consumed = new Set<number>();
+  for (const expectedItem of expected) {
+    const matchIndex = actual.findIndex(
+      (actualItem, index) =>
+        !consumed.has(index) &&
+        // oxlint-disable-next-line no-use-before-define -- mutual recursion with subsetMatches
+        subsetMatches(actualItem, expectedItem)
+    );
+    if (matchIndex === -1) {
+      return false;
+    }
+    consumed.add(matchIndex);
+  }
+  return true;
+};
+
+const subsetObjectMatches = (
+  actual: Record<string, unknown>,
+  expected: Record<string, unknown>
+): boolean =>
+  Object.keys(expected).every(
+    (key) =>
+      key in actual &&
+      // oxlint-disable-next-line no-use-before-define -- mutual recursion with subsetMatches
+      subsetMatches(actual[key], expected[key])
+  );
+
+const subsetMatches = (actual: unknown, expected: unknown): boolean => {
+  if (Array.isArray(expected)) {
+    return Array.isArray(actual) && subsetArrayMatches(actual, expected);
+  }
+  if (expected !== null && typeof expected === 'object') {
+    return (
+      actual !== null &&
+      typeof actual === 'object' &&
+      !Array.isArray(actual) &&
+      subsetObjectMatches(
+        actual as Record<string, unknown>,
+        expected as Record<string, unknown>
+      )
+    );
+  }
+  return isDeepStrictEqual(actual, expected);
+};
+
+const payloadMatches = (
+  payload: unknown,
+  assertion: TrailExampleSignalAssertion
+): boolean => {
+  if (
+    assertion.payload !== undefined &&
+    !isDeepStrictEqual(payload, assertion.payload)
+  ) {
+    return false;
+  }
+  if (
+    assertion.payloadMatch !== undefined &&
+    !subsetMatches(payload, assertion.payloadMatch)
+  ) {
+    return false;
+  }
+  return true;
+};
+
+const signalMatches = (
+  record: RecordedSignal,
+  assertion: TrailExampleSignalAssertion
+): boolean =>
+  record.signalId === assertionSignalId(assertion) &&
+  payloadMatches(record.payload, assertion);
+
+const assertValidTimes = (assertion: TrailExampleSignalAssertion): number => {
+  const times = assertion.times ?? 1;
+  if (!Number.isInteger(times) || times < 1) {
+    throw new Error(
+      `Signal assertion has invalid times value: ${formatAssertion(assertion)}`
+    );
+  }
+  return times;
+};
+
+const assertSignalAssertion = (
+  example: TrailExample<unknown, unknown>,
+  assertion: TrailExampleSignalAssertion,
+  observed: readonly RecordedSignal[],
+  consumed: Set<number>
+): void => {
+  const times = assertValidTimes(assertion);
+  for (let count = 0; count < times; count += 1) {
+    const matchIndex = observed.findIndex(
+      (record, index) =>
+        !consumed.has(index) && signalMatches(record, assertion)
+    );
+    if (matchIndex === -1) {
+      throw new Error(
+        `Example "${example.name}" expected signal ${formatAssertion(
+          assertion
+        )}; observed ${formatObserved(observed)}`
+      );
+    }
+    consumed.add(matchIndex);
+  }
+};
+
+export const assertSignalAssertions = (
+  example: TrailExample<unknown, unknown>,
+  observed: readonly RecordedSignal[]
+): void => {
+  const consumed = new Set<number>();
+  for (const assertion of example.signals ?? []) {
+    assertSignalAssertion(example, assertion, observed, consumed);
+  }
+};
+
+export const withSignalAssertions = (
+  ctx: TrailContext,
+  example: TrailExample<unknown, unknown>
+): SignalAssertionHarness => {
+  if (example.signals === undefined || example.signals.length === 0) {
+    return { assert: noop, ctx };
+  }
+
+  const observed: RecordedSignal[] = [];
+  const baseFire = ctx.fire as
+    | ((signal: unknown, payload: unknown) => Promise<void>)
+    | undefined;
+  const fire = (async (signal: unknown, payload: unknown): Promise<void> => {
+    observed.push({ payload, signalId: resolveSignalId(signal) });
+    await baseFire?.(signal, payload);
+  }) as FireFn;
+
+  return {
+    assert: () => assertSignalAssertions(example, observed),
+    ctx: { ...ctx, fire },
+  };
+};