@jterrazz/test 3.5.0 → 4.0.0

package/README.md

@@ -39,8 +39,8 @@ test("creates a user", async () => {
     .run();
 
   // Then — user created
-  result.expectStatus(201);
-  await result.expectTable("users", {
+  result.status.toBe(201);
+  await result.table("users").toMatch({
     columns: ["name"],
     rows: [["Alice"], ["Bob"]],
   });
@@ -69,12 +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
-    .expectExitCode(0)
-    .expectStdoutContains("Build completed")
-    .expectFile("dist/index.js")
-    .expectNoFile("dist/index.cjs")
-    .expectFileContains("dist/index.js", "Hello");
+  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");
 });
 ```
 
@@ -166,38 +165,46 @@ Every test follows the same pattern: `spec("label") → setup → action → ass
 
 ### Assertions
 
-All assertions return `this` for chaining. Database assertions (`expectTable`) are async.
+Assertions use a scoped API: `result.{scope}.{assertion}`. Database assertions (`result.table()`) are async.
 
 **HTTP-specific:**
 
-| Method                         | Description                                        |
-| ------------------------------ | -------------------------------------------------- |
-| `.expectStatus(code)`          | Assert HTTP status code                            |
-| `.expectResponse("file.json")` | Assert response body matches `responses/file.json` |
+| 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                               |
-| ---------------------------- | ----------------------------------------- |
-| `.expectExitCode(code)`      | Assert process exit code                  |
-| `.expectStdoutContains(str)` | Assert stdout contains string             |
-| `.expectStderrContains(str)` | Assert stderr contains string             |
-| `.expectStdout("file.txt")`  | Assert stdout matches `expected/file.txt` |
-| `.expectStderr("file.txt")`  | Assert stderr matches `expected/file.txt` |
+| 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                             |
-| ------------------------------------------------- | --------------------------------------- |
-| `.expectTable(table, { columns, rows })`          | Assert database table contents          |
-| `.expectTable(table, { columns, rows, service })` | Assert on a specific database           |
-| `.expectFile(path)`                               | Assert file exists in working directory |
-| `.expectNoFile(path)`                             | Assert file does not exist              |
-| `.expectFileContains(path, content)`              | Assert file contains string             |
+| 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       |
 
 ## Multi-database support
 
-When multiple databases are declared, `seed()` and `expectTable()` accept `{ service: "name" }` to target a specific database by its compose name. Without `service`, both default to the first postgres.
+When multiple databases are declared, `seed()` and `result.table()` accept `{ service: "name" }` to target a specific database by its compose name. Without `service`, both default to the first postgres.
 
 ```typescript
 const db = postgres({ compose: "db" });
@@ -214,11 +221,10 @@ const result = await spec("cross-db")
   .post("/users", "request.json")
   .run();
 
-await result.expectTable("users", { columns: ["name"], rows: [["Alice"]] });
-await result.expectTable("events", {
+await result.table("users").toMatch({ columns: ["name"], rows: [["Alice"]] });
+await result.table("events", { service: "analytics-db" }).toMatch({
   columns: ["type"],
   rows: [["user_created"]],
-  service: "analytics-db",
 });
 ```
 
@@ -300,8 +306,8 @@ test("creates a user and returns 201", async () => {
     .run();
 
   // Then — user created with all three in table
-  result.expectStatus(201);
-  await result.expectTable("users", {
+  result.status.toBe(201);
+  await result.table("users").toMatch({
     columns: ["name"],
     rows: [["Alice"], ["Bob"], ["Charlie"]],
   });

package/dist/index.cjs

@@ -861,92 +861,258 @@ 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 {
+	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`);
+	}
+	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`);
+	}
+};
+//#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;
+	}
+	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`);
+	}
+};
+//#endregion
 //#region src/specification/specification.ts
 var SpecificationResult = class {
 	commandResult;
 	config;
 	requestInfo;
-	response;
+	responseData;
 	testDir;
 	workDir;
 	constructor(options) {
-		this.response = options.response;
+		this.responseData = options.response;
 		this.commandResult = options.commandResult;
 		this.config = options.config;
 		this.testDir = options.testDir;
 		this.requestInfo = options.requestInfo;
 		this.workDir = options.workDir;
 	}
-	expectStatus(code) {
-		if (!this.response || !this.requestInfo) throw new Error("expectStatus requires an HTTP action (.get(), .post(), etc.)");
-		if (this.response.status !== code) throw new Error(formatStatusError(code, this.response.status, this.requestInfo, this.response.body));
-		return this;
-	}
-	expectResponse(file) {
-		if (!this.response) throw new Error("expectResponse requires an HTTP action (.get(), .post(), etc.)");
-		const expected = JSON.parse((0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "responses", file), "utf8"));
-		if (JSON.stringify(this.response.body) !== JSON.stringify(expected)) throw new Error(formatResponseDiff(file, expected, this.response.body));
-		return this;
-	}
-	expectExitCode(code) {
-		if (!this.commandResult) throw new Error("expectExitCode requires a CLI action (.exec())");
-		if (this.commandResult.exitCode !== code) throw new Error(formatExitCodeError(code, this.commandResult.exitCode, this.commandResult.stdout, this.commandResult.stderr));
-		return this;
-	}
-	expectStdout(file) {
-		if (!this.commandResult) throw new Error("expectStdout requires a CLI action (.exec())");
-		const expected = (0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "expected", file), "utf8").trim();
-		const actual = this.commandResult.stdout.trim();
-		if (actual !== expected) throw new Error(formatStdoutDiff(file, expected, actual));
-		return this;
-	}
-	expectStdoutContains(str) {
-		if (!this.commandResult) throw new Error("expectStdoutContains requires a CLI action (.exec())");
-		if (!this.commandResult.stdout.includes(str)) throw new Error(`Expected stdout to contain: "${str}"\n\nActual stdout:\n${this.commandResult.stdout}`);
-		return this;
+	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
+		});
 	}
-	expectStderr(file) {
-		if (!this.commandResult) throw new Error("expectStderr requires a CLI action (.exec())");
-		const expected = (0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "expected", file), "utf8").trim();
-		const actual = this.commandResult.stderr.trim();
-		if (actual !== expected) throw new Error(formatStdoutDiff(file, expected, actual));
-		return this;
+	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
+		});
 	}
-	expectStderrContains(str) {
-		if (!this.commandResult) throw new Error("expectStderrContains requires a CLI action (.exec())");
-		if (!this.commandResult.stderr.includes(str)) throw new Error(`Expected stderr to contain: "${str}"\n\nActual stderr:\n${this.commandResult.stderr}`);
-		return this;
+	get response() {
+		if (!this.responseData) throw new Error(".response requires an HTTP action (.get(), .post(), etc.)");
+		return new ResponseAssertion(this.responseData.body, this.testDir);
 	}
-	async expectTable(table, options) {
-		const db = this.resolveDatabase(options.service);
-		if (!db) throw new Error(options.service ? `expectTable requires database "${options.service}" but it was not found` : "expectTable requires a database adapter");
-		const actual = await db.query(table, options.columns);
-		if (JSON.stringify(actual) !== JSON.stringify(options.rows)) throw new Error(formatTableDiff(table, options.columns, options.rows, actual));
-		return this;
+	get stdout() {
+		if (!this.commandResult) throw new Error(".stdout requires a CLI action (.exec())");
+		return new StringAssertion(this.commandResult.stdout, "stdout", this.testDir);
 	}
-	expectFile(path) {
-		if (!(0, node_fs.existsSync)(this.resolveWorkPath(path))) throw new Error(formatFileMissing(path));
-		return this;
+	get stderr() {
+		if (!this.commandResult) throw new Error(".stderr requires a CLI action (.exec())");
+		return new StringAssertion(this.commandResult.stderr, "stderr", this.testDir);
 	}
-	expectNoFile(path) {
-		if ((0, node_fs.existsSync)(this.resolveWorkPath(path))) throw new Error(formatFileUnexpected(path));
-		return this;
+	file(path) {
+		return new FileAssertion(path, this.workDir ?? this.testDir);
 	}
-	expectFileContains(path, content) {
-		const resolved = this.resolveWorkPath(path);
-		if (!(0, node_fs.existsSync)(resolved)) throw new Error(formatFileMissing(path));
-		const actual = (0, node_fs.readFileSync)(resolved, "utf8");
-		if (!actual.includes(content)) throw new Error(formatFileContentMismatch(path, content, actual));
-		return this;
+	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`);
+		return new TableAssertion(tableName, db);
 	}
 	resolveDatabase(serviceName) {
 		if (serviceName && this.config.databases) return this.config.databases.get(serviceName);
 		return this.config.database;
 	}
-	resolveWorkPath(path) {
-		if (this.workDir) return (0, node_path.resolve)(this.workDir, path);
-		return (0, node_path.resolve)(this.testDir, path);
-	}
 };
 var SpecificationBuilder = class {
 	commandArgs = null;