@jterrazz/test 5.0.0 → 5.2.0

package/dist/index.d.cts

@@ -128,15 +128,20 @@ interface SpawnOptions {
   /** Kill the process after this many milliseconds. */
   timeout: number;
 }
+/**
+ * Extra environment variables to set for the child process.
+ * Values are merged on top of process.env. A `null` value unsets the variable.
+ */
+type CommandEnv = Record<string, null | 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>;
+  exec(args: string, cwd: string, env?: CommandEnv): Promise<CommandResult>;
   /** Spawn a long-running process and wait for a pattern or timeout. */
-  spawn(args: string, cwd: string, options: SpawnOptions): Promise<CommandResult>;
+  spawn(args: string, cwd: string, options: SpawnOptions, env?: CommandEnv): Promise<CommandResult>;
 }
 //#endregion
 //#region src/specification/ports/server.port.d.ts
@@ -179,6 +184,33 @@ declare class TableAssertion {
   }): Promise<void>;
   toBeEmpty(): Promise<void>;
 }
+interface DirectorySnapshotOptions {
+  /** Extra path segments to ignore (in addition to default: .git, node_modules, etc.). */
+  ignore?: string[];
+  /**
+   * Force update mode regardless of vitest flags / env vars.
+   * `true` writes the fixture, `false` always asserts. Defaults to auto-detect.
+   */
+  update?: boolean;
+}
+declare class DirectoryAccessor {
+  private absPath;
+  private testDir;
+  constructor(absPath: string, testDir: string);
+  /**
+   * Compare the directory tree against `expected/{name}/` (relative to the test file).
+   * On mismatch, throws with a structured diff. With update mode enabled, the
+   * fixture is overwritten with the current contents instead.
+   */
+  toMatchFixture(name: string, options?: DirectorySnapshotOptions): Promise<void>;
+  /**
+   * List all files in the directory (recursive, sorted, ignoring defaults).
+   * Useful for ad-hoc assertions when you don't want a full snapshot.
+   */
+  files(options?: {
+    ignore?: string[];
+  }): Promise<string[]>;
+}
 declare class ResponseAccessor {
   readonly body: unknown;
   private testDir;
@@ -209,6 +241,7 @@ declare class SpecificationResult {
   get stdout(): string;
   get stderr(): string;
   get response(): ResponseAccessor;
+  directory(path?: string): DirectoryAccessor;
   file(path: string): FileAccessor;
   table(tableName: string, options?: {
     service?: string;
@@ -217,6 +250,7 @@ declare class SpecificationResult {
 }
 declare class SpecificationBuilder {
   private commandArgs;
+  private commandEnv;
   private config;
   private fixtures;
   private label;
@@ -233,6 +267,17 @@ declare class SpecificationBuilder {
   fixture(file: string): this;
   project(name: string): this;
   mock(file: string): this;
+  /**
+   * Set environment variables for the CLI process. Merged on top of process.env.
+   * Use `null` to unset a variable. Multiple calls merge.
+   *
+   * The token `$WORKDIR` (in any value) is replaced with the actual working
+   * directory at run-time — useful for tests that need a fully isolated `HOME`.
+   *
+   * @example
+   *   spec("...").env({ HOME: "$WORKDIR", TZ: "UTC" }).exec("status").run();
+   */
+  env(env: CommandEnv): this;
   get(path: string): this;
   post(path: string, bodyFile?: string): this;
   put(path: string, bodyFile?: string): this;
@@ -240,6 +285,7 @@ declare class SpecificationBuilder {
   exec(args: string | string[]): this;
   spawn(args: string, options: SpawnOptions): this;
   run(): Promise<SpecificationResult>;
+  private resolveEnv;
   private prepareWorkDir;
   private runHttpAction;
   private runCliAction;
@@ -322,8 +368,8 @@ declare function redis(options?: RedisOptions): RedisHandle;
 declare class ExecAdapter implements CommandPort {
   private command;
   constructor(command: string);
-  exec(args: string, cwd: string): Promise<CommandResult>;
-  spawn(args: string, cwd: string, options: SpawnOptions): Promise<CommandResult>;
+  exec(args: string, cwd: string, extraEnv?: CommandEnv): Promise<CommandResult>;
+  spawn(args: string, cwd: string, options: SpawnOptions, extraEnv?: CommandEnv): Promise<CommandResult>;
 }
 //#endregion
 //#region src/specification/adapters/fetch.adapter.d.ts
@@ -417,5 +463,90 @@ declare function e2e(options?: E2eOptions): Promise<SpecificationRunnerWithClean
  */
 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, type SpecificationResult, cli, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, stripAnsi };
+//#region src/infrastructure/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/infrastructure/docker/docker-adapter.d.ts
+/** Create a Docker container port for an existing container */
+declare function dockerContainer(containerId: string): DockerContainerPort;
+//#endregion
+//#region src/infrastructure/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>;
+}
+//#endregion
+export { type CommandEnv, type CommandPort, type CommandResult, type DatabasePort, type DirectoryAccessor, type DirectorySnapshotOptions, DockerAssertion, type DockerContainerPort, type DockerInspectResult, ExecAdapter, FetchAdapter, HonoAdapter, type MockDatePort, type MockPort, Orchestrator, type ServerPort, type ServerResponse, type SpecificationResult, cli, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, stripAnsi };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -128,15 +128,20 @@ interface SpawnOptions {
   /** Kill the process after this many milliseconds. */
   timeout: number;
 }
+/**
+ * Extra environment variables to set for the child process.
+ * Values are merged on top of process.env. A `null` value unsets the variable.
+ */
+type CommandEnv = Record<string, null | 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>;
+  exec(args: string, cwd: string, env?: CommandEnv): Promise<CommandResult>;
   /** Spawn a long-running process and wait for a pattern or timeout. */
-  spawn(args: string, cwd: string, options: SpawnOptions): Promise<CommandResult>;
+  spawn(args: string, cwd: string, options: SpawnOptions, env?: CommandEnv): Promise<CommandResult>;
 }
 //#endregion
 //#region src/specification/ports/server.port.d.ts
@@ -179,6 +184,33 @@ declare class TableAssertion {
   }): Promise<void>;
   toBeEmpty(): Promise<void>;
 }
+interface DirectorySnapshotOptions {
+  /** Extra path segments to ignore (in addition to default: .git, node_modules, etc.). */
+  ignore?: string[];
+  /**
+   * Force update mode regardless of vitest flags / env vars.
+   * `true` writes the fixture, `false` always asserts. Defaults to auto-detect.
+   */
+  update?: boolean;
+}
+declare class DirectoryAccessor {
+  private absPath;
+  private testDir;
+  constructor(absPath: string, testDir: string);
+  /**
+   * Compare the directory tree against `expected/{name}/` (relative to the test file).
+   * On mismatch, throws with a structured diff. With update mode enabled, the
+   * fixture is overwritten with the current contents instead.
+   */
+  toMatchFixture(name: string, options?: DirectorySnapshotOptions): Promise<void>;
+  /**
+   * List all files in the directory (recursive, sorted, ignoring defaults).
+   * Useful for ad-hoc assertions when you don't want a full snapshot.
+   */
+  files(options?: {
+    ignore?: string[];
+  }): Promise<string[]>;
+}
 declare class ResponseAccessor {
   readonly body: unknown;
   private testDir;
@@ -209,6 +241,7 @@ declare class SpecificationResult {
   get stdout(): string;
   get stderr(): string;
   get response(): ResponseAccessor;
+  directory(path?: string): DirectoryAccessor;
   file(path: string): FileAccessor;
   table(tableName: string, options?: {
     service?: string;
@@ -217,6 +250,7 @@ declare class SpecificationResult {
 }
 declare class SpecificationBuilder {
   private commandArgs;
+  private commandEnv;
   private config;
   private fixtures;
   private label;
@@ -233,6 +267,17 @@ declare class SpecificationBuilder {
   fixture(file: string): this;
   project(name: string): this;
   mock(file: string): this;
+  /**
+   * Set environment variables for the CLI process. Merged on top of process.env.
+   * Use `null` to unset a variable. Multiple calls merge.
+   *
+   * The token `$WORKDIR` (in any value) is replaced with the actual working
+   * directory at run-time — useful for tests that need a fully isolated `HOME`.
+   *
+   * @example
+   *   spec("...").env({ HOME: "$WORKDIR", TZ: "UTC" }).exec("status").run();
+   */
+  env(env: CommandEnv): this;
   get(path: string): this;
   post(path: string, bodyFile?: string): this;
   put(path: string, bodyFile?: string): this;
@@ -240,6 +285,7 @@ declare class SpecificationBuilder {
   exec(args: string | string[]): this;
   spawn(args: string, options: SpawnOptions): this;
   run(): Promise<SpecificationResult>;
+  private resolveEnv;
   private prepareWorkDir;
   private runHttpAction;
   private runCliAction;
@@ -322,8 +368,8 @@ declare function redis(options?: RedisOptions): RedisHandle;
 declare class ExecAdapter implements CommandPort {
   private command;
   constructor(command: string);
-  exec(args: string, cwd: string): Promise<CommandResult>;
-  spawn(args: string, cwd: string, options: SpawnOptions): Promise<CommandResult>;
+  exec(args: string, cwd: string, extraEnv?: CommandEnv): Promise<CommandResult>;
+  spawn(args: string, cwd: string, options: SpawnOptions, extraEnv?: CommandEnv): Promise<CommandResult>;
 }
 //#endregion
 //#region src/specification/adapters/fetch.adapter.d.ts
@@ -417,5 +463,90 @@ declare function e2e(options?: E2eOptions): Promise<SpecificationRunnerWithClean
  */
 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, type SpecificationResult, cli, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, stripAnsi };
+//#region src/infrastructure/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/infrastructure/docker/docker-adapter.d.ts
+/** Create a Docker container port for an existing container */
+declare function dockerContainer(containerId: string): DockerContainerPort;
+//#endregion
+//#region src/infrastructure/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>;
+}
+//#endregion
+export { type CommandEnv, type CommandPort, type CommandResult, type DatabasePort, type DirectoryAccessor, type DirectorySnapshotOptions, DockerAssertion, type DockerContainerPort, type DockerInspectResult, ExecAdapter, FetchAdapter, HonoAdapter, type MockDatePort, type MockPort, Orchestrator, type ServerPort, type ServerResponse, type SpecificationResult, cli, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, stripAnsi };
 //# sourceMappingURL=index.d.ts.map