@jterrazz/test 5.3.1 → 6.0.0

package/dist/index.js

@@ -1,12 +1,11 @@
+import { n as postgres, t as redis } from "./redis.adapter.js";
+import { n as mockOfDate, t as mockOf } from "./mock-of.js";
 import { execSync, spawn } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { readdir } from "node:fs/promises";
-import { Client } from "pg";
 import { parse } from "yaml";
-import MockDatePackage from "mockdate";
-import { mockDeep } from "vitest-mock-extended";
 //#region src/adapters/exec.adapter.ts
 /**
 * Build a child-process env from the parent env plus user overrides.
@@ -22,8 +21,9 @@ function buildEnv(extra) {
 	return env;
 }
 /**
-* Executes CLI commands via execSync (blocking) or spawn (long-running).
-* Used by cli() for local command execution.
+* Executes CLI commands via Node.js child_process.
+* Uses `execSync` for one-shot commands and `spawn` for long-running processes.
+* Used by the `cli()` specification runner.
 */
 var ExecAdapter = class {
 	command;
@@ -103,6 +103,80 @@ var ExecAdapter = class {
 	}
 };
 //#endregion
+//#region src/adapters/fetch.adapter.ts
+/**
+* Server adapter that sends real HTTP requests via the Fetch API.
+* Used by the `e2e()` specification runner to hit a live server.
+*/
+var FetchAdapter = class {
+	baseUrl;
+	constructor(url) {
+		this.baseUrl = url.replace(/\/$/, "");
+	}
+	async request(method, path, body) {
+		const init = {
+			method,
+			headers: { "Content-Type": "application/json" }
+		};
+		if (body !== void 0) init.body = JSON.stringify(body);
+		const response = await fetch(`${this.baseUrl}${path}`, init);
+		const responseBody = await response.json().catch(() => null);
+		const headers = {};
+		response.headers.forEach((value, key) => {
+			headers[key] = value;
+		});
+		return {
+			status: response.status,
+			body: responseBody,
+			headers
+		};
+	}
+};
+//#endregion
+//#region src/adapters/hono.adapter.ts
+/**
+* Server adapter that dispatches requests in-process through a Hono app instance.
+* Used by the `integration()` specification runner -- no network overhead.
+*/
+var HonoAdapter = class {
+	app;
+	constructor(app) {
+		this.app = app;
+	}
+	async request(method, path, body) {
+		const init = {
+			method,
+			headers: { "Content-Type": "application/json" }
+		};
+		if (body !== void 0) init.body = JSON.stringify(body);
+		const response = await this.app.request(path, init);
+		const responseBody = await response.json().catch(() => null);
+		const headers = {};
+		response.headers.forEach((value, key) => {
+			headers[key] = value;
+		});
+		return {
+			status: response.status,
+			body: responseBody,
+			headers
+		};
+	}
+};
+//#endregion
+//#region src/utilities/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/utilities/directory.ts
 /**
 * Default ignore patterns — paths that should never appear in a tracked snapshot.
@@ -301,9 +375,11 @@ function rowLabel(n) {
 function formatRow(row) {
 	return row.map((v) => String(v ?? "null")).join("  |  ");
 }
+/** Strip ANSI escape codes from a string. */
 function stripAnsi(str) {
 	return str.replace(/\x1b\[[0-9;]*m/g, "");
 }
+/** Strip ANSI codes and replace volatile tokens (ports, durations) with placeholders. */
 function normalizeOutput(str) {
 	return stripAnsi(str).replace(/localhost:\d+/g, "localhost:PORT").replace(/\d+ms/g, "Xms").replace(/\d+\.\d+s/g, "X.Xs").trim();
 }
@@ -321,6 +397,10 @@ function shouldUpdateSnapshots() {
 	if (process.argv.includes("-u") || process.argv.includes("--update")) return true;
 	return false;
 }
+/**
+* Handle to a directory produced by a specification run.
+* Supports snapshot-based assertions via {@link toMatchFixture} and file listing via {@link files}.
+*/
 var DirectoryAccessor = class {
 	absPath;
 	testDir;
@@ -359,6 +439,7 @@ var DirectoryAccessor = class {
 };
 //#endregion
 //#region src/builder/response-accessor.ts
+/** Accessor for an HTTP response body with file-based assertion support. */
 var ResponseAccessor = class {
 	body;
 	testDir;
@@ -366,6 +447,12 @@ var ResponseAccessor = class {
 		this.body = body;
 		this.testDir = testDir;
 	}
+	/**
+	* Assert that the response body matches the JSON in `responses/{file}`.
+	*
+	* @example
+	*   result.response.toMatchFile("expected-items.json");
+	*/
 	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));
@@ -373,6 +460,7 @@ var ResponseAccessor = class {
 };
 //#endregion
 //#region src/builder/table-assertion.ts
+/** Assertion helper for verifying database table contents after a specification run. */
 var TableAssertion = class {
 	tableName;
 	db;
@@ -380,10 +468,20 @@ var TableAssertion = class {
 		this.tableName = tableName;
 		this.db = db;
 	}
+	/**
+	* Assert that the table contains exactly the expected rows for the given columns.
+	*
+	* @example
+	*   await result.table("users").toMatch({
+	*     columns: ["name", "email"],
+	*     rows: [["Alice", "alice@example.com"]],
+	*   });
+	*/
 	async toMatch(expected) {
 		const actual = await this.db.query(this.tableName, expected.columns);
 		if (JSON.stringify(actual) !== JSON.stringify(expected.rows)) throw new Error(formatTableDiff(this.tableName, expected.columns, expected.rows, actual));
 	}
+	/** Assert that the table has zero rows. */
 	async toBeEmpty() {
 		const actual = await this.db.query(this.tableName, ["*"]);
 		if (actual.length !== 0) throw new Error(`Expected table "${this.tableName}" to be empty, but it has ${actual.length} rows`);
@@ -391,6 +489,10 @@ var TableAssertion = class {
 };
 //#endregion
 //#region src/builder/specification-result.ts
+/**
+* The outcome of a single specification run.
+* Provides accessors for CLI output, HTTP responses, files, directories, and database tables.
+*/
 var SpecificationResult = class {
 	commandResult;
 	config;
@@ -406,29 +508,46 @@ var SpecificationResult = class {
 		this.requestInfo = options.requestInfo;
 		this.workDir = options.workDir;
 	}
+	/** The process exit code. Only available after a CLI action. */
 	get exitCode() {
 		if (!this.commandResult) throw new Error(".exitCode requires a CLI action (.exec())");
 		return this.commandResult.exitCode;
 	}
+	/** The HTTP response status code. Only available after an HTTP action. */
 	get status() {
 		if (!this.responseData) throw new Error(".status requires an HTTP action (.get(), .post(), etc.)");
 		return this.responseData.status;
 	}
+	/** The captured standard output. Only available after a CLI action. */
 	get stdout() {
 		if (!this.commandResult) throw new Error(".stdout requires a CLI action (.exec())");
 		return this.commandResult.stdout;
 	}
+	/** The captured standard error. Only available after a CLI action. */
 	get stderr() {
 		if (!this.commandResult) throw new Error(".stderr requires a CLI action (.exec())");
 		return this.commandResult.stderr;
 	}
+	/**
+	* Extract text blocks from stdout that contain a pattern.
+	* Useful for parsing structured CLI output (linters, compilers).
+	*
+	* @example
+	*   expect(result.grep('error.ts')).toContain('no-unused-vars');
+	*/
+	grep(pattern) {
+		return grep(this.stdout, pattern);
+	}
+	/** Access the HTTP response body for assertions. Only available after an HTTP action. */
 	get response() {
 		if (!this.responseData) throw new Error(".response requires an HTTP action (.get(), .post(), etc.)");
 		return new ResponseAccessor(this.responseData.body, this.testDir);
 	}
+	/** Access a directory (relative to the working directory) for snapshot assertions. */
 	directory(path = ".") {
 		return new DirectoryAccessor(resolve(this.workDir ?? this.testDir, path), this.testDir);
 	}
+	/** Access a single file (relative to the working directory) for content assertions. */
 	file(path) {
 		const resolvedPath = resolve(this.workDir ?? this.testDir, path);
 		const exists = existsSync(resolvedPath);
@@ -440,6 +559,7 @@ var SpecificationResult = class {
 			exists
 		};
 	}
+	/** Access a database table for row-level assertions. */
 	table(tableName, options) {
 		const db = this.resolveDatabase(options?.service);
 		if (!db) throw new Error(options?.service ? `table("${tableName}") requires database "${options.service}" but it was not found` : `table("${tableName}") requires a database adapter`);
@@ -452,6 +572,13 @@ var SpecificationResult = class {
 };
 //#endregion
 //#region src/builder/specification-builder.ts
+/**
+* Fluent builder for declaring a single test specification.
+*
+* Chain setup methods ({@link seed}, {@link fixture}, {@link env}), an action
+* ({@link get}, {@link post}, {@link exec}), then call {@link run} to execute
+* and receive a {@link SpecificationResult} for assertions.
+*/
 var SpecificationBuilder = class {
 	commandArgs = null;
 	commandEnv = {};
@@ -469,6 +596,12 @@ var SpecificationBuilder = class {
 		this.testDir = testDir;
 		this.label = label;
 	}
+	/**
+	* Queue a SQL seed file to run before the action.
+	*
+	* @example
+	*   spec("creates user").seed("users.sql").exec("list-users").run();
+	*/
 	seed(file, options) {
 		this.seeds.push({
 			file,
@@ -476,14 +609,17 @@ var SpecificationBuilder = class {
 		});
 		return this;
 	}
+	/** Copy a file or directory from `fixtures/` into the working directory before execution. */
 	fixture(file) {
 		this.fixtures.push({ file });
 		return this;
 	}
+	/** Copy an entire project fixture from `fixturesRoot` into the working directory. */
 	project(name) {
 		this.projectName = name;
 		return this;
 	}
+	/** Register an MSW mock definition file from `mock/` to intercept HTTP calls. */
 	mock(file) {
 		this.mocks.push({ file });
 		return this;
@@ -505,6 +641,12 @@ var SpecificationBuilder = class {
 		};
 		return this;
 	}
+	/**
+	* Send a GET request to the server adapter.
+	*
+	* @example
+	*   spec("list items").get("/api/items").run();
+	*/
 	get(path) {
 		this.request = {
 			method: "GET",
@@ -512,6 +654,13 @@ var SpecificationBuilder = class {
 		};
 		return this;
 	}
+	/**
+	* Send a POST request to the server adapter.
+	*
+	* @param bodyFile - Optional JSON file from `requests/` to use as the request body.
+	* @example
+	*   spec("create item").post("/api/items", "new-item.json").run();
+	*/
 	post(path, bodyFile) {
 		this.request = {
 			bodyFile,
@@ -520,6 +669,7 @@ var SpecificationBuilder = class {
 		};
 		return this;
 	}
+	/** Send a PUT request to the server adapter. */
 	put(path, bodyFile) {
 		this.request = {
 			bodyFile,
@@ -528,6 +678,7 @@ var SpecificationBuilder = class {
 		};
 		return this;
 	}
+	/** Send a DELETE request to the server adapter. */
 	delete(path) {
 		this.request = {
 			method: "DELETE",
@@ -535,10 +686,19 @@ var SpecificationBuilder = class {
 		};
 		return this;
 	}
+	/**
+	* Execute a CLI command (or a sequence of commands) in an isolated working directory.
+	* When an array is passed, commands run sequentially and stop on the first non-zero exit code.
+	*
+	* @example
+	*   spec("init project").exec("init --name demo").run();
+	*   spec("multi-step").exec(["init", "build"]).run();
+	*/
 	exec(args) {
 		this.commandArgs = args;
 		return this;
 	}
+	/** Spawn a long-running CLI process with custom spawn options (e.g. timeout, signal). */
 	spawn(args, options) {
 		this.spawnConfig = {
 			args,
@@ -546,6 +706,15 @@ var SpecificationBuilder = class {
 		};
 		return this;
 	}
+	/**
+	* Execute the specification: run seeds, copy fixtures, then perform the
+	* configured action (HTTP or CLI).
+	*
+	* @returns The result object used for assertions.
+	* @example
+	*   const result = await spec("test").exec("status").run();
+	*   expect(result.exitCode).toBe(0);
+	*/
 	async run() {
 		const hasHttpAction = this.request !== null;
 		const hasCliAction = this.commandArgs !== null || this.spawnConfig !== null;
@@ -639,207 +808,250 @@ function getCallerDir() {
 		const filePath = match[1];
 		if (filePath.includes("node_modules")) continue;
 		if (filePath.includes("/src/builder/") || filePath.includes("/src/runner/")) continue;
-		if (filePath.includes("/package-test/dist/") || filePath.includes("/package-test/src/")) continue;
 		return resolve(filePath, "..");
 	}
 	throw new Error("Cannot detect caller directory from stack trace");
 }
+/**
+* Create a {@link SpecificationRunner} bound to the given adapter configuration.
+* The test file directory is auto-detected from the call stack.
+*/
 function createSpecificationRunner(config) {
 	return (label) => {
 		return new SpecificationBuilder(config, getCallerDir(), label);
 	};
 }
 //#endregion
-//#region src/adapters/compose.adapter.ts
+//#region src/docker/docker-adapter.ts
 /**
-* Start the full compose stack and stop it all on cleanup.
+* Implements {@link DockerContainerPort} by shelling out to the Docker CLI.
+* Each instance is bound to a single container ID.
 */
-var ComposeStackAdapter = class {
-	composeFile;
-	started = false;
-	constructor(composeFile) {
-		this.composeFile = composeFile;
-	}
-	run(command) {
-		try {
-			return execSync(command, {
-				cwd: dirname(this.composeFile),
-				encoding: "utf8",
-				timeout: 12e4
-			}).trim();
-		} catch (error) {
-			const stderr = error.stderr?.toString().trim() ?? error.message;
-			throw new Error(`docker compose failed: ${stderr}`, { cause: error });
-		}
-	}
-	async start() {
-		if (this.started) return;
-		this.run(`docker compose -f ${this.composeFile} up -d --wait`);
-		this.started = true;
-	}
-	async stop() {
-		if (!this.started) return;
-		this.run(`docker compose -f ${this.composeFile} down -v`);
-		this.started = false;
-	}
-	getMappedPort(serviceName, containerPort) {
-		const port = this.run(`docker compose -f ${this.composeFile} port ${serviceName} ${containerPort}`).split(":").pop();
-		return Number(port);
-	}
-	getHost() {
-		return "localhost";
-	}
-};
-//#endregion
-//#region src/adapters/postgres.adapter.ts
-var PostgresHandle = class {
-	type = "postgres";
-	composeName;
-	defaultPort = 5432;
-	defaultImage;
-	environment;
-	connectionString = "";
-	started = false;
-	client = null;
-	constructor(options = {}) {
-		this.composeName = options.compose ?? null;
-		this.defaultImage = options.image ?? "postgres:17";
-		this.environment = {
-			POSTGRES_DB: "test",
-			POSTGRES_PASSWORD: "test",
-			POSTGRES_USER: "test",
-			...options.env
-		};
-	}
-	buildConnectionString(host, port) {
-		return `postgresql://${this.environment.POSTGRES_USER ?? "test"}:${this.environment.POSTGRES_PASSWORD ?? "test"}@${host}:${port}/${this.environment.POSTGRES_DB ?? "test"}`;
+var DockerAdapter = class {
+	containerId;
+	constructor(containerId) {
+		this.containerId = containerId;
 	}
-	createDatabaseAdapter() {
-		return this;
+	async exec(cmd) {
+		return execSync(`docker exec ${this.containerId} ${cmd.map((c) => `'${c}'`).join(" ")}`, {
+			encoding: "utf8",
+			timeout: 1e4
+		}).trim();
 	}
-	async healthcheck() {
-		if (!this.connectionString) throw new Error("postgres: cannot healthcheck — no connection string");
+	async file(path) {
 		try {
-			const client = new Client({ connectionString: this.connectionString });
-			await client.connect();
-			await client.query("SELECT 1");
-			await client.end();
-		} catch (error) {
-			throw new Error(`postgres healthcheck failed: ${error.message || error.code || String(error)}`, { cause: error });
+			return {
+				exists: true,
+				content: await this.exec(["cat", path])
+			};
+		} catch {
+			return {
+				exists: false,
+				content: ""
+			};
 		}
 	}
-	async initialize(composeDir) {
-		if (!this.composeName) return;
-		const initPaths = [resolve(composeDir, `${this.composeName}/init.sql`), resolve(composeDir, "postgres/init.sql")];
-		for (const initPath of initPaths) if (existsSync(initPath)) {
-			const sql = readFileSync(initPath, "utf8");
-			try {
-				await this.seed(sql);
-			} catch (error) {
-				throw new Error(`postgres init script failed (${initPath}):\n${error.message}`, { cause: error });
-			}
-			return;
+	async isRunning() {
+		try {
+			return execSync(`docker inspect --format='{{.State.Running}}' ${this.containerId}`, {
+				encoding: "utf8",
+				timeout: 5e3
+			}).trim() === "true";
+		} catch {
+			return false;
 		}
 	}
-	async getClient() {
-		if (this.client) return this.client;
-		const client = new Client({ connectionString: this.connectionString });
-		client.on("error", () => {
-			this.client = null;
+	async logs(tail) {
+		return execSync(`docker logs ${tail ? `--tail ${tail}` : ""} ${this.containerId}`, {
+			encoding: "utf8",
+			timeout: 1e4
 		});
-		await client.connect();
-		this.client = client;
-		return client;
-	}
-	async seed(sql) {
-		await (await this.getClient()).query(sql);
-	}
-	async query(table, columns) {
-		const client = await this.getClient();
-		const columnList = columns.join(", ");
-		return (await client.query(`SELECT ${columnList} FROM "${table}" ORDER BY 1`)).rows.map((row) => columns.map((col) => row[col]));
-	}
-	async reset() {
-		const client = await this.getClient();
-		const result = await client.query(`
-            SELECT tablename FROM pg_tables
-            WHERE schemaname = 'public'
-            AND tablename NOT LIKE '_prisma%'
-        `);
-		for (const row of result.rows) await client.query(`TRUNCATE "${row.tablename}" CASCADE`);
-	}
-};
-/**
-* Create a PostgreSQL service handle.
-*
-* @example
-* const db = postgres({ compose: "db" });
-* // After start: db.connectionString is populated
-*/
-function postgres(options = {}) {
-	return new PostgresHandle(options);
-}
-//#endregion
-//#region src/adapters/redis.adapter.ts
-var RedisHandle = class {
-	type = "redis";
-	composeName;
-	defaultPort = 6379;
-	defaultImage;
-	environment = {};
-	connectionString = "";
-	started = false;
-	constructor(options = {}) {
-		this.composeName = options.compose ?? null;
-		this.defaultImage = options.image ?? "redis:7";
-	}
-	buildConnectionString(host, port) {
-		return `redis://${host}:${port}`;
-	}
-	createDatabaseAdapter() {
-		return null;
 	}
-	async healthcheck() {
-		if (!this.connectionString) throw new Error("redis: cannot healthcheck — no connection string");
-		try {
-			const { createClient } = await import("redis");
-			const client = createClient({ url: this.connectionString });
-			await client.connect();
-			await client.ping();
-			await client.disconnect();
-		} catch (error) {
-			throw new Error(`redis healthcheck failed: ${error.message || error.code || String(error)}`, { cause: error });
-		}
+	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 initialize() {}
-	async reset() {
-		const { createClient } = await import("redis");
-		const client = createClient({ url: this.connectionString });
-		await client.connect();
+	async exists(path) {
 		try {
-			await client.flushAll();
-		} finally {
-			await client.disconnect();
+			await this.exec([
+				"test",
+				"-e",
+				path
+			]);
+			return true;
+		} catch {
+			return false;
 		}
 	}
 };
-/**
-* Create a Redis service handle.
-*
-* @example
-* const cache = redis({ compose: "cache" });
-* // After start: cache.connectionString is populated
-*/
-function redis(options = {}) {
-	return new RedisHandle(options);
+/** Create a {@link DockerContainerPort} bound to an existing container by ID. */
+function dockerContainer(containerId) {
+	return new DockerAdapter(containerId);
 }
 //#endregion
-//#region src/adapters/testcontainers.adapter.ts
+//#region src/docker/docker-assertion.ts
 /**
-* Container adapter using testcontainers.
-* Wraps a GenericContainer for programmatic container lifecycle.
+* Fluent assertion builder for Docker containers.
+* Chain async assertions like `toBeRunning()`, `toHaveFile()`, `toHaveMount()`.
 */
-var TestcontainersAdapter = class {
+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
+//#region src/adapters/compose.adapter.ts
+/**
+* Start the full compose stack and stop it all on cleanup.
+* Supports per-worker project names for parallel execution.
+*/
+var ComposeStackAdapter = class {
+	composeFile;
+	projectName;
+	started = false;
+	constructor(composeFile, projectName) {
+		this.composeFile = composeFile;
+		this.projectName = projectName ?? null;
+	}
+	get projectFlag() {
+		return this.projectName ? `-p ${this.projectName}` : "";
+	}
+	run(command) {
+		try {
+			return execSync(command, {
+				cwd: dirname(this.composeFile),
+				encoding: "utf8",
+				timeout: 12e4
+			}).trim();
+		} catch (error) {
+			const stderr = error.stderr?.toString().trim() ?? error.message;
+			throw new Error(`docker compose failed: ${stderr}`, { cause: error });
+		}
+	}
+	async start() {
+		if (this.started) return;
+		this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} up -d --wait`);
+		this.started = true;
+	}
+	async stop() {
+		if (!this.started) return;
+		this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} down -v`);
+		this.started = false;
+	}
+	getMappedPort(serviceName, containerPort) {
+		const port = this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} port ${serviceName} ${containerPort}`).split(":").pop();
+		return Number(port);
+	}
+	getHost() {
+		return "localhost";
+	}
+};
+//#endregion
+//#region src/adapters/testcontainers.adapter.ts
+/**
+* Container adapter using testcontainers.
+* Wraps a GenericContainer for programmatic container lifecycle.
+*/
+var TestcontainersAdapter = class {
 	image;
 	containerPort;
 	env;
@@ -977,6 +1189,7 @@ var Orchestrator = class {
 	services;
 	mode;
 	root;
+	projectName;
 	running = [];
 	composeStack = null;
 	composeHandles = [];
@@ -985,6 +1198,7 @@ var Orchestrator = class {
 		this.services = options.services;
 		this.mode = options.mode;
 		this.root = options.root ?? process.cwd();
+		this.projectName = options.projectName;
 	}
 	/**
 	* Start declared services via testcontainers (integration mode).
@@ -1082,7 +1296,7 @@ var Orchestrator = class {
 		const startTime = Date.now();
 		const composeDir = dirname(composePath);
 		const composeConfig = parseComposeFile(composePath);
-		this.composeStack = new ComposeStackAdapter(composePath);
+		this.composeStack = new ComposeStackAdapter(composePath, this.projectName);
 		await this.composeStack.start();
 		for (const service of composeConfig.infraServices) {
 			const type = detectServiceType(service.image);
@@ -1174,8 +1388,7 @@ function resolveProjectRoot(root) {
 			const match = line.match(/at\s+(?:.*?\()?(?:file:\/\/)?([^:)]+):\d+:\d+/);
 			if (!match) continue;
 			const filePath = match[1];
-			if (filePath.includes("node_modules")) continue;
-			if (filePath.includes("/src/runner/") || filePath.includes("/dist/")) continue;
+			if (filePath.includes("node_modules") || filePath.includes("/src/runner/")) continue;
 			return resolve(filePath, "..", root);
 		}
 	}
@@ -1193,6 +1406,169 @@ function resolveCommand(command, root) {
 	return command;
 }
 //#endregion
+//#region src/runner/spec.ts
+/**
+* Create a specification runner for the given target.
+*
+* @param target - What to test against: {@link app}, {@link stack}, or {@link command}.
+* @param options - Shared options: root directory, infrastructure services.
+*
+* @example
+*   // HTTP — in-process app with testcontainers
+*   const s = await spec(app(() => createApp(db)), { services: [db] });
+*
+*   // HTTP — full docker compose stack
+*   const s = await spec(stack('../../'));
+*
+*   // CLI — command binary
+*   const s = await spec(command('my-cli'), { root: '../fixtures' });
+*/
+async function spec(target, options = {}) {
+	switch (target.kind) {
+		case "app": return startApp(target, options);
+		case "stack": return startStack(target, options);
+		case "command": return startCommand(target, options);
+	}
+}
+function getWorkerId() {
+	return process.env.VITEST_POOL_ID ?? "0";
+}
+async function acquireIsolation(services) {
+	const workerId = getWorkerId();
+	for (const service of services) await service.isolation().acquire(workerId);
+}
+async function releaseIsolation(services) {
+	for (const service of services) await service.isolation().release();
+}
+async function startApp(target, options) {
+	const services = options.services ?? [];
+	const orchestrator = new Orchestrator({
+		mode: "integration",
+		root: resolveProjectRoot(options.root),
+		services
+	});
+	await orchestrator.start();
+	await acquireIsolation(services);
+	const honoApp = target.factory();
+	const database = orchestrator.getDatabase() ?? void 0;
+	const databases = orchestrator.getDatabases();
+	const runner = createSpecificationRunner({
+		database,
+		databases: databases.size > 0 ? databases : void 0,
+		server: new HonoAdapter(honoApp)
+	});
+	runner.cleanup = async () => {
+		await releaseIsolation(services);
+		await orchestrator.stop();
+	};
+	runner.docker = (id) => new DockerAssertion(dockerContainer(id));
+	runner.orchestrator = orchestrator;
+	return runner;
+}
+async function startStack(target, options) {
+	const root = resolveProjectRoot(target.root ?? options.root);
+	const projectName = `test-worker-${getWorkerId()}`;
+	const orchestrator = new Orchestrator({
+		mode: "e2e",
+		root,
+		services: options.services ?? [],
+		projectName
+	});
+	await orchestrator.startCompose();
+	const appUrl = orchestrator.getAppUrl();
+	if (!appUrl) throw new Error("stack(): could not detect app URL from compose. Ensure an app service with ports is defined.");
+	const database = orchestrator.getDatabase() ?? void 0;
+	const databases = orchestrator.getDatabases();
+	const runner = createSpecificationRunner({
+		database,
+		databases: databases.size > 0 ? databases : void 0,
+		server: new FetchAdapter(appUrl)
+	});
+	runner.cleanup = () => orchestrator.stopCompose();
+	runner.docker = (id) => new DockerAssertion(dockerContainer(id));
+	runner.orchestrator = orchestrator;
+	return runner;
+}
+async function startCommand(target, options) {
+	const root = resolveProjectRoot(options.root);
+	const bin = resolveCommand(target.bin, root);
+	const services = options.services ?? [];
+	let orchestrator = null;
+	let database;
+	let databases;
+	if (services.length) {
+		orchestrator = new Orchestrator({
+			mode: "integration",
+			root,
+			services
+		});
+		await orchestrator.start();
+		await acquireIsolation(services);
+		database = orchestrator.getDatabase() ?? void 0;
+		const dbMap = orchestrator.getDatabases();
+		databases = dbMap.size > 0 ? dbMap : void 0;
+	}
+	const runner = createSpecificationRunner({
+		command: new ExecAdapter(bin),
+		database,
+		databases,
+		fixturesRoot: root
+	});
+	runner.cleanup = async () => {
+		await releaseIsolation(services);
+		if (orchestrator) await orchestrator.stop();
+	};
+	runner.docker = (id) => new DockerAssertion(dockerContainer(id));
+	runner.orchestrator = orchestrator;
+	return runner;
+}
+//#endregion
+//#region src/runner/targets.ts
+/**
+* Test against an in-process Hono app. Services are started via testcontainers
+* and the app runs without network overhead.
+*
+* @param factory - Function that returns a Hono app instance (called after services start).
+*
+* @example
+*   await spec(app(() => createApp(db)), { services: [db] });
+*/
+function app(factory) {
+	return {
+		kind: "app",
+		factory
+	};
+}
+/**
+* Test against a full docker compose stack. The stack is started with
+* `docker compose up` and real HTTP requests are sent to the app service.
+*
+* @param root - Project root containing `docker/compose.test.yaml`.
+*
+* @example
+*   await spec(stack('../../'));
+*/
+function stack(root) {
+	return {
+		kind: "stack",
+		root
+	};
+}
+/**
+* Test a CLI binary. Each spec runs in a fresh temp directory.
+*
+* @param bin - Path to the CLI binary or command name (resolved from node_modules/.bin or PATH).
+*
+* @example
+*   await spec(command('my-cli'), { root: '../fixtures' });
+*/
+function command(bin) {
+	return {
+		kind: "command",
+		bin
+	};
+}
+//#endregion
 //#region src/runner/cli.ts
 /**
 * Create a CLI specification runner.
@@ -1228,36 +1604,6 @@ async function cli(options) {
 	return runner;
 }
 //#endregion
-//#region src/adapters/fetch.adapter.ts
-/**
-* Server adapter for real HTTP — sends actual fetch requests.
-* Used by e2e() specification runner.
-*/
-var FetchAdapter = class {
-	baseUrl;
-	constructor(url) {
-		this.baseUrl = url.replace(/\/$/, "");
-	}
-	async request(method, path, body) {
-		const init = {
-			method,
-			headers: { "Content-Type": "application/json" }
-		};
-		if (body !== void 0) init.body = JSON.stringify(body);
-		const response = await fetch(`${this.baseUrl}${path}`, init);
-		const responseBody = await response.json().catch(() => null);
-		const headers = {};
-		response.headers.forEach((value, key) => {
-			headers[key] = value;
-		});
-		return {
-			status: response.status,
-			body: responseBody,
-			headers
-		};
-	}
-};
-//#endregion
 //#region src/runner/e2e.ts
 /**
 * Create an E2E specification runner.
@@ -1284,36 +1630,6 @@ async function e2e(options = {}) {
 	return runner;
 }
 //#endregion
-//#region src/adapters/hono.adapter.ts
-/**
-* Server adapter for Hono — in-process requests, no real HTTP.
-* Used by integration() specification runner.
-*/
-var HonoAdapter = class {
-	app;
-	constructor(app) {
-		this.app = app;
-	}
-	async request(method, path, body) {
-		const init = {
-			method,
-			headers: { "Content-Type": "application/json" }
-		};
-		if (body !== void 0) init.body = JSON.stringify(body);
-		const response = await this.app.request(path, init);
-		const responseBody = await response.json().catch(() => null);
-		const headers = {};
-		response.headers.forEach((value, key) => {
-			headers[key] = value;
-		});
-		return {
-			status: response.status,
-			body: responseBody,
-			headers
-		};
-	}
-};
-//#endregion
 //#region src/runner/integration.ts
 /**
 * Create an integration specification runner.
@@ -1339,196 +1655,6 @@ async function integration(options) {
 	return runner;
 }
 //#endregion
-//#region src/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/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
-//#region src/utilities/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/mocking/mock-of-date.ts
-const mockOfDate = MockDatePackage;
-//#endregion
-//#region src/mocking/mock-of.ts
-const mockOf = mockDeep;
-//#endregion
-export { DirectoryAccessor, DockerAssertion, ExecAdapter, FetchAdapter, HonoAdapter, Orchestrator, ResponseAccessor, SpecificationBuilder, SpecificationResult, TableAssertion, cli, createSpecificationRunner, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, stripAnsi };
+export { DirectoryAccessor, DockerAssertion, ExecAdapter, FetchAdapter, HonoAdapter, Orchestrator, ResponseAccessor, SpecificationBuilder, SpecificationResult, TableAssertion, app, cli, command, createSpecificationRunner, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, spec, stack, stripAnsi };
 
 //# sourceMappingURL=index.js.map