@jterrazz/test 6.1.0 → 6.3.0

package/README.md

@@ -35,13 +35,13 @@ afterAll(() => run.cleanup());
 import { run } from '../../setup/integration.specification.js';
 
 test('creates a user', async () => {
-    // Given — one existing user
+    // Given - one existing user
     const result = await run('creates user')
         .seed('initial-users.sql')
         .post('/users', 'new-user.json')
         .run();
 
-    // Then — user created
+    // Then - user created
     expect(result.status).toBe(201);
     await result.table('users').toMatch({
         columns: ['name'],
@@ -67,10 +67,10 @@ export const run = await spec(command(resolve(import.meta.dirname, '../../bin/my
 import { run } from '../../setup/cli.specification.js';
 
 test('builds the project', async () => {
-    // Given — sample app project
+    // Given - sample app project
     const result = await run('build').project('sample-app').exec('build').run();
 
-    // Then — ESM output with source maps
+    // Then - ESM output with source maps
     expect(result.exitCode).toBe(0);
     expect(result.stdout).toContain('Build completed');
     expect(result.file('dist/index.js').exists).toBe(true);
@@ -83,7 +83,7 @@ test('builds the project', async () => {
 
 Three modes, same builder API. Each handles infrastructure and cleanup automatically.
 
-### `spec(app(...))` — testcontainers + in-process app
+### `spec(app(...))` - testcontainers + in-process app
 
 Starts real containers via testcontainers. App runs in-process (Hono). Fastest feedback loop.
 
@@ -103,7 +103,7 @@ export const run = await spec(
 );
 ```
 
-### `spec(stack(...))` — docker compose up + real HTTP
+### `spec(stack(...))` - docker compose up + real HTTP
 
 Starts the full `docker/compose.test.yaml` stack. App URL and databases auto-detected.
 
@@ -113,7 +113,7 @@ import { spec, stack } from '@jterrazz/test';
 export const run = await spec(stack('../../'));
 ```
 
-### `spec(command(...))` — local command execution
+### `spec(command(...))` - local command execution
 
 Runs CLI commands against fixture projects in temp directories. Optionally starts infrastructure.
 
@@ -331,13 +331,13 @@ Every test uses `// Given` and `// Then` comments. Always both, never one withou
 
 ```typescript
 test('creates a user and returns 201', async () => {
-    // Given — two existing users
+    // Given - two existing users
     const result = await run('creates user')
         .seed('initial-users.sql')
         .post('/users', 'new-user.json')
         .run();
 
-    // Then — user created with all three in table
+    // Then - user created with all three in table
     expect(result.status).toBe(201);
     await result.table('users').toMatch({
         columns: ['name'],

package/dist/index.cjs

@@ -115,22 +115,25 @@ var FetchAdapter = class {
 	constructor(url) {
 		this.baseUrl = url.replace(/\/$/, "");
 	}
-	async request(method, path, body) {
+	async request(method, path, body, headers) {
 		const init = {
 			method,
-			headers: { "Content-Type": "application/json" }
+			headers: {
+				"Content-Type": "application/json",
+				...headers
+			}
 		};
 		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 = {};
+		const responseHeaders = {};
 		response.headers.forEach((value, key) => {
-			headers[key] = value;
+			responseHeaders[key] = value;
 		});
 		return {
 			status: response.status,
 			body: responseBody,
-			headers
+			headers: responseHeaders
 		};
 	}
 };
@@ -145,22 +148,25 @@ var HonoAdapter = class {
 	constructor(app) {
 		this.app = app;
 	}
-	async request(method, path, body) {
+	async request(method, path, body, headers) {
 		const init = {
 			method,
-			headers: { "Content-Type": "application/json" }
+			headers: {
+				"Content-Type": "application/json",
+				...headers
+			}
 		};
 		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 = {};
+		const responseHeaders = {};
 		response.headers.forEach((value, key) => {
-			headers[key] = value;
+			responseHeaders[key] = value;
 		});
 		return {
 			status: response.status,
 			body: responseBody,
-			headers
+			headers: responseHeaders
 		};
 	}
 };
@@ -586,10 +592,12 @@ var SpecificationBuilder = class {
 	commandEnv = {};
 	config;
 	fixtures = [];
+	intercepts = [];
 	label;
 	mocks = [];
 	projectName = null;
 	request = null;
+	requestHeaders = {};
 	seeds = [];
 	spawnConfig = null;
 	testDir;
@@ -644,6 +652,41 @@ var SpecificationBuilder = class {
 		return this;
 	}
 	/**
+	* Set HTTP headers for the request. Multiple calls merge.
+	*
+	* @example
+	*   spec("french").headers({ 'Accept-Language': 'fr' }).get("/articles").run();
+	*/
+	headers(headers) {
+		this.requestHeaders = {
+			...this.requestHeaders,
+			...headers
+		};
+		return this;
+	}
+	/**
+	* Intercept an outgoing HTTP request and return a controlled response.
+	* Uses MSW under the hood. Intercepts are queued — multiple calls with the
+	* same trigger fire sequentially (first match consumed first).
+	*
+	* @param trigger - What to match (use openai.chat(), anthropic.messages(), http.get(), etc.)
+	* @param response - What to return (use openai.response(), http.json(), etc.)
+	*
+	* @example
+	*   spec('pipeline')
+	*       .intercept(openai.chat(), openai.response({ categories: ['TECH'] }))
+	*       .intercept(openai.chat(), openai.response({ headline: 'AI News' }))
+	*       .exec('process')
+	*       .run();
+	*/
+	intercept(trigger, response) {
+		this.intercepts.push({
+			trigger,
+			response
+		});
+		return this;
+	}
+	/**
 	* Send a GET request to the server adapter.
 	*
 	* @example
@@ -737,9 +780,17 @@ var SpecificationBuilder = class {
 			await db.seed(sql);
 		}
 		if (this.fixtures.length > 0 && workDir) for (const entry of this.fixtures) (0, node_fs.cpSync)((0, node_path.resolve)(this.testDir, "fixtures", entry.file), (0, node_path.resolve)(workDir, entry.file), { recursive: true });
-		for (const entry of this.mocks) JSON.parse((0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "mock", entry.file), "utf8"));
-		if (hasHttpAction) return this.runHttpAction();
-		return this.runCliAction(workDir);
+		let cleanupIntercepts = null;
+		if (this.intercepts.length > 0) {
+			const { registerIntercepts } = await Promise.resolve().then(() => require("./server.cjs"));
+			cleanupIntercepts = await registerIntercepts(this.intercepts);
+		}
+		try {
+			if (hasHttpAction) return await this.runHttpAction();
+			return await this.runCliAction(workDir);
+		} finally {
+			if (cleanupIntercepts) cleanupIntercepts();
+		}
 	}
 	resolveEnv(workDir) {
 		const keys = Object.keys(this.commandEnv);
@@ -764,7 +815,8 @@ var SpecificationBuilder = class {
 		if (!this.config.server) throw new Error("HTTP actions require a server adapter (use integration() or e2e())");
 		let body;
 		if (this.request.bodyFile) body = JSON.parse((0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "requests", this.request.bodyFile), "utf8"));
-		const response = await this.config.server.request(this.request.method, this.request.path, body);
+		const headers = Object.keys(this.requestHeaders).length > 0 ? this.requestHeaders : void 0;
+		const response = await this.config.server.request(this.request.method, this.request.path, body, headers);
 		return new SpecificationResult({
 			config: this.config,
 			requestInfo: {