@jterrazz/test 5.0.0 → 5.2.0

package/README.md

@@ -136,13 +136,13 @@ Every test follows the same pattern: `spec("label") → setup → action → ass
 
 ### Setup (cross-mode)
 
-| Method                                   | Description                                              |
-| ---------------------------------------- | -------------------------------------------------------- |
-| `.seed("file.sql")`                      | Load SQL from `seeds/file.sql` into the default database |
-| `.seed("file.sql", { service: "name" })` | Load SQL into a specific database                        |
-| `.fixture("file")`                       | Copy `fixtures/file` into the CLI working directory      |
-| `.project("name")`                       | Use `fixtures/name/` as the CLI working directory        |
-| `.mock("file.json")`                     | Register mocked external API response (MSW, planned)     |
+| Method                                   | Description                                               |
+| ---------------------------------------- | --------------------------------------------------------- |
+| `.seed("file.sql")`                      | Load SQL from `seeds/file.sql` into the default database  |
+| `.seed("file.sql", { service: "name" })` | Load SQL into a specific database                         |
+| `.fixture("file")`                       | Copy `fixtures/file` into the CLI working directory       |
+| `.project("name")`                       | Copy `fixtures/name/` into a fresh temp dir and run there |
+| `.mock("file.json")`                     | Register mocked external API response (MSW, planned)      |
 
 ### Actions (one per spec, mutually exclusive)
 
@@ -157,11 +157,14 @@ Every test follows the same pattern: `spec("label") → setup → action → ass
 
 **CLI:**
 
-| Method                                 | Description                                                 |
-| -------------------------------------- | ----------------------------------------------------------- |
-| `.exec("args")`                        | Run command (blocking)                                      |
-| `.exec(["build", "start"])`            | Run commands sequentially in same directory                 |
-| `.spawn("args", { waitFor, timeout })` | Run long-lived process, resolve on pattern match or timeout |
+| Method                                 | Description                                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------------------- |
+| `.exec("args")`                        | Run command (blocking)                                                                |
+| `.exec(["build", "start"])`            | Run commands sequentially in same directory                                           |
+| `.spawn("args", { waitFor, timeout })` | Run long-lived process, resolve on pattern match or timeout                           |
+| `.env({ KEY: "value" })`               | Set env vars on the child process (`null` unsets, `$WORKDIR` expands to the temp cwd) |
+
+Every CLI spec runs in a **fresh, empty temp directory** by default. `.project("name")` starts from a copy of `fixtures/name/`; `.fixture("file")` seeds specific files into the temp dir. Bare specs (`spec("x").exec("...")`) get an empty dir — ideal for testing scaffolding CLIs that write into their cwd.
 
 ### Assertions
 
@@ -184,6 +187,16 @@ Result properties are raw values — use vitest `expect()` for assertions. Datab
 | `expect(result.file("dist/index.js").content).toContain("Hello")` | Assert file contains string |
 | `expect(result.file("dist/index.cjs").exists).toBe(false)`        | Assert file does not exist  |
 
+**Directories (CLI scaffolding / codegen output):**
+
+| Expression                                                        | Description                                                                    |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `await result.directory("out").toMatchFixture("go-api")`          | Snapshot the tree against `expected/go-api/`, structured diff on mismatch      |
+| `await result.directory().toMatchFixture("scaffold", { ignore })` | Pass extra ignore patterns; defaults already skip `.git`, `node_modules`, etc. |
+| `await result.directory("out").files()`                           | List all files (recursive, sorted) for ad-hoc assertions                       |
+
+Run with `JTERRAZZ_TEST_UPDATE=1` (or vitest `-u`) to overwrite fixtures with the current output. Fixtures live at `{test}/expected/{name}/` — same convention as `responses/` for HTTP bodies.
+
 **Grep (scoped text matching):**
 
 ```typescript

package/dist/index.cjs

@@ -30,6 +30,7 @@ let node_child_process = require("node:child_process");
 let yaml = require("yaml");
 let pg = require("pg");
 let node_os = require("node:os");
+let node_fs_promises = require("node:fs/promises");
 //#region src/mocking/mock-of-date.ts
 const mockOfDate = mockdate.default;
 //#endregion
@@ -292,6 +293,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`;
 }
@@ -643,6 +685,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.
 */
@@ -651,11 +706,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,
@@ -679,11 +731,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 = "";
@@ -790,6 +839,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 (0, node_fs_promises.readdir)(current);
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (ignores.has(entry)) continue;
+			const abs = (0, node_path.resolve)(current, entry);
+			const stat = (0, node_fs.statSync)(abs);
+			if (stat.isDirectory()) await walk(abs);
+			else if (stat.isFile()) out.push((0, node_path.relative)(root, abs).split(node_path.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 = (0, node_fs.readFileSync)((0, node_path.resolve)(expectedRoot, file), "utf8");
+		const actual = (0, node_fs.readFileSync)((0, node_path.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;
@@ -807,6 +925,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 = (0, node_path.resolve)(this.testDir, "expected", name);
+		if (options.update ?? shouldUpdateSnapshots()) {
+			(0, node_fs.rmSync)(fixtureDir, {
+				force: true,
+				recursive: true
+			});
+			(0, node_fs.mkdirSync)(fixtureDir, { recursive: true });
+			(0, node_fs.cpSync)(this.absPath, fixtureDir, { recursive: true });
+			return;
+		}
+		if (!(0, node_fs.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;
@@ -854,6 +1020,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((0, node_path.resolve)(this.workDir ?? this.testDir, path), this.testDir);
+	}
 	file(path) {
 		const resolvedPath = (0, node_path.resolve)(this.workDir ?? this.testDir, path);
 		const exists = (0, node_fs.existsSync)(resolvedPath);
@@ -877,6 +1046,7 @@ var SpecificationResult = class {
 };
 var SpecificationBuilder = class {
 	commandArgs = null;
+	commandEnv = {};
 	config;
 	fixtures = [];
 	label;
@@ -910,6 +1080,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",
@@ -975,8 +1162,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 = (0, node_fs.mkdtempSync)((0, node_path.resolve)((0, node_os.tmpdir)(), "spec-cli-"));
 		if (this.projectName && this.config.fixturesRoot) {
 			const projectDir = (0, node_path.resolve)(this.config.fixturesRoot, this.projectName);
@@ -1003,8 +1199,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,
@@ -1012,10 +1209,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,
@@ -1176,11 +1373,183 @@ async function cli(options) {
 	return runner;
 }
 //#endregion
+//#region src/infrastructure/docker/docker-adapter.ts
+var DockerAdapter = class {
+	containerId;
+	constructor(containerId) {
+		this.containerId = containerId;
+	}
+	async exec(cmd) {
+		return (0, node_child_process.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 (0, node_child_process.execSync)(`docker inspect --format='{{.State.Running}}' ${this.containerId}`, {
+				encoding: "utf8",
+				timeout: 5e3
+			}).trim() === "true";
+		} catch {
+			return false;
+		}
+	}
+	async logs(tail) {
+		return (0, node_child_process.execSync)(`docker logs ${tail ? `--tail ${tail}` : ""} ${this.containerId}`, {
+			encoding: "utf8",
+			timeout: 1e4
+		});
+	}
+	async inspect() {
+		const raw = (0, node_child_process.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
+exports.DockerAssertion = DockerAssertion;
 exports.ExecAdapter = ExecAdapter;
 exports.FetchAdapter = FetchAdapter;
 exports.HonoAdapter = HonoAdapter;
 exports.Orchestrator = Orchestrator;
 exports.cli = cli;
+exports.dockerContainer = dockerContainer;
 exports.e2e = e2e;
 exports.grep = grep;
 exports.integration = integration;