@jterrazz/test 3.1.0 → 3.3.0

package/dist/index.d.cts

@@ -0,0 +1,381 @@
+import { DeepMockProxy } from "vitest-mock-extended";
+
+//#region src/mocking/mock-of-date.d.ts
+interface MockDatePort {
+  reset: () => void;
+  set: (date: Date | number | string) => void;
+}
+declare const mockOfDate: MockDatePort;
+//#endregion
+//#region src/mocking/mock-of.d.ts
+type MockPort = <T>() => DeepMockProxy<T>;
+declare const mockOf: MockPort;
+//#endregion
+//#region src/specification/ports/database.port.d.ts
+/**
+ * Abstract database interface for specification runners.
+ * Implement this to plug in your database stack.
+ */
+interface DatabasePort {
+  /** Execute raw SQL (for seeding test data). */
+  seed(sql: string): Promise<void>;
+  /** Query a table and return rows as arrays of values. */
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  /** Reset database to clean state between tests. */
+  reset(): Promise<void>;
+}
+//#endregion
+//#region src/infrastructure/services/service.port.d.ts
+/**
+ * A service handle — returned by factory functions like postgres(), redis().
+ * Mutable: connectionString is populated after the orchestrator starts containers.
+ */
+interface ServiceHandle {
+  /** Service type identifier. */
+  readonly type: string;
+  /** Compose service name (if linked). */
+  readonly composeName: null | string;
+  /** Default container port for this service type. */
+  readonly defaultPort: number;
+  /** Default Docker image for this service type. */
+  readonly defaultImage: string;
+  /** Environment variables to pass to the container. */
+  readonly environment: Record<string, string>;
+  /** Connection string — populated after start. */
+  connectionString: string;
+  /** Whether this service has been started. */
+  started: boolean;
+  /** Build the connection string from host and port. */
+  buildConnectionString(host: string, port: number): string;
+  /** Create a DatabasePort adapter (if this is a database). Returns null otherwise. */
+  createDatabaseAdapter(): DatabasePort | null;
+  /** Verify the service is ready and accepting connections. Throws with context if not. */
+  healthcheck(): Promise<void>;
+  /** Run initialization scripts (e.g., init.sql). Throws with SQL error context if it fails. */
+  initialize(composeDir: string): Promise<void>;
+  /** Reset state between tests (truncate tables, flush cache, etc.) */
+  reset(): Promise<void>;
+}
+//#endregion
+//#region src/infrastructure/orchestrator.d.ts
+interface OrchestratorOptions {
+  services: ServiceHandle[];
+  mode: "e2e" | "integration";
+  root?: string;
+}
+/**
+ * Orchestrator for test infrastructure.
+ * Integration: starts services via testcontainers.
+ * E2E: runs full docker compose up.
+ */
+declare class Orchestrator {
+  private services;
+  private mode;
+  private root;
+  private running;
+  private composeStack;
+  private composeHandles;
+  private started;
+  constructor(options: OrchestratorOptions);
+  /**
+   * Start declared services via testcontainers (integration mode).
+   * Reads image/env config from docker-compose.test.yaml if a service has compose: "name".
+   */
+  start(): Promise<void>;
+  /**
+   * Stop testcontainers (integration mode).
+   */
+  stop(): Promise<void>;
+  /**
+   * Start full docker compose stack (e2e mode).
+   * Auto-detects infra services and creates handles for them.
+   */
+  startCompose(): Promise<void>;
+  /**
+   * Stop docker compose stack (e2e mode).
+   */
+  stopCompose(): Promise<void>;
+  /**
+   * Get a database service by compose name, or the first one if no name given.
+   */
+  getDatabase(serviceName?: string): DatabasePort | null;
+  /**
+   * Get all database services keyed by compose name.
+   */
+  getDatabases(): Map<string, DatabasePort>;
+  /**
+   * Get app URL from compose (e2e mode).
+   */
+  getAppUrl(): null | string;
+}
+//#endregion
+//#region src/specification/ports/command.port.d.ts
+/**
+ * Result of executing a CLI command.
+ */
+interface CommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+/**
+ * Abstract CLI interface for specification runners.
+ * Implement this to plug in your command execution strategy.
+ */
+interface CommandPort {
+  /** Execute a CLI command with the given arguments in the given working directory. */
+  exec(args: string, cwd: string): Promise<CommandResult>;
+}
+//#endregion
+//#region src/specification/ports/server.port.d.ts
+/**
+ * HTTP response returned by a server port.
+ */
+interface ServerResponse {
+  status: number;
+  body: unknown;
+  headers: Record<string, string>;
+}
+/**
+ * Abstract server interface for specification runners.
+ * Integration mode uses in-process app, E2E mode uses real HTTP.
+ */
+interface ServerPort {
+  /** Send an HTTP request and return the response. */
+  request(method: string, path: string, body?: unknown): Promise<ServerResponse>;
+}
+//#endregion
+//#region src/specification/specification.d.ts
+interface SpecificationConfig {
+  command?: CommandPort;
+  database?: DatabasePort;
+  databases?: Map<string, DatabasePort>;
+  fixturesRoot?: string;
+  server?: ServerPort;
+}
+interface RequestInfo {
+  body?: unknown;
+  method: string;
+  path: string;
+}
+declare class SpecificationResult {
+  private commandResult?;
+  private config;
+  private requestInfo?;
+  private response?;
+  private testDir;
+  private workDir?;
+  constructor(options: {
+    commandResult?: CommandResult;
+    config: SpecificationConfig;
+    requestInfo?: RequestInfo;
+    response?: ServerResponse;
+    testDir: string;
+    workDir?: string;
+  });
+  expectStatus(code: number): this;
+  expectResponse(file: string): this;
+  expectExitCode(code: number): this;
+  expectStdout(file: string): this;
+  expectStdoutContains(str: string): this;
+  expectStderr(file: string): this;
+  expectStderrContains(str: string): this;
+  expectTable(table: string, options: {
+    columns: string[];
+    rows: unknown[][];
+    service?: string;
+  }): Promise<this>;
+  expectFile(path: string): this;
+  expectNoFile(path: string): this;
+  expectFileContains(path: string, content: string): this;
+  private resolveDatabase;
+  private resolveWorkPath;
+}
+declare class SpecificationBuilder {
+  private commandArgs;
+  private config;
+  private fixtures;
+  private label;
+  private mocks;
+  private projectName;
+  private request;
+  private seeds;
+  private testDir;
+  constructor(config: SpecificationConfig, testDir: string, label: string);
+  seed(file: string, options?: {
+    service?: string;
+  }): this;
+  fixture(file: string): this;
+  project(name: string): this;
+  mock(file: string): this;
+  get(path: string): this;
+  post(path: string, bodyFile?: string): this;
+  put(path: string, bodyFile?: string): this;
+  delete(path: string): this;
+  exec(args: string): this;
+  run(): Promise<SpecificationResult>;
+  private prepareWorkDir;
+  private runHttpAction;
+  private runCliAction;
+}
+type SpecificationRunner = (label: string) => SpecificationBuilder;
+//#endregion
+//#region src/infrastructure/services/postgres.d.ts
+interface PostgresOptions {
+  /** Map to a service in docker-compose.test.yaml. */
+  compose?: string;
+  /** Override image. */
+  image?: string;
+  /** Override environment variables. */
+  env?: Record<string, string>;
+}
+declare class PostgresHandle implements DatabasePort, ServiceHandle {
+  readonly type = "postgres";
+  readonly composeName: null | string;
+  readonly defaultPort = 5432;
+  readonly defaultImage: string;
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  constructor(options?: PostgresOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort;
+  healthcheck(): Promise<void>;
+  initialize(composeDir: string): Promise<void>;
+  private getClient;
+  seed(sql: string): Promise<void>;
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  reset(): Promise<void>;
+}
+/**
+ * Create a PostgreSQL service handle.
+ *
+ * @example
+ * const db = postgres({ compose: "db" });
+ * // After start: db.connectionString is populated
+ */
+declare function postgres(options?: PostgresOptions): PostgresHandle;
+//#endregion
+//#region src/infrastructure/services/redis.d.ts
+interface RedisOptions {
+  /** Map to a service in docker-compose.test.yaml. */
+  compose?: string;
+  /** Override image. */
+  image?: string;
+}
+declare class RedisHandle implements ServiceHandle {
+  readonly type = "redis";
+  readonly composeName: null | string;
+  readonly defaultPort = 6379;
+  readonly defaultImage: string;
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  constructor(options?: RedisOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort | null;
+  healthcheck(): Promise<void>;
+  initialize(): Promise<void>;
+  reset(): Promise<void>;
+}
+/**
+ * Create a Redis service handle.
+ *
+ * @example
+ * const cache = redis({ compose: "cache" });
+ * // After start: cache.connectionString is populated
+ */
+declare function redis(options?: RedisOptions): RedisHandle;
+//#endregion
+//#region src/specification/adapters/exec.adapter.d.ts
+/**
+ * Executes CLI commands via execSync.
+ * Used by cli() for local command execution.
+ */
+declare class ExecAdapter implements CommandPort {
+  private command;
+  constructor(command: string);
+  exec(args: string, cwd: string): Promise<CommandResult>;
+}
+//#endregion
+//#region src/specification/adapters/fetch.adapter.d.ts
+/**
+ * Server adapter for real HTTP — sends actual fetch requests.
+ * Used by e2e() specification runner.
+ */
+declare class FetchAdapter implements ServerPort {
+  private baseUrl;
+  constructor(url: string);
+  request(method: string, path: string, body?: unknown): Promise<ServerResponse>;
+}
+//#endregion
+//#region src/specification/adapters/hono.adapter.d.ts
+/**
+ * Server adapter for Hono — in-process requests, no real HTTP.
+ * Used by integration() specification runner.
+ */
+declare class HonoAdapter implements ServerPort {
+  private app;
+  constructor(app: {
+    request: (path: string, init?: RequestInit) => Promise<Response> | Response;
+  });
+  request(method: string, path: string, body?: unknown): Promise<ServerResponse>;
+}
+//#endregion
+//#region src/infrastructure/reporter.d.ts
+declare function stripAnsi(str: string): string;
+declare function normalizeOutput(str: string): string;
+//#endregion
+//#region src/specification/index.d.ts
+type HonoApp = {
+  fetch: (...args: any[]) => any;
+  request: (path: string, init?: RequestInit) => Promise<Response> | Response;
+};
+interface IntegrationOptions {
+  /** Factory that returns a Hono app — called after services start. */
+  app: () => HonoApp;
+  /** Project root for compose detection (relative paths supported). */
+  root?: string;
+  /** Declared services — started via testcontainers. */
+  services: ServiceHandle[];
+}
+interface E2eOptions {
+  /** Project root — must contain docker/compose.test.yaml. */
+  root?: string;
+}
+interface CliOptions {
+  /** CLI command to run (resolved from node_modules/.bin or PATH). */
+  command: string;
+  /** Project root — base dir for .project() fixture lookup (relative paths supported). */
+  root?: string;
+  /** Optional infrastructure services (started via testcontainers). */
+  services?: ServiceHandle[];
+}
+interface SpecificationRunnerWithCleanup extends SpecificationRunner {
+  cleanup: () => Promise<void>;
+  orchestrator: Orchestrator;
+}
+/**
+ * Create an integration specification runner.
+ * Starts infra containers via testcontainers, app runs in-process.
+ */
+declare function integration(options: IntegrationOptions): Promise<SpecificationRunnerWithCleanup>;
+/**
+ * Create an E2E specification runner.
+ * Starts full docker compose stack. App URL and database auto-detected.
+ */
+declare function e2e(options?: E2eOptions): Promise<SpecificationRunnerWithCleanup>;
+/**
+ * Create a CLI specification runner.
+ * Runs CLI commands against fixture projects. Optionally starts infrastructure.
+ *
+ * @example
+ * export const spec = await cli({
+ *     command: resolve(import.meta.dirname, "../../bin/my-cli.sh"),
+ *     root: "../fixtures",
+ * });
+ */
+declare function cli(options: CliOptions): Promise<SpecificationRunnerWithCleanup>;
+//#endregion
+export { type CommandPort, type CommandResult, type DatabasePort, ExecAdapter, FetchAdapter, HonoAdapter, type MockDatePort, type MockPort, Orchestrator, type ServerPort, type ServerResponse, cli, e2e, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, stripAnsi };
+//# sourceMappingURL=index.d.cts.map