@jterrazz/test 4.0.0 → 5.0.0

package/README.md

@@ -39,7 +39,7 @@ test("creates a user", async () => {
     .run();
 
   // Then — user created
-  result.status.toBe(201);
+  expect(result.status).toBe(201);
   await result.table("users").toMatch({
     columns: ["name"],
     rows: [["Alice"], ["Bob"]],
@@ -69,11 +69,11 @@ test("builds the project", async () => {
   const result = await spec("build").project("sample-app").exec("build").run();
 
   // Then — ESM output with source maps
-  result.exitCode.toBe(0);
-  result.stdout.toContain("Build completed");
-  result.file("dist/index.js").toExist();
-  result.file("dist/index.cjs").not.toExist();
-  result.file("dist/index.js").toContain("Hello");
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("Build completed");
+  expect(result.file("dist/index.js").exists).toBe(true);
+  expect(result.file("dist/index.cjs").exists).toBe(false);
+  expect(result.file("dist/index.js").content).toContain("Hello");
 });
 ```
 
@@ -165,42 +165,50 @@ Every test follows the same pattern: `spec("label") → setup → action → ass
 
 ### Assertions
 
-Assertions use a scoped API: `result.{scope}.{assertion}`. Database assertions (`result.table()`) are async.
-
-**HTTP-specific:**
-
-| Method                                     | Description                                        |
-| ------------------------------------------ | -------------------------------------------------- |
-| `result.status.toBe(code)`                 | Assert HTTP status code                            |
-| `result.response.toMatchFile("file.json")` | Assert response body matches `responses/file.json` |
-
-**CLI-specific:**
-
-| Method                                              | Description                                        |
-| --------------------------------------------------- | -------------------------------------------------- |
-| `result.exitCode.toBe(code)`                        | Assert process exit code                           |
-| `result.stdout.toContain(str)`                      | Assert stdout contains string                      |
-| `result.stdout.not.toContain(str)`                  | Assert stdout does not contain string              |
-| `result.stdout.toContain(str, { near: "ctx" })`     | Assert stdout contains string near context         |
-| `result.stderr.toContain(str)`                      | Assert stderr contains string                      |
-| `result.stderr.not.toContain(str)`                  | Assert stderr does not contain string              |
-| `result.stderr.not.toContain(str, { near: "ctx" })` | Assert stderr does not contain string near context |
-| `result.stdout.toMatch(/regex/)`                    | Assert stdout matches regex                        |
-| `result.stdout.toMatchFile("file.txt")`             | Assert stdout matches `expected/file.txt`          |
-| `result.stderr.toMatchFile("file.txt")`             | Assert stderr matches `expected/file.txt`          |
-| `result.stdout.toBeEmpty()`                         | Assert stdout is empty                             |
-
-**Cross-mode:**
-
-| Method                                                             | Description                             |
-| ------------------------------------------------------------------ | --------------------------------------- |
-| `await result.table(name).toMatch({ columns, rows })`              | Assert database table contents          |
-| `await result.table(name, { service }).toMatch({ columns, rows })` | Assert on a specific database           |
-| `await result.table(name).toBeEmpty()`                             | Assert database table is empty          |
-| `result.file(path).toExist()`                                      | Assert file exists in working directory |
-| `result.file(path).not.toExist()`                                  | Assert file does not exist              |
-| `result.file(path).toContain(content)`                             | Assert file contains string             |
-| `result.file(path).toMatch(/regex/)`                               | Assert file content matches regex       |
+Result properties are raw values — use vitest `expect()` for assertions. Database and response file assertions use custom async methods.
+
+**Raw values (vitest expect):**
+
+| Expression                                   | Description                 |
+| -------------------------------------------- | --------------------------- |
+| `expect(result.exitCode).toBe(0)`            | CLI exit code               |
+| `expect(result.status).toBe(201)`            | HTTP status code            |
+| `expect(result.stdout).toContain("hello")`   | CLI stdout contains string  |
+| `expect(result.stderr).not.toContain("err")` | CLI stderr does not contain |
+
+**Files (result.file returns {exists, content}):**
+
+| Expression                                                        | Description                 |
+| ----------------------------------------------------------------- | --------------------------- |
+| `expect(result.file("dist/index.js").exists).toBe(true)`          | Assert file exists          |
+| `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  |
+
+**Grep (scoped text matching):**
+
+```typescript
+import { grep } from "@jterrazz/test";
+
+expect(grep(result.stdout, "unused-var.ts")).toContain("no-unused-vars");
+expect(grep(result.stdout, "valid/sorted.ts")).not.toContain("sort-imports");
+```
+
+`grep(output, pattern)` filters multi-line output to the block matching `pattern`, returning a string for vitest assertions.
+
+**Response (HTTP body):**
+
+| Expression                                      | Description                                                                 |
+| ----------------------------------------------- | --------------------------------------------------------------------------- |
+| `result.response.toMatchFile("expected.json")`  | Custom — compares body to `responses/expected.json`, shows diff on mismatch |
+| `expect(result.response.body).toEqual({ ... })` | Raw body object for vitest assertions                                       |
+
+**Tables (custom async — database queries):**
+
+| Expression                                                                      | Description                    |
+| ------------------------------------------------------------------------------- | ------------------------------ |
+| `await result.table("users").toMatch({ columns: ["name"], rows: [["Alice"]] })` | Assert database table contents |
+| `await result.table("events", { service: "analytics-db" }).toMatch({ ... })`    | Assert on a specific database  |
+| `await result.table("users").toBeEmpty()`                                       | Assert database table is empty |
 
 ## Multi-database support
 
@@ -221,6 +229,7 @@ const result = await spec("cross-db")
   .post("/users", "request.json")
   .run();
 
+expect(result.status).toBe(201);
 await result.table("users").toMatch({ columns: ["name"], rows: [["Alice"]] });
 await result.table("events", { service: "analytics-db" }).toMatch({
   columns: ["type"],
@@ -306,7 +315,7 @@ test("creates a user and returns 201", async () => {
     .run();
 
   // Then — user created with all three in table
-  result.status.toBe(201);
+  expect(result.status).toBe(201);
   await result.table("users").toMatch({
     columns: ["name"],
     rows: [["Alice"], ["Bob"], ["Charlie"]],

package/dist/index.cjs

@@ -244,20 +244,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`);
@@ -306,66 +292,9 @@ function formatResponseDiff(file, expected, actual) {
 	}
 	return lines.join("\n");
 }
-function formatExitCodeError(expected, received, stdout, stderr) {
-	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})`);
-	lines.push("");
-	lines.push(`${GREEN}- Expected${RESET}`);
-	lines.push(`${RED}+ Received${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}`);
-		}
-	}
-	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}`);
-	return lines.join("\n");
-}
 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("  |  ");
 }
@@ -861,205 +790,35 @@ var HonoAdapter = class {
 	}
 };
 //#endregion
-//#region src/specification/assertions/base.ts
-/**
-* Base assertion that handles .not negation.
-* Subclasses call this.assert(condition, message, negatedMessage) for each predicate.
-*/
-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
-/**
-* Assertions on a file in the working directory.
-* Usage: result.file("dist/index.js").toExist()
-*/
-var FileAssertion = class extends BaseAssertion {
-	filePath;
-	resolvedPath;
-	constructor(filePath, workDir) {
-		super();
-		this.filePath = filePath;
-		this.resolvedPath = (0, node_path.resolve)(workDir, filePath);
-	}
-	toExist() {
-		const exists = (0, node_fs.existsSync)(this.resolvedPath);
-		this.assert(exists, formatFileMissing(this.filePath), formatFileUnexpected(this.filePath));
-	}
-	toContain(expected) {
-		if (!(0, node_fs.existsSync)(this.resolvedPath)) {
-			if (this.negated) return;
-			throw new Error(formatFileMissing(this.filePath));
-		}
-		const content = (0, node_fs.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 (!(0, node_fs.existsSync)(this.resolvedPath)) {
-			if (this.negated) return;
-			throw new Error(formatFileMissing(this.filePath));
-		}
-		const content = (0, node_fs.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((0, node_fs.readFileSync)((0, node_path.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
-/**
-* Assertions on a string (stdout, stderr, response body).
-* Usage: result.stdout.toContain("hello")
-*/
-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 = (0, node_fs.readFileSync)((0, node_path.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)`;
-	}
-};
-//#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)
-*/
-var ValueAssertion = class extends BaseAssertion {
-	actual;
-	label;
-	context;
-	constructor(actual, label, context) {
-		super();
-		this.actual = actual;
-		this.label = label;
-		this.context = context;
+var ResponseAccessor = class {
+	body;
+	testDir;
+	constructor(body, testDir) {
+		this.body = body;
+		this.testDir = testDir;
 	}
-	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`);
+	toMatchFile(file) {
+		const expected = JSON.parse((0, node_fs.readFileSync)((0, node_path.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;
@@ -1077,32 +836,34 @@ 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);
 	}
 	file(path) {
-		return new FileAssertion(path, this.workDir ?? this.testDir);
+		const resolvedPath = (0, node_path.resolve)(this.workDir ?? this.testDir, path);
+		const exists = (0, node_fs.existsSync)(resolvedPath);
+		return {
+			get content() {
+				if (!exists) throw new Error(`File not found: ${path}`);
+				return (0, node_fs.readFileSync)(resolvedPath, "utf8");
+			},
+			exists
+		};
 	}
 	table(tableName, options) {
 		const db = this.resolveDatabase(options?.service);
@@ -1215,6 +976,7 @@ var SpecificationBuilder = class {
 		return this.runCliAction(workDir);
 	}
 	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);
@@ -1246,8 +1008,8 @@ var SpecificationBuilder = class {
 		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);
@@ -1276,16 +1038,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.
@@ -1410,6 +1182,7 @@ exports.HonoAdapter = HonoAdapter;
 exports.Orchestrator = Orchestrator;
 exports.cli = cli;
 exports.e2e = e2e;
+exports.grep = grep;
 exports.integration = integration;
 exports.mockOf = mockOf;
 exports.mockOfDate = mockOfDate;