@ontrails/testing 1.0.0-beta.2 → 1.0.0-beta.21

package/src/harness-cli.ts

@@ -1,19 +1,47 @@
 /**
  * CLI integration test harness.
  *
- * Builds CLI commands from an App, executes them in-process,
+ * Builds CLI commands from a graph, executes them in-process,
  * and captures stdout/stderr.
  */
 
-import { buildCliCommands } from '@ontrails/cli';
-import type { CliCommand } from '@ontrails/cli';
+import { deriveCliCommands } from '@ontrails/cli';
+import type { CliCommand, DeriveCliCommandsOptions } from '@ontrails/cli';
+import type { Topo, TrailContext } from '@ontrails/core';
+import { projectPublicSurfaceError } from '@ontrails/core';
 
-import { createTestContext } from './context.js';
-import type {
-  CliHarness,
-  CliHarnessOptions,
-  CliHarnessResult,
-} from './types.js';
+import { mergeTestContext } from './context.js';
+
+/** Options for creating a CLI harness. */
+export interface CliHarnessOptions extends Omit<
+  DeriveCliCommandsOptions,
+  'onResult' | 'presets' | 'resolveInput'
+> {
+  readonly ctx?: Partial<TrailContext> | undefined;
+  readonly graph: Topo;
+}
+
+/** A test harness for CLI commands. */
+export interface CliHarness {
+  /** Execute a CLI command string and capture output. */
+  run(command: string): Promise<CliHarnessResult>;
+}
+
+/** The result of a CLI harness command execution. */
+export interface CliHarnessResult {
+  readonly error?:
+    | {
+        readonly category: string;
+        readonly code: string;
+        readonly message: string;
+      }
+    | undefined;
+  readonly exitCode: number;
+  /** Parsed JSON output if --output json was used. */
+  readonly json?: unknown | undefined;
+  readonly stderr: string;
+  readonly stdout: string;
+}
 
 // ---------------------------------------------------------------------------
 // Tokenizer
@@ -30,55 +58,31 @@ const parseCommandString = (input: string): string[] =>
 // Command resolution
 // ---------------------------------------------------------------------------
 
-/** Try to match group + name from tokens. */
-const tryGroupMatch = (
-  commands: CliCommand[],
-  firstToken: string,
-  secondToken: string | undefined,
-  tokens: string[]
-): { command: CliCommand; flagTokens: string[] } | undefined => {
-  if (secondToken === undefined || secondToken.startsWith('-')) {
-    return undefined;
-  }
-  const match = commands.find(
-    (c) => c.group === firstToken && c.name === secondToken
-  );
-  if (match === undefined) {
-    return undefined;
-  }
-  return { command: match, flagTokens: tokens.slice(2) };
-};
+const matchesPath = (
+  path: readonly string[],
+  tokens: readonly string[]
+): boolean =>
+  path.length <= tokens.length &&
+  path.every((segment, index) => tokens[index] === segment);
 
-/** Try to match a direct name from the first token. */
-const tryDirectMatch = (
+/** Resolve a command from tokens using the longest matching command path. */
+const resolveCommand = (
   commands: CliCommand[],
-  firstToken: string,
   tokens: string[]
 ): { command: CliCommand; flagTokens: string[] } | undefined => {
-  const match = commands.find(
-    (c) => c.name === firstToken && c.group === undefined
-  );
-  if (match === undefined) {
+  if (tokens.length === 0) {
     return undefined;
   }
-  return { command: match, flagTokens: tokens.slice(1) };
-};
 
-/** Resolve a command from tokens, handling group.name patterns. */
-const resolveCommand = (
-  commands: CliCommand[],
-  tokens: string[]
-): { command: CliCommand; flagTokens: string[] } | undefined => {
-  const [firstToken, secondToken] = tokens;
+  const [match] = commands
+    .filter((command) => matchesPath(command.path, tokens))
+    .toSorted((a, b) => b.path.length - a.path.length);
 
-  if (firstToken === undefined) {
+  if (match === undefined) {
     return undefined;
   }
 
-  return (
-    tryGroupMatch(commands, firstToken, secondToken, tokens) ??
-    tryDirectMatch(commands, firstToken, tokens)
-  );
+  return { command: match, flagTokens: tokens.slice(match.path.length) };
 };
 
 // ---------------------------------------------------------------------------
@@ -230,10 +234,16 @@ const buildErrorResult = (
   streams: CapturedStreams
 ): CliHarnessResult => {
   streams.restore();
-  const message = error instanceof Error ? error.message : String(error);
+  const actualError = error instanceof Error ? error : new Error(String(error));
+  const projection = projectPublicSurfaceError('cli', actualError);
   return {
+    error: {
+      category: projection.category,
+      code: projection.name,
+      message: projection.message,
+    },
     exitCode: 1,
-    stderr: streams.getStderr() || message,
+    stderr: streams.getStderr() || projection.message,
     stdout: streams.getStdout(),
   };
 };
@@ -242,16 +252,23 @@ const buildErrorResult = (
 const executeCommand = async (
   command: CliCommand,
   flags: Record<string, unknown>,
-  streams: CapturedStreams
+  streams: CapturedStreams,
+  ctxOverrides?: Partial<TrailContext>
 ): Promise<CliHarnessResult> => {
-  const ctx = createTestContext();
+  const ctx = mergeTestContext(ctxOverrides);
   const result = await command.execute({}, flags, ctx);
   streams.restore();
 
   if (result.isErr()) {
+    const projection = projectPublicSurfaceError('cli', result.error);
     return {
+      error: {
+        category: projection.category,
+        code: projection.name,
+        message: projection.message,
+      },
       exitCode: 1,
-      stderr: streams.getStderr() || result.error.message,
+      stderr: streams.getStderr() || projection.message,
       stdout: streams.getStdout(),
     };
   }
@@ -262,7 +279,8 @@ const executeCommand = async (
 /** Run the full command pipeline: resolve, parse, execute. */
 const runCommand = async (
   commands: CliCommand[],
-  commandString: string
+  commandString: string,
+  ctxOverrides?: Partial<TrailContext>
 ): Promise<CliHarnessResult> => {
   const parts = parseCommandString(commandString);
   const resolved = resolveCommand(commands, parts);
@@ -279,7 +297,7 @@ const runCommand = async (
   const streams = captureStreams();
 
   try {
-    return await executeCommand(command, flags, streams);
+    return await executeCommand(command, flags, streams, ctxOverrides);
   } catch (error: unknown) {
     return buildErrorResult(error, streams);
   }
@@ -292,19 +310,26 @@ const runCommand = async (
 /**
  * Create a CLI harness for integration testing.
  *
- * Builds commands from the app's topo and provides a `run()` method
+ * Builds commands from the graph's topo and provides a `run()` method
  * that parses command strings and executes them in-process.
  *
  * ```ts
- * const harness = createCliHarness({ app });
+ * import { createCliHarness } from '@ontrails/testing/cli';
+ *
+ * const harness = createCliHarness({ graph });
  * const result = await harness.run("entity show --name Alpha --output json");
  * expect(result.exitCode).toBe(0);
  * ```
  */
 export const createCliHarness = (options: CliHarnessOptions): CliHarness => {
-  const commands = buildCliCommands(options.app);
+  const { ctx, graph, ...deriveOptions } = options;
+  const commandsResult = deriveCliCommands(graph, deriveOptions);
+  if (commandsResult.isErr()) {
+    throw commandsResult.error;
+  }
+  const commands = commandsResult.value;
 
   return {
-    run: (commandString: string) => runCommand(commands, commandString),
+    run: (commandString: string) => runCommand(commands, commandString, ctx),
   };
 };

package/src/harness-http.ts

@@ -0,0 +1,341 @@
+/**
+ * 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 {
+  DeriveHttpRoutesOptions,
+  HttpHeaderSource,
+  HttpMethod,
+  HttpRouteDefinition,
+} from '@ontrails/http';
+import type { Topo, TrailContext, TrailContextInit } from '@ontrails/core';
+import { NotFoundError, projectPublicSurfaceError } from '@ontrails/core';
+
+import { mergeTestContext } from './context.js';
+
+/** Options for creating an HTTP harness. */
+export interface HttpHarnessOptions extends DeriveHttpRoutesOptions {
+  readonly ctx?: Partial<TrailContext> | undefined;
+  readonly graph: Topo;
+}
+
+export interface HttpHarnessRequest {
+  readonly abortSignal?: AbortSignal | undefined;
+  readonly body?: unknown | undefined;
+  readonly headers?: HttpHeaderSource | undefined;
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly query?: Record<string, unknown> | undefined;
+  readonly requestId?: string | undefined;
+}
+
+export interface HttpHarnessRequestOptions extends Omit<
+  HttpHarnessRequest,
+  'body' | 'method' | 'path' | 'query'
+> {
+  readonly query?: Record<string, unknown> | undefined;
+}
+
+/** A test harness for HTTP route projections. */
+export interface HttpHarness {
+  /** Execute a raw HTTP-style harness request. */
+  request(request: HttpHarnessRequest): Promise<HttpHarnessResult>;
+  /** Execute a GET request, reading input from query params. */
+  get(
+    path: string,
+    query?: Record<string, unknown>,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a POST request, reading input from the JSON-like body value. */
+  post(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a PUT request. */
+  put(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a PATCH request. */
+  patch(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a DELETE request. */
+  delete(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+}
+
+export interface HttpHarnessErrorBody {
+  readonly error: {
+    readonly category: string;
+    readonly code: string;
+    readonly message: string;
+  };
+}
+
+export interface HttpHarnessSuccessBody {
+  readonly data: unknown;
+}
+
+/** The result of an HTTP harness request. */
+export interface HttpHarnessResult {
+  readonly body: HttpHarnessErrorBody | HttpHarnessSuccessBody;
+  readonly data?: unknown | undefined;
+  readonly error?: HttpHarnessErrorBody['error'] | undefined;
+  readonly ok: boolean;
+  readonly status: number;
+}
+
+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/http';
+ *
+ * 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

@@ -1,18 +1,40 @@
 /**
  * MCP integration test harness.
  *
- * Builds MCP tools from an App, invokes them directly (no transport),
+ * Builds MCP tools from a graph, invokes them directly (no transport),
  * and returns the MCP tool response.
  */
 
-import { buildMcpTools } from '@ontrails/mcp';
-import type { McpToolDefinition } from '@ontrails/mcp';
-
+import { deriveMcpTools } from '@ontrails/mcp';
 import type {
-  McpHarness,
-  McpHarnessOptions,
-  McpHarnessResult,
-} from './types.js';
+  DeriveMcpToolsOptions,
+  McpExtra,
+  McpToolDefinition,
+} from '@ontrails/mcp';
+import type { Topo } from '@ontrails/core';
+
+/** Options for creating an MCP harness. */
+export interface McpHarnessOptions extends DeriveMcpToolsOptions {
+  readonly extra?: Partial<McpExtra> | undefined;
+  readonly graph: Topo;
+}
+
+/** A test harness for MCP tools. */
+export interface McpHarness {
+  /** Call an MCP tool by name with arguments. */
+  callTool(
+    name: string,
+    args: Record<string, unknown>
+  ): Promise<McpHarnessResult>;
+}
+
+/** The result of an MCP harness tool invocation. */
+export interface McpHarnessResult {
+  readonly content: unknown;
+  readonly isError: boolean;
+  readonly meta?: Record<string, unknown> | undefined;
+  readonly structuredContent?: Record<string, unknown> | undefined;
+}
 
 // ---------------------------------------------------------------------------
 // createMcpHarness
@@ -21,19 +43,25 @@ import type {
 /**
  * Create an MCP harness for integration testing.
  *
- * Builds MCP tools from the app's topo and provides a `callTool()` method
- * that invokes tools directly without any transport layer.
+ * Builds MCP tools from the graph's topo and provides a `callTool()` method
+ * that invokes tools directly without any transport boundary.
  *
  * ```ts
- * const harness = createMcpHarness({ app });
+ * import { createMcpHarness } from '@ontrails/testing/mcp';
+ *
+ * const harness = createMcpHarness({ graph });
  * const result = await harness.callTool("myapp_entity_show", { name: "Alpha" });
  * expect(result.isError).toBe(false);
  * ```
  */
 export const createMcpHarness = (options: McpHarnessOptions): McpHarness => {
-  const tools = buildMcpTools(options.app);
+  const { extra, graph, ...deriveOptions } = options;
+  const toolsResult = deriveMcpTools(graph, deriveOptions);
+  if (toolsResult.isErr()) {
+    throw toolsResult.error;
+  }
   const toolMap = new Map<string, McpToolDefinition>();
-  for (const tool of tools) {
+  for (const tool of toolsResult.value) {
     toolMap.set(tool.name, tool);
   }
 
@@ -51,14 +79,16 @@ export const createMcpHarness = (options: McpHarnessOptions): McpHarness => {
       }
 
       const result = await tool.handler(args, {
-        progressToken: undefined,
-        sendProgress: undefined,
-        signal: undefined,
+        abortSignal: extra?.abortSignal,
+        progressToken: extra?.progressToken,
+        sendProgress: extra?.sendProgress,
       });
 
       return {
         content: result.content,
         isError: result.isError ?? false,
+        meta: result._meta,
+        structuredContent: result.structuredContent,
       };
     },
   };

package/src/http.ts

@@ -0,0 +1,10 @@
+export { createHttpHarness } from './harness-http.js';
+export type {
+  HttpHarness,
+  HttpHarnessErrorBody,
+  HttpHarnessOptions,
+  HttpHarnessRequest,
+  HttpHarnessRequestOptions,
+  HttpHarnessResult,
+  HttpHarnessSuccessBody,
+} from './harness-http.js';