@jterrazz/test 5.0.0 → 5.2.0

package/dist/index.js

@@ -1,11 +1,12 @@
 import MockDatePackage from "mockdate";
 import { mockDeep } from "vitest-mock-extended";
-import { cpSync, existsSync, mkdtempSync, readFileSync } from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { execSync, spawn } from "node:child_process";
 import { parse } from "yaml";
 import { Client } from "pg";
 import { tmpdir } from "node:os";
+import { readdir } from "node:fs/promises";
 //#region src/mocking/mock-of-date.ts
 const mockOfDate = MockDatePackage;
 //#endregion
@@ -268,6 +269,47 @@ function formatResponseDiff(file, expected, actual) {
 	}
 	return lines.join("\n");
 }
+function formatDirectoryDiff(fixtureName, diff, hint) {
+	const lines = [];
+	const total = diff.added.length + diff.removed.length + diff.changed.length;
+	lines.push(`Directory mismatch: ${BOLD}${fixtureName}${RESET}`);
+	lines.push(`${DIM}  ${total} difference${total === 1 ? "" : "s"}: ${diff.added.length} added, ${diff.removed.length} removed, ${diff.changed.length} changed${RESET}`);
+	lines.push("");
+	lines.push(`${GREEN}- Expected (fixture)${RESET}`);
+	lines.push(`${RED}+ Received (generated)${RESET}`);
+	lines.push("");
+	for (const path of diff.added) lines.push(`${RED}+ added    ${path}${RESET}  ${DIM}(not in fixture)${RESET}`);
+	for (const path of diff.removed) lines.push(`${GREEN}- removed  ${path}${RESET}  ${DIM}(in fixture, not generated)${RESET}`);
+	for (const { path, expected, actual } of diff.changed) {
+		const expectedLines = expected.split("\n");
+		const actualLines = actual.split("\n");
+		const changedCount = countLineDifferences(expectedLines, actualLines);
+		lines.push(`${BOLD}~ changed  ${path}${RESET}  ${DIM}(${changedCount} line${changedCount === 1 ? "" : "s"} differ)${RESET}`);
+		let shown = 0;
+		const maxShown = 5;
+		const maxLines = Math.max(expectedLines.length, actualLines.length);
+		for (let i = 0; i < maxLines && shown < maxShown; i++) {
+			const exp = expectedLines[i];
+			const act = actualLines[i];
+			if (exp !== act) {
+				lines.push(`${DIM}    line ${i + 1}:${RESET}`);
+				if (exp !== void 0) lines.push(`    ${GREEN}- ${exp}${RESET}`);
+				if (act !== void 0) lines.push(`    ${RED}+ ${act}${RESET}`);
+				shown++;
+			}
+		}
+		if (changedCount > maxShown) lines.push(`    ${DIM}... ${changedCount - maxShown} more line(s)${RESET}`);
+	}
+	lines.push("");
+	lines.push(`${DIM}${hint}${RESET}`);
+	return lines.join("\n");
+}
+function countLineDifferences(expected, actual) {
+	let count = 0;
+	const max = Math.max(expected.length, actual.length);
+	for (let i = 0; i < max; i++) if (expected[i] !== actual[i]) count++;
+	return count;
+}
 function rowLabel(n) {
 	return n === 1 ? "1 row" : `${n} rows`;
 }
@@ -619,6 +661,19 @@ var Orchestrator = class {
 //#endregion
 //#region src/specification/adapters/exec.adapter.ts
 /**
+* Build a child-process env from the parent env plus user overrides.
+* `null` overrides delete keys (e.g. `INIT_CWD: null`).
+*/
+function buildEnv(extra) {
+	const env = {
+		...process.env,
+		INIT_CWD: void 0
+	};
+	if (extra) for (const [key, value] of Object.entries(extra)) if (value === null) delete env[key];
+	else env[key] = value;
+	return env;
+}
+/**
 * Executes CLI commands via execSync (blocking) or spawn (long-running).
 * Used by cli() for local command execution.
 */
@@ -627,11 +682,8 @@ var ExecAdapter = class {
 	constructor(command) {
 		this.command = command;
 	}
-	async exec(args, cwd) {
-		const env = {
-			...process.env,
-			INIT_CWD: void 0
-		};
+	async exec(args, cwd, extraEnv) {
+		const env = buildEnv(extraEnv);
 		try {
 			return {
 				exitCode: 0,
@@ -655,11 +707,8 @@ var ExecAdapter = class {
 			};
 		}
 	}
-	async spawn(args, cwd, options) {
-		const env = {
-			...process.env,
-			INIT_CWD: void 0
-		};
+	async spawn(args, cwd, options, extraEnv) {
+		const env = buildEnv(extraEnv);
 		return new Promise((resolve) => {
 			let stdout = "";
 			let stderr = "";
@@ -766,6 +815,75 @@ var HonoAdapter = class {
 	}
 };
 //#endregion
+//#region src/specification/directory.ts
+/**
+* Default ignore patterns — paths that should never appear in a tracked snapshot.
+* Each entry is matched against any path segment OR a path prefix.
+*/
+const DEFAULT_IGNORES = [
+	".git",
+	".DS_Store",
+	"node_modules",
+	".next",
+	"dist",
+	".turbo",
+	".cache"
+];
+/**
+* Recursively walk a directory, returning sorted relative paths of files only.
+* Ignored entries (default + caller-supplied) are skipped.
+*/
+async function walkDirectory(root, options = {}) {
+	const ignores = new Set([...DEFAULT_IGNORES, ...options.ignore ?? []]);
+	const out = [];
+	async function walk(current) {
+		let entries;
+		try {
+			entries = await readdir(current);
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (ignores.has(entry)) continue;
+			const abs = resolve(current, entry);
+			const stat = statSync(abs);
+			if (stat.isDirectory()) await walk(abs);
+			else if (stat.isFile()) out.push(relative(root, abs).split(sep).join("/"));
+		}
+	}
+	await walk(root);
+	out.sort();
+	return out;
+}
+/**
+* Compare two directory trees file-by-file.
+* Binary files are compared by byte equality but reported without inline diff.
+*/
+async function diffDirectories(expectedRoot, actualRoot, options = {}) {
+	const expectedFiles = await walkDirectory(expectedRoot, options);
+	const actualFiles = await walkDirectory(actualRoot, options);
+	const expectedSet = new Set(expectedFiles);
+	const actualSet = new Set(actualFiles);
+	const added = actualFiles.filter((f) => !expectedSet.has(f));
+	const removed = expectedFiles.filter((f) => !actualSet.has(f));
+	const changed = [];
+	for (const file of expectedFiles) {
+		if (!actualSet.has(file)) continue;
+		const expected = readFileSync(resolve(expectedRoot, file), "utf8");
+		const actual = readFileSync(resolve(actualRoot, file), "utf8");
+		if (expected !== actual) changed.push({
+			actual,
+			expected,
+			path: file
+		});
+	}
+	return {
+		added,
+		changed,
+		removed
+	};
+}
+//#endregion
 //#region src/specification/specification.ts
 var TableAssertion = class {
 	tableName;
@@ -783,6 +901,54 @@ var TableAssertion = class {
 		if (actual.length !== 0) throw new Error(`Expected table "${this.tableName}" to be empty, but it has ${actual.length} rows`);
 	}
 };
+/**
+* Detect whether the user wants to update snapshots — `true` for any of:
+*   - vitest run with `-u` / `--update`
+*   - JTERRAZZ_TEST_UPDATE=1
+*   - UPDATE_SNAPSHOTS=1
+*/
+function shouldUpdateSnapshots() {
+	if (process.env.JTERRAZZ_TEST_UPDATE === "1") return true;
+	if (process.env.UPDATE_SNAPSHOTS === "1") return true;
+	if (process.argv.includes("-u") || process.argv.includes("--update")) return true;
+	return false;
+}
+var DirectoryAccessor = class {
+	absPath;
+	testDir;
+	constructor(absPath, testDir) {
+		this.absPath = absPath;
+		this.testDir = testDir;
+	}
+	/**
+	* 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.
+	*/
+	async toMatchFixture(name, options = {}) {
+		const fixtureDir = resolve(this.testDir, "expected", name);
+		if (options.update ?? shouldUpdateSnapshots()) {
+			rmSync(fixtureDir, {
+				force: true,
+				recursive: true
+			});
+			mkdirSync(fixtureDir, { recursive: true });
+			cpSync(this.absPath, fixtureDir, { recursive: true });
+			return;
+		}
+		if (!existsSync(fixtureDir)) throw new Error(`Directory fixture "${name}" does not exist at ${fixtureDir}.\nRun with JTERRAZZ_TEST_UPDATE=1 (or vitest -u) to create it.`);
+		const diff = await diffDirectories(fixtureDir, this.absPath, { ignore: options.ignore });
+		if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) return;
+		throw new Error(formatDirectoryDiff(name, diff, "Run with JTERRAZZ_TEST_UPDATE=1 to update the fixture."));
+	}
+	/**
+	* List all files in the directory (recursive, sorted, ignoring defaults).
+	* Useful for ad-hoc assertions when you don't want a full snapshot.
+	*/
+	async files(options = {}) {
+		return walkDirectory(this.absPath, options);
+	}
+};
 var ResponseAccessor = class {
 	body;
 	testDir;
@@ -830,6 +996,9 @@ var SpecificationResult = class {
 		if (!this.responseData) throw new Error(".response requires an HTTP action (.get(), .post(), etc.)");
 		return new ResponseAccessor(this.responseData.body, this.testDir);
 	}
+	directory(path = ".") {
+		return new DirectoryAccessor(resolve(this.workDir ?? this.testDir, path), this.testDir);
+	}
 	file(path) {
 		const resolvedPath = resolve(this.workDir ?? this.testDir, path);
 		const exists = existsSync(resolvedPath);
@@ -853,6 +1022,7 @@ var SpecificationResult = class {
 };
 var SpecificationBuilder = class {
 	commandArgs = null;
+	commandEnv = {};
 	config;
 	fixtures = [];
 	label;
@@ -886,6 +1056,23 @@ var SpecificationBuilder = class {
 		this.mocks.push({ file });
 		return 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) {
+		this.commandEnv = {
+			...this.commandEnv,
+			...env
+		};
+		return this;
+	}
 	get(path) {
 		this.request = {
 			method: "GET",
@@ -951,8 +1138,17 @@ var SpecificationBuilder = class {
 		if (hasHttpAction) return this.runHttpAction();
 		return this.runCliAction(workDir);
 	}
+	resolveEnv(workDir) {
+		const keys = Object.keys(this.commandEnv);
+		if (keys.length === 0) return;
+		const resolved = {};
+		for (const key of keys) {
+			const value = this.commandEnv[key];
+			resolved[key] = typeof value === "string" ? value.replace(/\$WORKDIR/g, workDir) : value;
+		}
+		return resolved;
+	}
 	prepareWorkDir() {
-		if (!this.projectName && this.fixtures.length === 0) return this.config.fixturesRoot ?? process.cwd();
 		const tempDir = mkdtempSync(resolve(tmpdir(), "spec-cli-"));
 		if (this.projectName && this.config.fixturesRoot) {
 			const projectDir = resolve(this.config.fixturesRoot, this.projectName);
@@ -979,8 +1175,9 @@ var SpecificationBuilder = class {
 	}
 	async runCliAction(workDir) {
 		if (!this.config.command) throw new Error("CLI actions require a command adapter (use cli())");
+		const env = this.resolveEnv(workDir);
 		let commandResult;
-		if (this.spawnConfig) commandResult = await this.config.command.spawn(this.spawnConfig.args, workDir, this.spawnConfig.options);
+		if (this.spawnConfig) commandResult = await this.config.command.spawn(this.spawnConfig.args, workDir, this.spawnConfig.options, env);
 		else if (Array.isArray(this.commandArgs)) {
 			commandResult = {
 				exitCode: 0,
@@ -988,10 +1185,10 @@ var SpecificationBuilder = class {
 				stdout: ""
 			};
 			for (const args of this.commandArgs) {
-				commandResult = await this.config.command.exec(args, workDir);
+				commandResult = await this.config.command.exec(args, workDir, env);
 				if (commandResult.exitCode !== 0) break;
 			}
-		} else commandResult = await this.config.command.exec(this.commandArgs, workDir);
+		} else commandResult = await this.config.command.exec(this.commandArgs, workDir, env);
 		return new SpecificationResult({
 			commandResult,
 			config: this.config,
@@ -1152,6 +1349,176 @@ async function cli(options) {
 	return runner;
 }
 //#endregion
-export { ExecAdapter, FetchAdapter, HonoAdapter, Orchestrator, cli, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, stripAnsi };
+//#region src/infrastructure/docker/docker-adapter.ts
+var DockerAdapter = class {
+	containerId;
+	constructor(containerId) {
+		this.containerId = containerId;
+	}
+	async exec(cmd) {
+		return execSync(`docker exec ${this.containerId} ${cmd.map((c) => `'${c}'`).join(" ")}`, {
+			encoding: "utf8",
+			timeout: 1e4
+		}).trim();
+	}
+	async file(path) {
+		try {
+			return {
+				exists: true,
+				content: await this.exec(["cat", path])
+			};
+		} catch {
+			return {
+				exists: false,
+				content: ""
+			};
+		}
+	}
+	async isRunning() {
+		try {
+			return execSync(`docker inspect --format='{{.State.Running}}' ${this.containerId}`, {
+				encoding: "utf8",
+				timeout: 5e3
+			}).trim() === "true";
+		} catch {
+			return false;
+		}
+	}
+	async logs(tail) {
+		return execSync(`docker logs ${tail ? `--tail ${tail}` : ""} ${this.containerId}`, {
+			encoding: "utf8",
+			timeout: 1e4
+		});
+	}
+	async inspect() {
+		const raw = execSync(`docker inspect ${this.containerId}`, {
+			encoding: "utf8",
+			timeout: 5e3
+		});
+		const data = JSON.parse(raw)[0];
+		return {
+			id: data.Id,
+			name: data.Name,
+			state: {
+				running: data.State.Running,
+				exitCode: data.State.ExitCode,
+				status: data.State.Status
+			},
+			config: {
+				image: data.Config.Image,
+				env: data.Config.Env || []
+			},
+			hostConfig: {
+				memory: data.HostConfig.Memory || 0,
+				cpuQuota: data.HostConfig.CpuQuota || 0,
+				networkMode: data.HostConfig.NetworkMode || "",
+				mounts: (data.Mounts || []).map((m) => ({
+					source: m.Source,
+					destination: m.Destination,
+					type: m.Type
+				}))
+			},
+			networkSettings: { networks: Object.fromEntries(Object.entries(data.NetworkSettings.Networks || {}).map(([name, net]) => [name, {
+				gateway: net.Gateway,
+				ipAddress: net.IPAddress
+			}])) }
+		};
+	}
+	async exists(path) {
+		try {
+			await this.exec([
+				"test",
+				"-e",
+				path
+			]);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+/** Create a Docker container port for an existing container */
+function dockerContainer(containerId) {
+	return new DockerAdapter(containerId);
+}
+//#endregion
+//#region src/infrastructure/docker/docker-assertion.ts
+/** Fluent assertion builder for Docker containers */
+var DockerAssertion = class {
+	container;
+	constructor(container) {
+		this.container = container;
+	}
+	/** Assert the container is running */
+	async toBeRunning() {
+		if (!await this.container.isRunning()) throw new Error("Expected container to be running");
+		return this;
+	}
+	/** Assert the container is NOT running / doesn't exist */
+	async toNotExist() {
+		if (await this.container.isRunning()) throw new Error("Expected container to not exist or not be running");
+		return this;
+	}
+	/** Assert a file exists inside the container */
+	async toHaveFile(path, opts) {
+		const file = await this.container.file(path);
+		if (!file.exists) throw new Error(`Expected file ${path} to exist in container`);
+		if (opts?.containing && !file.content.includes(opts.containing)) throw new Error(`Expected file ${path} to contain "${opts.containing}", got: ${file.content.slice(0, 200)}`);
+		return this;
+	}
+	/** Assert a file does NOT exist */
+	async toNotHaveFile(path) {
+		if (await this.container.exists(path)) throw new Error(`Expected ${path} to not exist in container`);
+		return this;
+	}
+	/** Assert a directory exists */
+	async toHaveDirectory(path) {
+		if (!await this.container.exists(path)) throw new Error(`Expected directory ${path} to exist in container`);
+		return this;
+	}
+	/** Assert a mount exists */
+	async toHaveMount(destination) {
+		const info = await this.container.inspect();
+		if (!info.hostConfig.mounts.find((m) => m.destination === destination)) {
+			const available = info.hostConfig.mounts.map((m) => m.destination).join(", ");
+			throw new Error(`Expected mount at ${destination}, found: [${available}]`);
+		}
+		return this;
+	}
+	/** Assert network mode */
+	async toHaveNetwork(mode) {
+		const info = await this.container.inspect();
+		if (!info.hostConfig.networkMode.includes(mode)) throw new Error(`Expected network mode "${mode}", got "${info.hostConfig.networkMode}"`);
+		return this;
+	}
+	/** Assert memory limit */
+	async toHaveMemoryLimit(bytes) {
+		const info = await this.container.inspect();
+		if (info.hostConfig.memory !== bytes) throw new Error(`Expected memory limit ${bytes}, got ${info.hostConfig.memory}`);
+		return this;
+	}
+	/** Assert CPU quota */
+	async toHaveCpuQuota(quota) {
+		const info = await this.container.inspect();
+		if (info.hostConfig.cpuQuota !== quota) throw new Error(`Expected CPU quota ${quota}, got ${info.hostConfig.cpuQuota}`);
+		return this;
+	}
+	/** Execute a command and return output for custom assertions */
+	async exec(cmd) {
+		return this.container.exec(cmd);
+	}
+	/** Read a file for custom assertions */
+	async readFile(path) {
+		const file = await this.container.file(path);
+		if (!file.exists) throw new Error(`File ${path} does not exist`);
+		return file.content;
+	}
+	/** Get logs for custom assertions */
+	async getLogs(tail) {
+		return this.container.logs(tail);
+	}
+};
+//#endregion
+export { DockerAssertion, ExecAdapter, FetchAdapter, HonoAdapter, Orchestrator, cli, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, stripAnsi };
 
 //# sourceMappingURL=index.js.map