@jterrazz/test 5.3.1 → 6.0.0

package/dist/index.d.ts

@@ -1,58 +1,16 @@
-import { DeepMockProxy } from "vitest-mock-extended";
+import { a as ServiceHandle, i as postgres, n as redis, o as IsolationStrategy, r as PostgresOptions, s as DatabasePort, t as RedisOptions } from "./redis.adapter.js";
+import { i as mockOfDate, n as mockOf, r as MockDatePort, t as MockPort } from "./mock-of.js";
 
-//#region src/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/ports/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/ports/command.port.d.ts
 /**
- * Result of executing a CLI command.
+ * Result of executing a CLI command, including exit code and captured output streams.
  */
 interface CommandResult {
+  /** Process exit code (0 = success). */
   exitCode: number;
+  /** Captured standard output. */
   stdout: string;
+  /** Captured standard error. */
   stderr: string;
 }
 /**
@@ -82,19 +40,22 @@ interface CommandPort {
 //#endregion
 //#region src/ports/server.port.d.ts
 /**
- * HTTP response returned by a server port.
+ * HTTP response returned by a server port, with parsed JSON body.
  */
 interface ServerResponse {
+  /** HTTP status code. */
   status: number;
+  /** Parsed JSON response body, or null if parsing failed. */
   body: unknown;
+  /** Response headers as a flat key-value map. */
   headers: Record<string, string>;
 }
 /**
  * Abstract server interface for specification runners.
- * Integration mode uses in-process app, E2E mode uses real HTTP.
+ * Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
  */
 interface ServerPort {
-  /** Send an HTTP request and return the response. */
+  /** Send an HTTP request and return the parsed response. */
   request(method: string, path: string, body?: unknown): Promise<ServerResponse>;
 }
 //#endregion
@@ -108,6 +69,10 @@ interface DirectorySnapshotOptions {
    */
   update?: boolean;
 }
+/**
+ * Handle to a directory produced by a specification run.
+ * Supports snapshot-based assertions via {@link toMatchFixture} and file listing via {@link files}.
+ */
 declare class DirectoryAccessor {
   private absPath;
   private testDir;
@@ -128,30 +93,54 @@ declare class DirectoryAccessor {
 }
 //#endregion
 //#region src/builder/response-accessor.d.ts
+/** Accessor for an HTTP response body with file-based assertion support. */
 declare class ResponseAccessor {
   readonly body: unknown;
   private testDir;
   constructor(body: unknown, testDir: string);
+  /**
+   * Assert that the response body matches the JSON in `responses/{file}`.
+   *
+   * @example
+   *   result.response.toMatchFile("expected-items.json");
+   */
   toMatchFile(file: string): void;
 }
 //#endregion
 //#region src/builder/table-assertion.d.ts
+/** Assertion helper for verifying database table contents after a specification run. */
 declare class TableAssertion {
   private tableName;
   private db;
   constructor(tableName: string, db: DatabasePort);
+  /**
+   * Assert that the table contains exactly the expected rows for the given columns.
+   *
+   * @example
+   *   await result.table("users").toMatch({
+   *     columns: ["name", "email"],
+   *     rows: [["Alice", "alice@example.com"]],
+   *   });
+   */
   toMatch(expected: {
     columns: string[];
     rows: unknown[][];
   }): Promise<void>;
+  /** Assert that the table has zero rows. */
   toBeEmpty(): Promise<void>;
 }
 //#endregion
 //#region src/builder/specification-result.d.ts
+/** Read-only handle to a single file produced by a CLI action. */
 interface FileAccessor {
+  /** The UTF-8 text content. Throws if the file does not exist. */
   readonly content: string;
   readonly exists: boolean;
 }
+/**
+ * The outcome of a single specification run.
+ * Provides accessors for CLI output, HTTP responses, files, directories, and database tables.
+ */
 declare class SpecificationResult {
   private commandResult?;
   private config;
@@ -171,13 +160,29 @@ declare class SpecificationResult {
     testDir: string;
     workDir?: string;
   });
+  /** The process exit code. Only available after a CLI action. */
   get exitCode(): number;
+  /** The HTTP response status code. Only available after an HTTP action. */
   get status(): number;
+  /** The captured standard output. Only available after a CLI action. */
   get stdout(): string;
+  /** The captured standard error. Only available after a CLI action. */
   get stderr(): string;
+  /**
+   * Extract text blocks from stdout that contain a pattern.
+   * Useful for parsing structured CLI output (linters, compilers).
+   *
+   * @example
+   *   expect(result.grep('error.ts')).toContain('no-unused-vars');
+   */
+  grep(pattern: string): string;
+  /** Access the HTTP response body for assertions. Only available after an HTTP action. */
   get response(): ResponseAccessor;
+  /** Access a directory (relative to the working directory) for snapshot assertions. */
   directory(path?: string): DirectoryAccessor;
+  /** Access a single file (relative to the working directory) for content assertions. */
   file(path: string): FileAccessor;
+  /** Access a database table for row-level assertions. */
   table(tableName: string, options?: {
     service?: string;
   }): TableAssertion;
@@ -185,6 +190,7 @@ declare class SpecificationResult {
 }
 //#endregion
 //#region src/builder/specification-builder.d.ts
+/** Adapter configuration passed to the specification runner at setup time. */
 interface SpecificationConfig {
   command?: CommandPort;
   database?: DatabasePort;
@@ -192,6 +198,13 @@ interface SpecificationConfig {
   fixturesRoot?: string;
   server?: ServerPort;
 }
+/**
+ * Fluent builder for declaring a single test specification.
+ *
+ * Chain setup methods ({@link seed}, {@link fixture}, {@link env}), an action
+ * ({@link get}, {@link post}, {@link exec}), then call {@link run} to execute
+ * and receive a {@link SpecificationResult} for assertions.
+ */
 declare class SpecificationBuilder {
   private commandArgs;
   private commandEnv;
@@ -205,11 +218,20 @@ declare class SpecificationBuilder {
   private spawnConfig;
   private testDir;
   constructor(config: SpecificationConfig, testDir: string, label: string);
+  /**
+   * Queue a SQL seed file to run before the action.
+   *
+   * @example
+   *   spec("creates user").seed("users.sql").exec("list-users").run();
+   */
   seed(file: string, options?: {
     service?: string;
   }): this;
+  /** Copy a file or directory from `fixtures/` into the working directory before execution. */
   fixture(file: string): this;
+  /** Copy an entire project fixture from `fixturesRoot` into the working directory. */
   project(name: string): this;
+  /** Register an MSW mock definition file from `mock/` to intercept HTTP calls. */
   mock(file: string): this;
   /**
    * Set environment variables for the CLI process. Merged on top of process.env.
@@ -222,26 +244,152 @@ declare class SpecificationBuilder {
    *   spec("...").env({ HOME: "$WORKDIR", TZ: "UTC" }).exec("status").run();
    */
   env(env: CommandEnv): this;
+  /**
+   * Send a GET request to the server adapter.
+   *
+   * @example
+   *   spec("list items").get("/api/items").run();
+   */
   get(path: string): this;
+  /**
+   * Send a POST request to the server adapter.
+   *
+   * @param bodyFile - Optional JSON file from `requests/` to use as the request body.
+   * @example
+   *   spec("create item").post("/api/items", "new-item.json").run();
+   */
   post(path: string, bodyFile?: string): this;
+  /** Send a PUT request to the server adapter. */
   put(path: string, bodyFile?: string): this;
+  /** Send a DELETE request to the server adapter. */
   delete(path: string): this;
+  /**
+   * Execute a CLI command (or a sequence of commands) in an isolated working directory.
+   * When an array is passed, commands run sequentially and stop on the first non-zero exit code.
+   *
+   * @example
+   *   spec("init project").exec("init --name demo").run();
+   *   spec("multi-step").exec(["init", "build"]).run();
+   */
   exec(args: string | string[]): this;
+  /** Spawn a long-running CLI process with custom spawn options (e.g. timeout, signal). */
   spawn(args: string, options: SpawnOptions): this;
+  /**
+   * Execute the specification: run seeds, copy fixtures, then perform the
+   * configured action (HTTP or CLI).
+   *
+   * @returns The result object used for assertions.
+   * @example
+   *   const result = await spec("test").exec("status").run();
+   *   expect(result.exitCode).toBe(0);
+   */
   run(): Promise<SpecificationResult>;
   private resolveEnv;
   private prepareWorkDir;
   private runHttpAction;
   private runCliAction;
 }
+/** Factory function returned by `cli()`, `integration()`, or `e2e()` that starts a new spec. */
 type SpecificationRunner = (label: string) => SpecificationBuilder;
+/**
+ * Create a {@link SpecificationRunner} bound to the given adapter configuration.
+ * The test file directory is auto-detected from the call stack.
+ */
 declare function createSpecificationRunner(config: SpecificationConfig): SpecificationRunner;
 //#endregion
+//#region src/docker/docker-port.d.ts
+/** Abstract interface for interacting with a Docker container (exec, inspect, file I/O). */
+interface DockerContainerPort {
+  /** Execute a command inside the container, return stdout */
+  exec(cmd: string[]): Promise<string>;
+  /** Read a file from inside the container */
+  file(path: string): Promise<{
+    exists: boolean;
+    content: string;
+  }>;
+  /** Check if container is running */
+  isRunning(): Promise<boolean>;
+  /** Get container logs */
+  logs(tail?: number): Promise<string>;
+  /** Get full docker inspect JSON */
+  inspect(): Promise<DockerInspectResult>;
+  /** Check if a file/directory exists */
+  exists(path: string): Promise<boolean>;
+}
+/** Normalized subset of `docker inspect` output for assertion use. */
+interface DockerInspectResult {
+  id: string;
+  name: string;
+  state: {
+    running: boolean;
+    exitCode: number;
+    status: string;
+  };
+  config: {
+    image: string;
+    env: string[];
+  };
+  hostConfig: {
+    memory: number;
+    cpuQuota: number;
+    networkMode: string;
+    mounts: Array<{
+      source: string;
+      destination: string;
+      type: string;
+    }>;
+  };
+  networkSettings: {
+    networks: Record<string, {
+      gateway: string;
+      ipAddress: string;
+    }>;
+  };
+}
+//#endregion
+//#region src/docker/docker-assertion.d.ts
+/**
+ * Fluent assertion builder for Docker containers.
+ * Chain async assertions like `toBeRunning()`, `toHaveFile()`, `toHaveMount()`.
+ */
+declare class DockerAssertion {
+  private container;
+  constructor(container: DockerContainerPort);
+  /** Assert the container is running */
+  toBeRunning(): Promise<this>;
+  /** Assert the container is NOT running / doesn't exist */
+  toNotExist(): Promise<this>;
+  /** Assert a file exists inside the container */
+  toHaveFile(path: string, opts?: {
+    containing?: string;
+  }): Promise<this>;
+  /** Assert a file does NOT exist */
+  toNotHaveFile(path: string): Promise<this>;
+  /** Assert a directory exists */
+  toHaveDirectory(path: string): Promise<this>;
+  /** Assert a mount exists */
+  toHaveMount(destination: string): Promise<this>;
+  /** Assert network mode */
+  toHaveNetwork(mode: string): Promise<this>;
+  /** Assert memory limit */
+  toHaveMemoryLimit(bytes: number): Promise<this>;
+  /** Assert CPU quota */
+  toHaveCpuQuota(quota: number): Promise<this>;
+  /** Execute a command and return output for custom assertions */
+  exec(cmd: string[]): Promise<string>;
+  /** Read a file for custom assertions */
+  readFile(path: string): Promise<string>;
+  /** Get logs for custom assertions */
+  getLogs(tail?: number): Promise<string>;
+}
+//#endregion
 //#region src/orchestrator/orchestrator.d.ts
 interface OrchestratorOptions {
   services: ServiceHandle[];
   mode: 'e2e' | 'integration';
   root?: string;
+  /** Compose project name — used for per-worker stack isolation. */
+  projectName?: string;
 }
 /**
  * Orchestrator for test infrastructure.
@@ -252,6 +400,7 @@ declare class Orchestrator {
   private services;
   private mode;
   private root;
+  private projectName;
   private running;
   private composeStack;
   private composeHandles;
@@ -290,54 +439,105 @@ declare class Orchestrator {
   getAppUrl(): null | string;
 }
 //#endregion
-//#region src/runner/integration.d.ts
-type HonoApp = {
+//#region src/runner/targets.d.ts
+/**
+ * Target factories for {@link spec}. Each target describes what is being tested
+ * and how the specification runner should connect to it.
+ */
+type HonoApp$1 = {
   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 SpecificationRunnerWithCleanup extends SpecificationRunner {
-  cleanup: () => Promise<void>;
-  orchestrator: Orchestrator;
-}
+/** In-process Hono app target. Created by {@link app}. */
+interface AppTarget {
+  readonly kind: 'app';
+  readonly factory: () => HonoApp$1;
+}
+/** Docker compose stack target. Created by {@link stack}. */
+interface StackTarget {
+  readonly kind: 'stack';
+  readonly root: string;
+}
+/** CLI command target. Created by {@link command}. */
+interface CommandTarget {
+  readonly kind: 'command';
+  readonly bin: string;
+}
+/** Any target that produces an HTTP interface (app or stack). */
+type HttpTarget = AppTarget | StackTarget;
+/** Any valid spec target. */
+type SpecTarget = AppTarget | CommandTarget | StackTarget;
 /**
- * Create an integration specification runner.
- * Starts infra containers via testcontainers, app runs in-process.
+ * Test against an in-process Hono app. Services are started via testcontainers
+ * and the app runs without network overhead.
+ *
+ * @param factory - Function that returns a Hono app instance (called after services start).
+ *
+ * @example
+ *   await spec(app(() => createApp(db)), { services: [db] });
  */
-declare function integration(options: IntegrationOptions): Promise<SpecificationRunnerWithCleanup>;
-//#endregion
-//#region src/runner/cli.d.ts
-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[];
-}
+declare function app(factory: () => HonoApp$1): AppTarget;
 /**
- * Create a CLI specification runner.
- * Runs CLI commands against fixture projects. Optionally starts infrastructure.
+ * Test against a full docker compose stack. The stack is started with
+ * `docker compose up` and real HTTP requests are sent to the app service.
+ *
+ * @param root - Project root containing `docker/compose.test.yaml`.
+ *
+ * @example
+ *   await spec(stack('../../'));
  */
-declare function cli(options: CliOptions): Promise<SpecificationRunnerWithCleanup>;
+declare function stack(root: string): StackTarget;
+/**
+ * Test a CLI binary. Each spec runs in a fresh temp directory.
+ *
+ * @param bin - Path to the CLI binary or command name (resolved from node_modules/.bin or PATH).
+ *
+ * @example
+ *   await spec(command('my-cli'), { root: '../fixtures' });
+ */
+declare function command(bin: string): CommandTarget;
 //#endregion
-//#region src/runner/e2e.d.ts
-interface E2eOptions {
-  /** Project root — must contain docker/compose.test.yaml. */
+//#region src/runner/spec.d.ts
+/** Shared options for all spec targets. */
+interface SpecOptions {
+  /** Project root for fixture lookup and compose detection (relative paths supported). */
   root?: string;
+  /** Infrastructure services to start via testcontainers. */
+  services?: ServiceHandle[];
+}
+/** A specification runner with teardown support and orchestrator access. */
+interface SpecRunner {
+  /** The function to create individual specs: `runner('label').get('/path').run()`. */
+  (label: string): SpecificationBuilder;
+  /** Stop all infrastructure started by this runner. */
+  cleanup: () => Promise<void>;
+  /**
+   * Get a Docker assertion builder for a running container.
+   *
+   * @example
+   *   await runner.docker('my-container').toBeRunning();
+   */
+  docker: (containerId: string) => DockerAssertion;
+  /** The orchestrator managing the test infrastructure lifecycle. */
+  orchestrator: Orchestrator;
 }
 /**
- * Create an E2E specification runner.
- * Starts full docker compose stack. App URL and database auto-detected.
+ * Create a specification runner for the given target.
+ *
+ * @param target - What to test against: {@link app}, {@link stack}, or {@link command}.
+ * @param options - Shared options: root directory, infrastructure services.
+ *
+ * @example
+ *   // HTTP — in-process app with testcontainers
+ *   const s = await spec(app(() => createApp(db)), { services: [db] });
+ *
+ *   // HTTP — full docker compose stack
+ *   const s = await spec(stack('../../'));
+ *
+ *   // CLI — command binary
+ *   const s = await spec(command('my-cli'), { root: '../fixtures' });
  */
-declare function e2e(options?: E2eOptions): Promise<SpecificationRunnerWithCleanup>;
+declare function spec(target: SpecTarget, options?: SpecOptions): Promise<SpecRunner>;
 //#endregion
 //#region src/ports/container.port.d.ts
 /**
@@ -361,8 +561,9 @@ interface ContainerPort {
 //#endregion
 //#region src/adapters/exec.adapter.d.ts
 /**
- * Executes CLI commands via execSync (blocking) or spawn (long-running).
- * Used by cli() for local command execution.
+ * Executes CLI commands via Node.js child_process.
+ * Uses `execSync` for one-shot commands and `spawn` for long-running processes.
+ * Used by the `cli()` specification runner.
  */
 declare class ExecAdapter implements CommandPort {
   private command;
@@ -373,8 +574,8 @@ declare class ExecAdapter implements CommandPort {
 //#endregion
 //#region src/adapters/fetch.adapter.d.ts
 /**
- * Server adapter for real HTTP — sends actual fetch requests.
- * Used by e2e() specification runner.
+ * Server adapter that sends real HTTP requests via the Fetch API.
+ * Used by the `e2e()` specification runner to hit a live server.
  */
 declare class FetchAdapter implements ServerPort {
   private baseUrl;
@@ -384,8 +585,8 @@ declare class FetchAdapter implements ServerPort {
 //#endregion
 //#region src/adapters/hono.adapter.d.ts
 /**
- * Server adapter for Hono — in-process requests, no real HTTP.
- * Used by integration() specification runner.
+ * Server adapter that dispatches requests in-process through a Hono app instance.
+ * Used by the `integration()` specification runner -- no network overhead.
  */
 declare class HonoAdapter implements ServerPort {
   private app;
@@ -395,158 +596,57 @@ declare class HonoAdapter implements ServerPort {
   request(method: string, path: string, body?: unknown): Promise<ServerResponse>;
 }
 //#endregion
-//#region src/adapters/postgres.adapter.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>;
+//#region src/runner/integration.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[];
 }
-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;
-  private client;
-  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>;
+/** A specification runner that also exposes teardown and the underlying orchestrator. */
+interface SpecificationRunnerWithCleanup extends SpecificationRunner {
+  /** Stop all infrastructure containers started by this runner. */
+  cleanup: () => Promise<void>;
+  /** The orchestrator managing the test infrastructure lifecycle. */
+  orchestrator: Orchestrator;
 }
 /**
- * Create a PostgreSQL service handle.
- *
- * @example
- * const db = postgres({ compose: "db" });
- * // After start: db.connectionString is populated
+ * Create an integration specification runner.
+ * Starts infra containers via testcontainers, app runs in-process.
  */
-declare function postgres(options?: PostgresOptions): PostgresHandle;
+declare function integration(options: IntegrationOptions): Promise<SpecificationRunnerWithCleanup>;
 //#endregion
-//#region src/adapters/redis.adapter.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>;
+//#region src/runner/cli.d.ts
+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[];
 }
 /**
- * Create a Redis service handle.
- *
- * @example
- * const cache = redis({ compose: "cache" });
- * // After start: cache.connectionString is populated
+ * Create a CLI specification runner.
+ * Runs CLI commands against fixture projects. Optionally starts infrastructure.
  */
-declare function redis(options?: RedisOptions): RedisHandle;
-//#endregion
-//#region src/docker/docker-port.d.ts
-interface DockerContainerPort {
-  /** Execute a command inside the container, return stdout */
-  exec(cmd: string[]): Promise<string>;
-  /** Read a file from inside the container */
-  file(path: string): Promise<{
-    exists: boolean;
-    content: string;
-  }>;
-  /** Check if container is running */
-  isRunning(): Promise<boolean>;
-  /** Get container logs */
-  logs(tail?: number): Promise<string>;
-  /** Get full docker inspect JSON */
-  inspect(): Promise<DockerInspectResult>;
-  /** Check if a file/directory exists */
-  exists(path: string): Promise<boolean>;
-}
-interface DockerInspectResult {
-  id: string;
-  name: string;
-  state: {
-    running: boolean;
-    exitCode: number;
-    status: string;
-  };
-  config: {
-    image: string;
-    env: string[];
-  };
-  hostConfig: {
-    memory: number;
-    cpuQuota: number;
-    networkMode: string;
-    mounts: Array<{
-      source: string;
-      destination: string;
-      type: string;
-    }>;
-  };
-  networkSettings: {
-    networks: Record<string, {
-      gateway: string;
-      ipAddress: string;
-    }>;
-  };
-}
-//#endregion
-//#region src/docker/docker-adapter.d.ts
-/** Create a Docker container port for an existing container */
-declare function dockerContainer(containerId: string): DockerContainerPort;
+declare function cli(options: CliOptions): Promise<SpecificationRunnerWithCleanup>;
 //#endregion
-//#region src/docker/docker-assertion.d.ts
-/** Fluent assertion builder for Docker containers */
-declare class DockerAssertion {
-  private container;
-  constructor(container: DockerContainerPort);
-  /** Assert the container is running */
-  toBeRunning(): Promise<this>;
-  /** Assert the container is NOT running / doesn't exist */
-  toNotExist(): Promise<this>;
-  /** Assert a file exists inside the container */
-  toHaveFile(path: string, opts?: {
-    containing?: string;
-  }): Promise<this>;
-  /** Assert a file does NOT exist */
-  toNotHaveFile(path: string): Promise<this>;
-  /** Assert a directory exists */
-  toHaveDirectory(path: string): Promise<this>;
-  /** Assert a mount exists */
-  toHaveMount(destination: string): Promise<this>;
-  /** Assert network mode */
-  toHaveNetwork(mode: string): Promise<this>;
-  /** Assert memory limit */
-  toHaveMemoryLimit(bytes: number): Promise<this>;
-  /** Assert CPU quota */
-  toHaveCpuQuota(quota: number): Promise<this>;
-  /** Execute a command and return output for custom assertions */
-  exec(cmd: string[]): Promise<string>;
-  /** Read a file for custom assertions */
-  readFile(path: string): Promise<string>;
-  /** Get logs for custom assertions */
-  getLogs(tail?: number): Promise<string>;
+//#region src/runner/e2e.d.ts
+interface E2eOptions {
+  /** Project root — must contain docker/compose.test.yaml. */
+  root?: string;
 }
+/**
+ * Create an E2E specification runner.
+ * Starts full docker compose stack. App URL and database auto-detected.
+ */
+declare function e2e(options?: E2eOptions): Promise<SpecificationRunnerWithCleanup>;
 //#endregion
 //#region src/utilities/grep.d.ts
 /**
@@ -561,19 +661,14 @@ declare class DockerAssertion {
 declare function grep(output: string, pattern: string): string;
 //#endregion
 //#region src/utilities/reporter.d.ts
+/** Strip ANSI escape codes from a string. */
 declare function stripAnsi(str: string): string;
+/** Strip ANSI codes and replace volatile tokens (ports, durations) with placeholders. */
 declare function normalizeOutput(str: string): string;
 //#endregion
-//#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;
+//#region src/docker/docker-adapter.d.ts
+/** Create a {@link DockerContainerPort} bound to an existing container by ID. */
+declare function dockerContainer(containerId: string): DockerContainerPort;
 //#endregion
-export { type CliOptions, type CommandEnv, type CommandPort, type CommandResult, type ContainerPort, type DatabasePort, DirectoryAccessor, type DirectorySnapshotOptions, DockerAssertion, type DockerContainerPort, type DockerInspectResult, type E2eOptions, ExecAdapter, FetchAdapter, type FileAccessor, HonoAdapter, type IntegrationOptions, type MockDatePort, type MockPort, Orchestrator, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServerPort, type ServerResponse, type ServiceHandle, type SpawnOptions, SpecificationBuilder, type SpecificationConfig, SpecificationResult, type SpecificationRunner, type SpecificationRunnerWithCleanup, TableAssertion, cli, createSpecificationRunner, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, stripAnsi };
+export { type AppTarget, type CliOptions, type CommandEnv, type CommandPort, type CommandResult, type CommandTarget, type ContainerPort, type DatabasePort, DirectoryAccessor, type DirectorySnapshotOptions, DockerAssertion, type DockerContainerPort, type DockerInspectResult, type E2eOptions, ExecAdapter, FetchAdapter, type FileAccessor, HonoAdapter, type HttpTarget, type IntegrationOptions, type IsolationStrategy, type MockDatePort, type MockPort, Orchestrator, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServerPort, type ServerResponse, type ServiceHandle, type SpawnOptions, type SpecOptions, type SpecRunner, type SpecTarget, SpecificationBuilder, type SpecificationConfig, SpecificationResult, type SpecificationRunner, type SpecificationRunnerWithCleanup, type StackTarget, TableAssertion, app, cli, command, createSpecificationRunner, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, spec, stack, stripAnsi };
 //# sourceMappingURL=index.d.ts.map