@jterrazz/test 4.0.1 → 5.1.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
@@ -220,20 +221,6 @@ function formatStartupReport(mode, services, app) {
 	lines.push("");
 	return lines.join("\n");
 }
-function formatStatusError(expectedStatus, receivedStatus, request, responseBody) {
-	const lines = [];
-	lines.push(`Expected status: ${GREEN}${expectedStatus}${RESET}`);
-	lines.push(`Received status: ${RED}${receivedStatus}${RESET}`);
-	lines.push("");
-	lines.push(`${DIM}${request.method} ${request.path}${RESET}`);
-	if (request.body) lines.push(formatJson(request.body, DIM));
-	if (responseBody) {
-		lines.push("");
-		lines.push(`${DIM}Response:${RESET}`);
-		lines.push(formatJson(responseBody, RED));
-	}
-	return lines.join("\n");
-}
 function formatTableDiff(table, columns, expected, actual) {
 	const lines = [];
 	lines.push(`Table "${table}" mismatch`);
@@ -282,66 +269,50 @@ function formatResponseDiff(file, expected, actual) {
 	}
 	return lines.join("\n");
 }
-function formatExitCodeError(expected, received, stdout, stderr) {
+function formatDirectoryDiff(fixtureName, diff, hint) {
 	const lines = [];
-	lines.push(`Expected exit code: ${GREEN}${expected}${RESET}`);
-	lines.push(`Received exit code: ${RED}${received}${RESET}`);
-	if (stdout.trim()) {
-		lines.push("");
-		lines.push(`${DIM}stdout:${RESET}`);
-		for (const line of stdout.trim().split("\n").slice(-15)) lines.push(`  ${DIM}${line}${RESET}`);
-	}
-	if (stderr.trim()) {
-		lines.push("");
-		lines.push(`${DIM}stderr:${RESET}`);
-		for (const line of stderr.trim().split("\n").slice(-15)) lines.push(`  ${RED}${line}${RESET}`);
-	}
-	return lines.join("\n");
-}
-function formatStdoutDiff(file, expected, actual) {
-	const lines = [];
-	lines.push(`Output mismatch (${file})`);
+	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${RESET}`);
-	lines.push(`${RED}+ Received${RESET}`);
+	lines.push(`${GREEN}- Expected (fixture)${RESET}`);
+	lines.push(`${RED}+ Received (generated)${RESET}`);
 	lines.push("");
-	const expectedLines = expected.split("\n");
-	const actualLines = actual.split("\n");
-	const maxLines = Math.max(expectedLines.length, actualLines.length);
-	for (let i = 0; i < maxLines; i++) {
-		const exp = expectedLines[i];
-		const act = actualLines[i];
-		if (exp === act) lines.push(`  ${exp}`);
-		else {
-			if (exp !== void 0) lines.push(`${GREEN}- ${exp}${RESET}`);
-			if (act !== void 0) lines.push(`${RED}+ ${act}${RESET}`);
+	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}`);
 	}
-	return lines.join("\n");
-}
-function formatFileMissing(path) {
-	return `Expected file to exist: ${RED}${path}${RESET}`;
-}
-function formatFileUnexpected(path) {
-	return `Expected file NOT to exist: ${RED}${path}${RESET}`;
-}
-function formatFileContentMismatch(path, expected, actual) {
-	const lines = [];
-	lines.push(`File "${path}" does not contain expected content`);
 	lines.push("");
-	lines.push(`${GREEN}Expected to contain:${RESET}`);
-	lines.push(`  ${GREEN}${expected}${RESET}`);
-	lines.push("");
-	lines.push(`${RED}Actual content (first 20 lines):${RESET}`);
-	for (const line of actual.split("\n").slice(0, 20)) lines.push(`  ${DIM}${line}${RESET}`);
+	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`;
 }
-function formatJson(value, color) {
-	return JSON.stringify(value, null, 2).split("\n").map((line) => `${color}${line}${RESET}`).join("\n");
-}
 function formatRow(row) {
 	return row.map((v) => String(v ?? "null")).join("  |  ");
 }
@@ -690,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.
 */
@@ -698,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,
@@ -726,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 = "";
@@ -837,205 +815,152 @@ var HonoAdapter = class {
 	}
 };
 //#endregion
-//#region src/specification/assertions/base.ts
+//#region src/specification/directory.ts
 /**
-* Base assertion that handles .not negation.
-* Subclasses call this.assert(condition, message, negatedMessage) for each predicate.
+* Default ignore patterns — paths that should never appear in a tracked snapshot.
+* Each entry is matched against any path segment OR a path prefix.
 */
-var BaseAssertion = class {
-	negated = false;
-	get not() {
-		const clone = Object.create(Object.getPrototypeOf(this));
-		Object.assign(clone, this);
-		clone.negated = !this.negated;
-		return clone;
-	}
-	assert(condition, message, negatedMessage) {
-		if (this.negated) {
-			if (condition) throw new Error(negatedMessage);
-		} else if (!condition) throw new Error(message);
-	}
-};
-//#endregion
-//#region src/specification/assertions/file.ts
+const DEFAULT_IGNORES = [
+	".git",
+	".DS_Store",
+	"node_modules",
+	".next",
+	"dist",
+	".turbo",
+	".cache"
+];
 /**
-* Assertions on a file in the working directory.
-* Usage: result.file("dist/index.js").toExist()
+* Recursively walk a directory, returning sorted relative paths of files only.
+* Ignored entries (default + caller-supplied) are skipped.
 */
-var FileAssertion = class extends BaseAssertion {
-	filePath;
-	resolvedPath;
-	constructor(filePath, workDir) {
-		super();
-		this.filePath = filePath;
-		this.resolvedPath = resolve(workDir, filePath);
-	}
-	toExist() {
-		const exists = existsSync(this.resolvedPath);
-		this.assert(exists, formatFileMissing(this.filePath), formatFileUnexpected(this.filePath));
-	}
-	toContain(expected) {
-		if (!existsSync(this.resolvedPath)) {
-			if (this.negated) return;
-			throw new Error(formatFileMissing(this.filePath));
+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;
 		}
-		const content = readFileSync(this.resolvedPath, "utf8");
-		const found = content.includes(expected);
-		this.assert(found, formatFileContentMismatch(this.filePath, expected, content), `Expected file "${this.filePath}" NOT to contain "${expected}"`);
-	}
-	toMatch(pattern) {
-		if (!existsSync(this.resolvedPath)) {
-			if (this.negated) return;
-			throw new Error(formatFileMissing(this.filePath));
+		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("/"));
 		}
-		const content = readFileSync(this.resolvedPath, "utf8");
-		const found = pattern.test(content);
-		this.assert(found, `Expected file "${this.filePath}" to match: ${pattern}\n\nActual content:\n${content.slice(0, 500)}`, `Expected file "${this.filePath}" NOT to match: ${pattern}`);
-	}
-};
-//#endregion
-//#region src/specification/assertions/response.ts
-/**
-* Assertions on an HTTP response body.
-* Usage: result.response.toMatchFile("expected.json")
-*/
-var ResponseAssertion = class extends BaseAssertion {
-	body;
-	testDir;
-	constructor(body, testDir) {
-		super();
-		this.body = body;
-		this.testDir = testDir;
-	}
-	toMatchFile(file) {
-		const expected = JSON.parse(readFileSync(resolve(this.testDir, "responses", file), "utf8"));
-		const match = JSON.stringify(this.body) === JSON.stringify(expected);
-		this.assert(match, formatResponseDiff(file, expected, this.body), `Expected response NOT to match file "${file}", but it did`);
-	}
-	toContain(subset) {
-		const bodyStr = JSON.stringify(this.body);
-		const subsetStr = JSON.stringify(subset);
-		const bodyObj = typeof this.body === "object" && this.body !== null ? this.body : {};
-		const match = Object.entries(subset).every(([key, value]) => JSON.stringify(bodyObj[key]) === JSON.stringify(value));
-		this.assert(match, `Expected response to contain: ${subsetStr}\n\nActual response:\n${bodyStr}`, `Expected response NOT to contain: ${subsetStr}`);
 	}
-};
-//#endregion
-//#region src/specification/assertions/string.ts
+	await walk(root);
+	out.sort();
+	return out;
+}
 /**
-* Assertions on a string (stdout, stderr, response body).
-* Usage: result.stdout.toContain("hello")
+* Compare two directory trees file-by-file.
+* Binary files are compared by byte equality but reported without inline diff.
 */
-var StringAssertion = class extends BaseAssertion {
-	actual;
-	label;
-	testDir;
-	constructor(actual, label, testDir) {
-		super();
-		this.actual = actual;
-		this.label = label;
-		this.testDir = testDir;
-	}
-	toContain(expected, options) {
-		if (options?.near) {
-			const found = this.containsNear(expected, options.near);
-			this.assert(found, `Expected ${this.label} to contain "${expected}" near "${options.near}"\n\n${this.label}:\n${this.truncate(this.actual)}`, `Expected ${this.label} NOT to contain "${expected}" near "${options.near}", but it was found`);
-		} else {
-			const found = this.actual.includes(expected);
-			this.assert(found, `Expected ${this.label} to contain: "${expected}"\n\nActual ${this.label}:\n${this.truncate(this.actual)}`, `Expected ${this.label} NOT to contain: "${expected}"`);
-		}
-	}
-	toMatch(pattern) {
-		const found = pattern.test(this.actual);
-		this.assert(found, `Expected ${this.label} to match: ${pattern}\n\nActual ${this.label}:\n${this.truncate(this.actual)}`, `Expected ${this.label} NOT to match: ${pattern}`);
-	}
-	toMatchFile(file) {
-		if (!this.testDir) throw new Error("toMatchFile requires a test directory context");
-		const expected = readFileSync(resolve(this.testDir, "expected", file), "utf8").trim();
-		const actual = this.actual.trim();
-		const match = actual === expected;
-		this.assert(match, formatStdoutDiff(file, expected, actual), `Expected ${this.label} NOT to match file "${file}", but it did`);
-	}
-	toBeEmpty() {
-		const empty = this.actual.trim() === "";
-		this.assert(empty, `Expected ${this.label} to be empty\n\nActual ${this.label}:\n${this.truncate(this.actual)}`, `Expected ${this.label} NOT to be empty`);
-	}
-	containsNear(target, near, proximity = 500) {
-		const clean = this.stripAnsi(this.actual);
-		const nearLower = near.toLowerCase();
-		const targetLower = target.toLowerCase();
-		let searchFrom = 0;
-		while (true) {
-			const idx = clean.toLowerCase().indexOf(nearLower, searchFrom);
-			if (idx === -1) break;
-			const windowStart = Math.max(0, idx - proximity);
-			const windowEnd = Math.min(clean.length, idx + nearLower.length + proximity);
-			if (clean.substring(windowStart, windowEnd).toLowerCase().includes(targetLower)) return true;
-			searchFrom = idx + 1;
-		}
-		return false;
-	}
-	stripAnsi(str) {
-		return str.replace(/\x1b\[[0-9;]*m/g, "");
-	}
-	truncate(str, maxLines = 20) {
-		const lines = str.split("\n");
-		if (lines.length <= maxLines) return str;
-		return `${lines.slice(0, maxLines).join("\n")}\n... (${lines.length - maxLines} more lines)`;
+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/assertions/table.ts
-/**
-* Assertions on a database table.
-* Usage: await result.table("users").toMatch({ columns: ["name"], rows: [["Alice"]] })
-*/
-var TableAssertion = class extends BaseAssertion {
+//#region src/specification/specification.ts
+var TableAssertion = class {
 	tableName;
 	db;
 	constructor(tableName, db) {
-		super();
 		this.tableName = tableName;
 		this.db = db;
 	}
 	async toMatch(expected) {
 		const actual = await this.db.query(this.tableName, expected.columns);
-		const match = JSON.stringify(actual) === JSON.stringify(expected.rows);
-		this.assert(match, formatTableDiff(this.tableName, expected.columns, expected.rows, actual), `Expected table "${this.tableName}" NOT to match, but it did`);
+		if (JSON.stringify(actual) !== JSON.stringify(expected.rows)) throw new Error(formatTableDiff(this.tableName, expected.columns, expected.rows, actual));
 	}
 	async toBeEmpty() {
 		const actual = await this.db.query(this.tableName, ["*"]);
-		const empty = actual.length === 0;
-		this.assert(empty, `Expected table "${this.tableName}" to be empty, but it has ${actual.length} rows`, `Expected table "${this.tableName}" NOT to be empty, but it is`);
+		if (actual.length !== 0) throw new Error(`Expected table "${this.tableName}" to be empty, but it has ${actual.length} rows`);
 	}
 };
-//#endregion
-//#region src/specification/assertions/value.ts
 /**
-* Assertions on a single value (exit code, status code).
-* Usage: result.exitCode.toBe(0)
+* Detect whether the user wants to update snapshots — `true` for any of:
+*   - vitest run with `-u` / `--update`
+*   - JTERRAZZ_TEST_UPDATE=1
+*   - UPDATE_SNAPSHOTS=1
 */
-var ValueAssertion = class extends BaseAssertion {
-	actual;
-	label;
-	context;
-	constructor(actual, label, context) {
-		super();
-		this.actual = actual;
-		this.label = label;
-		this.context = context;
+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."));
 	}
-	toBe(expected) {
-		const match = this.actual === expected;
-		let message;
-		if (this.label === "exit code" && this.context?.stdout !== void 0) message = formatExitCodeError(expected, this.actual, this.context.stdout ?? "", this.context.stderr ?? "");
-		else if (this.label === "status" && this.context?.request) message = formatStatusError(expected, this.actual, this.context.request, this.context.responseBody);
-		else message = `Expected ${this.label}: ${expected}\nReceived ${this.label}: ${this.actual}`;
-		this.assert(match, message, `Expected ${this.label} NOT to be ${expected}, but it was`);
+	/**
+	* 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;
+	constructor(body, testDir) {
+		this.body = body;
+		this.testDir = testDir;
+	}
+	toMatchFile(file) {
+		const expected = JSON.parse(readFileSync(resolve(this.testDir, "responses", file), "utf8"));
+		if (JSON.stringify(this.body) !== JSON.stringify(expected)) throw new Error(formatResponseDiff(file, expected, this.body));
 	}
 };
-//#endregion
-//#region src/specification/specification.ts
 var SpecificationResult = class {
 	commandResult;
 	config;
@@ -1053,32 +978,37 @@ var SpecificationResult = class {
 	}
 	get exitCode() {
 		if (!this.commandResult) throw new Error(".exitCode requires a CLI action (.exec())");
-		return new ValueAssertion(this.commandResult.exitCode, "exit code", {
-			stderr: this.commandResult.stderr,
-			stdout: this.commandResult.stdout
-		});
+		return this.commandResult.exitCode;
 	}
 	get status() {
-		if (!this.responseData || !this.requestInfo) throw new Error(".status requires an HTTP action (.get(), .post(), etc.)");
-		return new ValueAssertion(this.responseData.status, "status", {
-			request: this.requestInfo,
-			responseBody: this.responseData.body
-		});
-	}
-	get response() {
-		if (!this.responseData) throw new Error(".response requires an HTTP action (.get(), .post(), etc.)");
-		return new ResponseAssertion(this.responseData.body, this.testDir);
+		if (!this.responseData) throw new Error(".status requires an HTTP action (.get(), .post(), etc.)");
+		return this.responseData.status;
 	}
 	get stdout() {
 		if (!this.commandResult) throw new Error(".stdout requires a CLI action (.exec())");
-		return new StringAssertion(this.commandResult.stdout, "stdout", this.testDir);
+		return this.commandResult.stdout;
 	}
 	get stderr() {
 		if (!this.commandResult) throw new Error(".stderr requires a CLI action (.exec())");
-		return new StringAssertion(this.commandResult.stderr, "stderr", this.testDir);
+		return this.commandResult.stderr;
+	}
+	get response() {
+		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) {
-		return new FileAssertion(path, this.workDir ?? this.testDir);
+		const resolvedPath = resolve(this.workDir ?? this.testDir, path);
+		const exists = existsSync(resolvedPath);
+		return {
+			get content() {
+				if (!exists) throw new Error(`File not found: ${path}`);
+				return readFileSync(resolvedPath, "utf8");
+			},
+			exists
+		};
 	}
 	table(tableName, options) {
 		const db = this.resolveDatabase(options?.service);
@@ -1092,6 +1022,7 @@ var SpecificationResult = class {
 };
 var SpecificationBuilder = class {
 	commandArgs = null;
+	commandEnv = {};
 	config;
 	fixtures = [];
 	label;
@@ -1125,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",
@@ -1190,6 +1138,16 @@ 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-"));
@@ -1218,19 +1176,20 @@ 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,
-				stdout: "",
-				stderr: ""
+				stderr: "",
+				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,
@@ -1253,16 +1212,26 @@ function getCallerDir() {
 	}
 	throw new Error("Cannot detect caller directory from stack trace");
 }
-/**
-* Create a specification runner.
-* Automatically detects the test directory from the call site.
-*/
 function createSpecificationRunner(config) {
 	return (label) => {
 		return new SpecificationBuilder(config, getCallerDir(), label);
 	};
 }
 //#endregion
+//#region src/specification/grep.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")
+*/
+function grep(output, pattern) {
+	return output.replace(/\x1b\[[0-9;]*m/g, "").split(/\n\s*\n/).filter((block) => block.includes(pattern)).join("\n\n");
+}
+//#endregion
 //#region src/specification/index.ts
 /**
 * Resolve root — if relative, resolves from the caller's directory.
@@ -1381,6 +1350,176 @@ async function cli(options) {
 	return runner;
 }
 //#endregion
-export { ExecAdapter, FetchAdapter, HonoAdapter, Orchestrator, cli, e2e, 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