@ontrails/testing 0.2.0

package/src/harness-cli.ts

@@ -0,0 +1,335 @@
+/**
+ * CLI integration test harness.
+ *
+ * Builds CLI commands from a graph, executes them in-process,
+ * and captures stdout/stderr.
+ */
+
+import { deriveCliCommands } from '@ontrails/cli';
+import type { CliCommand, DeriveCliCommandsOptions } from '@ontrails/cli';
+import type { Topo, TrailContext } from '@ontrails/core';
+import { renderPublicSurfaceError } from '@ontrails/core';
+
+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
+// ---------------------------------------------------------------------------
+
+/** Parse a command string into tokens (simple split, no quoting support). */
+const parseCommandString = (input: string): string[] =>
+  input
+    .trim()
+    .split(/\s+/)
+    .filter((s) => s.length > 0);
+
+// ---------------------------------------------------------------------------
+// Command resolution
+// ---------------------------------------------------------------------------
+
+const matchesPath = (
+  path: readonly string[],
+  tokens: readonly string[]
+): boolean =>
+  path.length <= tokens.length &&
+  path.every((segment, index) => tokens[index] === segment);
+
+/** Resolve a command from tokens using the longest matching command path. */
+const resolveCommand = (
+  commands: CliCommand[],
+  tokens: string[]
+): { command: CliCommand; flagTokens: string[] } | undefined => {
+  if (tokens.length === 0) {
+    return undefined;
+  }
+
+  const [match] = commands
+    .filter((command) => matchesPath(command.path, tokens))
+    .toSorted((a, b) => b.path.length - a.path.length);
+
+  if (match === undefined) {
+    return undefined;
+  }
+
+  return { command: match, flagTokens: tokens.slice(match.path.length) };
+};
+
+// ---------------------------------------------------------------------------
+// Flag parsing
+// ---------------------------------------------------------------------------
+
+/** Parse a value flag (--key value) and return new index. */
+const parseValueFlag = (
+  key: string,
+  next: string,
+  flags: Record<string, unknown>
+): void => {
+  const num = Number(next);
+  flags[key] = Number.isNaN(num) ? next : num;
+};
+
+/** Parse a single flag token and advance the index. */
+const parseSingleFlag = (
+  tokens: string[],
+  i: number,
+  flags: Record<string, unknown>
+): number => {
+  const token = tokens[i];
+  if (token === undefined || !token.startsWith('--')) {
+    return i + 1;
+  }
+
+  const key = token.slice(2);
+  const next = tokens[i + 1];
+
+  if (next !== undefined && !next.startsWith('-')) {
+    parseValueFlag(key, next, flags);
+    return i + 2;
+  }
+
+  flags[key] = true;
+  return i + 1;
+};
+
+/** Parse flag tokens into a record. */
+const parseFlagTokens = (tokens: string[]): Record<string, unknown> => {
+  const flags: Record<string, unknown> = {};
+  let i = 0;
+
+  while (i < tokens.length) {
+    i = parseSingleFlag(tokens, i, flags);
+  }
+
+  return flags;
+};
+
+// ---------------------------------------------------------------------------
+// Stream capture
+// ---------------------------------------------------------------------------
+
+interface CapturedStreams {
+  readonly getStderr: () => string;
+  readonly getStdout: () => string;
+  readonly restore: () => void;
+  readonly writeStdout: (text: string) => void;
+}
+
+/** Create interceptors for stdout/stderr capture. */
+const captureStreams = (): CapturedStreams => {
+  let stdout = '';
+  let stderr = '';
+  const origStdoutWrite = process.stdout.write;
+  const origStderrWrite = process.stderr.write;
+
+  process.stdout.write = ((chunk: string | Uint8Array): boolean => {
+    stdout +=
+      typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+
+  process.stderr.write = ((chunk: string | Uint8Array): boolean => {
+    stderr +=
+      typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  return {
+    getStderr: () => stderr,
+    getStdout: () => stdout,
+    restore: () => {
+      process.stdout.write = origStdoutWrite;
+      process.stderr.write = origStderrWrite;
+    },
+    writeStdout: (text: string) => {
+      stdout += text;
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Output formatting
+// ---------------------------------------------------------------------------
+
+/** Try to parse a string as JSON, returning undefined on failure. */
+const tryParseJson = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+
+/** Format result value into stdout and build the CLI result. */
+const formatSuccessResult = (
+  value: unknown,
+  flags: Record<string, unknown>,
+  streams: CapturedStreams
+): CliHarnessResult => {
+  const outputMode =
+    flags['output'] ?? (flags['json'] === true ? 'json' : 'text');
+
+  if (outputMode === 'json') {
+    const jsonStr = `${JSON.stringify(value, null, 2)}\n`;
+    streams.writeStdout(jsonStr);
+    return {
+      exitCode: 0,
+      json: tryParseJson(jsonStr),
+      stderr: streams.getStderr(),
+      stdout: streams.getStdout(),
+    };
+  }
+
+  const formatted =
+    typeof value === 'string'
+      ? `${value}\n`
+      : `${JSON.stringify(value, null, 2)}\n`;
+  streams.writeStdout(formatted);
+
+  return {
+    exitCode: 0,
+    json: tryParseJson(streams.getStdout().trim()),
+    stderr: streams.getStderr(),
+    stdout: streams.getStdout(),
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Execute command
+// ---------------------------------------------------------------------------
+
+/** Build an error result from a caught exception. */
+const buildErrorResult = (
+  error: unknown,
+  streams: CapturedStreams
+): CliHarnessResult => {
+  streams.restore();
+  const actualError = error instanceof Error ? error : new Error(String(error));
+  const rendering = renderPublicSurfaceError('cli', actualError);
+  return {
+    error: {
+      category: rendering.category,
+      code: rendering.name,
+      message: rendering.message,
+    },
+    exitCode: 1,
+    stderr: streams.getStderr() || rendering.message,
+    stdout: streams.getStdout(),
+  };
+};
+
+/** Execute a resolved command and return the result. */
+const executeCommand = async (
+  command: CliCommand,
+  flags: Record<string, unknown>,
+  streams: CapturedStreams,
+  ctxOverrides?: Partial<TrailContext>
+): Promise<CliHarnessResult> => {
+  const ctx = mergeTestContext(ctxOverrides);
+  const result = await command.execute({}, flags, ctx);
+  streams.restore();
+
+  if (result.isErr()) {
+    const rendering = renderPublicSurfaceError('cli', result.error);
+    return {
+      error: {
+        category: rendering.category,
+        code: rendering.name,
+        message: rendering.message,
+      },
+      exitCode: 1,
+      stderr: streams.getStderr() || rendering.message,
+      stdout: streams.getStdout(),
+    };
+  }
+
+  return formatSuccessResult(result.value, flags, streams);
+};
+
+/** Run the full command pipeline: resolve, parse, execute. */
+const runCommand = async (
+  commands: CliCommand[],
+  commandString: string,
+  ctxOverrides?: Partial<TrailContext>
+): Promise<CliHarnessResult> => {
+  const parts = parseCommandString(commandString);
+  const resolved = resolveCommand(commands, parts);
+  if (resolved === undefined) {
+    return {
+      exitCode: 1,
+      stderr: `Unknown command: ${commandString}`,
+      stdout: '',
+    };
+  }
+
+  const { command, flagTokens } = resolved;
+  const flags = parseFlagTokens(flagTokens);
+  const streams = captureStreams();
+
+  try {
+    return await executeCommand(command, flags, streams, ctxOverrides);
+  } catch (error: unknown) {
+    return buildErrorResult(error, streams);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// createCliHarness
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a CLI harness for integration testing.
+ *
+ * Builds commands from the graph's topo and provides a `run()` method
+ * that parses command strings and executes them in-process.
+ *
+ * ```ts
+ * 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 { 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, 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, renderPublicSurfaceError } 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 renderings. */
+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 rendering = renderPublicSurfaceError('http', error);
+  const body = {
+    error: {
+      category: rendering.category,
+      code: rendering.name,
+      message: rendering.message,
+    },
+  };
+  return {
+    body,
+    error: body.error,
+    ok: false,
+    status: rendering.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,
+  };
+};