@jterrazz/test 4.0.1 → 5.1.0

package/dist/index.d.ts

@@ -110,99 +110,6 @@ declare class Orchestrator {
   getAppUrl(): null | string;
 }
 //#endregion
-//#region src/specification/assertions/base.d.ts
-/**
- * Base assertion that handles .not negation.
- * Subclasses call this.assert(condition, message, negatedMessage) for each predicate.
- */
-declare class BaseAssertion {
-  protected negated: boolean;
-  get not(): this;
-  protected assert(condition: boolean, message: string, negatedMessage: string): void;
-}
-//#endregion
-//#region src/specification/assertions/file.d.ts
-/**
- * Assertions on a file in the working directory.
- * Usage: result.file("dist/index.js").toExist()
- */
-declare class FileAssertion extends BaseAssertion {
-  private filePath;
-  private resolvedPath;
-  constructor(filePath: string, workDir: string);
-  toExist(): void;
-  toContain(expected: string): void;
-  toMatch(pattern: RegExp): void;
-}
-//#endregion
-//#region src/specification/assertions/response.d.ts
-/**
- * Assertions on an HTTP response body.
- * Usage: result.response.toMatchFile("expected.json")
- */
-declare class ResponseAssertion extends BaseAssertion {
-  private body;
-  private testDir;
-  constructor(body: unknown, testDir: string);
-  toMatchFile(file: string): void;
-  toContain(subset: Record<string, unknown>): void;
-}
-//#endregion
-//#region src/specification/assertions/string.d.ts
-/**
- * Assertions on a string (stdout, stderr, response body).
- * Usage: result.stdout.toContain("hello")
- */
-declare class StringAssertion extends BaseAssertion {
-  private actual;
-  private label;
-  private testDir?;
-  constructor(actual: string, label: string, testDir?: string);
-  toContain(expected: string, options?: {
-    near?: string;
-  }): void;
-  toMatch(pattern: RegExp): void;
-  toMatchFile(file: string): void;
-  toBeEmpty(): void;
-  private containsNear;
-  private stripAnsi;
-  private truncate;
-}
-//#endregion
-//#region src/specification/assertions/table.d.ts
-/**
- * Assertions on a database table.
- * Usage: await result.table("users").toMatch({ columns: ["name"], rows: [["Alice"]] })
- */
-declare class TableAssertion extends BaseAssertion {
-  private tableName;
-  private db;
-  constructor(tableName: string, db: DatabasePort);
-  toMatch(expected: {
-    columns: string[];
-    rows: unknown[][];
-  }): Promise<void>;
-  toBeEmpty(): Promise<void>;
-}
-//#endregion
-//#region src/specification/assertions/value.d.ts
-/**
- * Assertions on a single value (exit code, status code).
- * Usage: result.exitCode.toBe(0)
- */
-declare class ValueAssertion extends BaseAssertion {
-  private actual;
-  private label;
-  private context?;
-  constructor(actual: number, label: string, context?: {
-    request?: any;
-    responseBody?: unknown;
-    stdout?: string;
-    stderr?: string;
-  });
-  toBe(expected: number): void;
-}
-//#endregion
 //#region src/specification/ports/command.port.d.ts
 /**
  * Result of executing a CLI command.
@@ -221,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
@@ -258,10 +170,52 @@ interface SpecificationConfig {
   fixturesRoot?: string;
   server?: ServerPort;
 }
-interface RequestInfo {
-  body?: unknown;
-  method: string;
-  path: string;
+interface FileAccessor {
+  readonly content: string;
+  readonly exists: boolean;
+}
+declare class TableAssertion {
+  private tableName;
+  private db;
+  constructor(tableName: string, db: DatabasePort);
+  toMatch(expected: {
+    columns: string[];
+    rows: unknown[][];
+  }): 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;
+  constructor(body: unknown, testDir: string);
+  toMatchFile(file: string): void;
 }
 declare class SpecificationResult {
   private commandResult?;
@@ -273,17 +227,22 @@ declare class SpecificationResult {
   constructor(options: {
     commandResult?: CommandResult;
     config: SpecificationConfig;
-    requestInfo?: RequestInfo;
+    requestInfo?: {
+      body?: unknown;
+      method: string;
+      path: string;
+    };
     response?: ServerResponse;
     testDir: string;
     workDir?: string;
   });
-  get exitCode(): ValueAssertion;
-  get status(): ValueAssertion;
-  get response(): ResponseAssertion;
-  get stdout(): StringAssertion;
-  get stderr(): StringAssertion;
-  file(path: string): FileAssertion;
+  get exitCode(): number;
+  get status(): number;
+  get stdout(): string;
+  get stderr(): string;
+  get response(): ResponseAccessor;
+  directory(path?: string): DirectoryAccessor;
+  file(path: string): FileAccessor;
   table(tableName: string, options?: {
     service?: string;
   }): TableAssertion;
@@ -291,6 +250,7 @@ declare class SpecificationResult {
 }
 declare class SpecificationBuilder {
   private commandArgs;
+  private commandEnv;
   private config;
   private fixtures;
   private label;
@@ -307,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;
@@ -314,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;
@@ -396,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
@@ -424,6 +396,18 @@ declare class HonoAdapter implements ServerPort {
   request(method: string, path: string, body?: unknown): Promise<ServerResponse>;
 }
 //#endregion
+//#region src/specification/grep.d.ts
+/**
+ * Extract text blocks from output that contain a pattern.
+ * Splits by blank lines (how linter/compiler output is structured),
+ * returns only blocks matching the pattern.
+ *
+ * @example
+ * expect(grep(result.stdout, "unused-var.ts")).toContain("no-unused-vars")
+ * expect(grep(result.stdout, "valid/sorted.ts")).not.toContain("sort-imports")
+ */
+declare function grep(output: string, pattern: string): string;
+//#endregion
 //#region src/infrastructure/reporter.d.ts
 declare function stripAnsi(str: string): string;
 declare function normalizeOutput(str: string): string;
@@ -479,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, cli, e2e, 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