@jterrazz/test 18.0.4 → 18.2.0

package/dist/index.js

@@ -24,9 +24,11 @@ import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { readdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { createServer } from "node:http";
+import { connect, isIP } from "node:net";
+import { createServer, request } from "node:http";
 import { tmpdir } from "node:os";
 import { TestRunner, describe, it, onTestFinished, vi } from "vitest";
+import { checkServerIdentity, connect as connect$1, getCACertificates } from "node:tls";
 import { mock, mockDeep } from "vitest-mock-extended";
 //#region src/expectations/disk/directory.ts
 const DEFAULT_IGNORES = [
@@ -656,6 +658,11 @@ function createDockerReader(testDir, inspect = inspectContainer) {
 }
 //#endregion
 //#region src/expectations/http/response.ts
+/** A fresh golden records the content-type alone, and a golden with no body is given the body the response carried. */
+const DEFAULT_RECORDING = {
+	bodyKeptAbsent: false,
+	headers: ["content-type"]
+};
 /** Read-only accessor for an HTTP response, compared by `expect(...).toMatch(...)`. */
 var ResponseAccessor = class {
 	/** The JSON value the body holds, or its text when it is not JSON; null when the body is empty. */
@@ -664,15 +671,21 @@ var ResponseAccessor = class {
 	captures;
 	/** Response headers as a flat, lower-cased key-value map. */
 	headers;
+	/** @internal */
+	recording;
 	status;
 	/** @internal */
 	testDir;
-	constructor(response, testDir, captures) {
+	/** Why the exchange never answered, a golden's `unreachable: <reason>` line; undefined when it answered. */
+	unreachable;
+	constructor(response, testDir, captures, recording = DEFAULT_RECORDING) {
 		this.body = response.body;
 		this.headers = response.headers;
 		this.status = response.status;
+		this.unreachable = response.unreachable;
 		this.testDir = testDir;
 		this.captures = captures ?? new CaptureScope();
+		this.recording = recording;
 	}
 };
 //#endregion
@@ -1121,6 +1134,9 @@ function parseHeaders(headerLines, fileName) {
 }
 const PARAMETERS = /;.*$/su;
 const START_LINE = /^HTTP\/1\.1\s+(?<status>\S+)(?:\s+.*)?$/u;
+const UNREACHABLE_LINE = /^unreachable:\s*(?<reason>\S.*)$/u;
+/** The one line an exchange that never answered is written as. */
+const unreachableLine = (reason) => `unreachable: ${reason}`;
 const TEXT_MEDIA_TYPES = /* @__PURE__ */ new Set([
 	"application/javascript",
 	"application/x-ndjson",
@@ -1170,12 +1186,14 @@ function statedContentType(headers) {
 }
 function parseResponseFile(content, fileName, contentType) {
 	const { body, headerLines, startLine } = splitSections(content);
+	const reason = UNREACHABLE_LINE.exec(startLine.trim())?.groups?.reason;
+	if (reason !== void 0) return unreachableFile(reason, headerLines.length > 0 || body.length > 0, fileName);
 	const status = START_LINE.exec(startLine.trim())?.[1];
 	if (status === void 0) throw new Error(refusal$1({
-		fix: "start the response file with its status line: \"HTTP/1.1 200 OK\"",
+		fix: "start the response file with its status line: \"HTTP/1.1 200 OK\", or \"unreachable: <reason>\" for an exchange that never answers",
 		found: `${fileName}: the first line is "${startLine}"`,
 		read: "docs/guides/api-specs.md#http-request-files-full-format",
-		why: "A response file opens on `HTTP/1.1 <status>`."
+		why: "A response file opens on `HTTP/1.1 <status>`, or is the one line `unreachable: <reason>`."
 	}));
 	const headers = parseHeaders(headerLines, fileName);
 	return {
@@ -1185,6 +1203,25 @@ function parseResponseFile(content, fileName, contentType) {
 		status
 	};
 }
+function unreachableFile(reason, more, fileName) {
+	if (more) throw new Error(refusal$1({
+		fix: "keep the one line `unreachable: <reason>`, or state the status the exchange answers",
+		found: `${fileName}: "unreachable: ${reason}" is followed by headers or a body`,
+		read: "docs/guides/deployment-specs.md#unreachable-is-a-result",
+		why: "An exchange that never answered carries no header and no body, so its golden is one line."
+	}));
+	return unreachableResponse(reason);
+}
+/** The golden of an exchange that never answered: its reason, and no status, header or body. */
+function unreachableResponse(reason) {
+	return {
+		body: void 0,
+		hasBody: false,
+		headers: {},
+		status: "",
+		unreachable: reason
+	};
+}
 const STATUS_TEXT = {
 	200: "OK",
 	201: "Created",
@@ -1193,6 +1230,8 @@ const STATUS_TEXT = {
 	301: "Moved Permanently",
 	302: "Found",
 	304: "Not Modified",
+	307: "Temporary Redirect",
+	308: "Permanent Redirect",
 	400: "Bad Request",
 	401: "Unauthorized",
 	403: "Forbidden",
@@ -1206,6 +1245,7 @@ const STATUS_TEXT = {
 };
 /** A body is written as text or JSON by its `content-type`, the actual response's when the fixture states none. */
 function serializeResponseFile(response, contentType) {
+	if (response.unreachable !== void 0) return `${unreachableLine(response.unreachable)}\n`;
 	const statusNumber = Number(response.status);
 	const statusText = STATUS_TEXT[statusNumber];
 	const lines = [`HTTP/1.1 ${response.status}${statusText === void 0 ? "" : ` ${statusText}`}`];
@@ -1231,26 +1271,49 @@ function isJsonLike(text) {
 //#endregion
 //#region src/expectations/goldens/response-goldens.ts
 const STATUS_CODE = /^\d+$/u;
-/** Headers are the intersection with the actual response, so a freshly updated fixture passes the next run. */
-function buildUpdatedResponse(previous, actual, workdir) {
-	const scope = new CaptureScope();
-	const status = previous && structuralEquals(previous.status, String(actual.status), scope) ? previous.status : String(actual.status);
+const outcomeOf = (response) => response.unreachable === void 0 ? `HTTP/1.1 ${response.status}` : unreachableLine(response.unreachable);
+function updatedUnreachable(previous, reason, scope) {
+	return unreachableResponse(previous?.unreachable !== void 0 && structuralEquals(previous.unreachable, reason, scope) ? previous.unreachable : reason);
+}
+function updatedHeaders(previous, actual, scope) {
 	const headers = {};
-	if (previous) for (const [key, value] of Object.entries(previous.headers)) {
+	if (previous === null) {
+		for (const name of (actual.recording ?? DEFAULT_RECORDING).headers) {
+			const actualValue = actual.headers[name.toLowerCase()];
+			if (actualValue !== void 0) headers[name.toLowerCase()] = actualValue;
+		}
+		return headers;
+	}
+	for (const [key, value] of Object.entries(previous.headers)) {
 		const actualValue = actual.headers[key.toLowerCase()];
-		if (actualValue === void 0) continue;
-		headers[key] = structuralEquals(value, actualValue, scope) ? value : actualValue;
+		if (actualValue !== void 0) headers[key] = structuralEquals(value, actualValue, scope) ? value : actualValue;
 	}
-	else if (actual.headers["content-type"] !== void 0) headers["content-type"] = actual.headers["content-type"];
-	const hasBody = actual.body !== null && actual.body !== void 0;
+	return headers;
+}
+function updatedBody(previous, actual, workdir) {
+	const hasBody = !((actual.recording ?? DEFAULT_RECORDING).bodyKeptAbsent && previous?.hasBody === false) && actual.body !== null && actual.body !== void 0;
 	return {
 		body: previous?.hasBody === true && hasBody ? mergePreservingPlaceholders(previous.body, actual.body, workdir) : mergePreservingPlaceholders(null, actual.body, workdir),
-		hasBody,
-		headers,
+		hasBody
+	};
+}
+/** Headers are the intersection with the actual response, so a freshly updated fixture passes the next run. */
+function buildUpdatedResponse(stated, actual, workdir) {
+	const scope = new CaptureScope();
+	if (actual.unreachable !== void 0) return updatedUnreachable(stated, actual.unreachable, scope);
+	const previous = stated?.unreachable === void 0 ? stated : null;
+	const status = previous && structuralEquals(previous.status, String(actual.status), scope) ? previous.status : String(actual.status);
+	return {
+		...updatedBody(previous, actual, workdir),
+		headers: updatedHeaders(previous, actual, scope),
 		status
 	};
 }
+function compareOutcome(name, expected, actual, scope) {
+	return structuralEquals(expected.unreachable, actual.unreachable, scope) ? null : `Response outcome mismatch (${name})\n  expected: ${outcomeOf(expected)}\n  received: ${outcomeOf(actual)}`;
+}
 function compareResponse(name, expected, actual, scope) {
+	if (expected.unreachable !== void 0 || actual.unreachable !== void 0) return compareOutcome(name, expected, actual, scope);
 	if (!(STATUS_CODE.test(expected.status) ? Number(expected.status) === actual.status : structuralEquals(expected.status, String(actual.status), scope))) return `Response status mismatch (${name})\n  expected: ${expected.status}\n  received: ${actual.status}`;
 	for (const [key, value] of Object.entries(expected.headers)) {
 		const actualValue = actual.headers[key.toLowerCase()];
@@ -1603,7 +1666,7 @@ function declaredDatabaseKeys(services) {
 }
 //#endregion
 //#region src/services/containers/run-setup-container.adapter.ts
-function answered(value) {
+function answered$1(value) {
 	const error = field$1(value, "error");
 	if (typeof error === "string") return { error };
 	const host = field$1(value, "host");
@@ -1634,7 +1697,7 @@ var RunSetupContainer = class {
 		this.request = request;
 	}
 	async start() {
-		const answer = answered(await (await fetch(`${this.url}/containers`, {
+		const answer = answered$1(await (await fetch(`${this.url}/containers`, {
 			body: JSON.stringify(this.request),
 			method: "POST"
 		})).json());
@@ -2238,24 +2301,7 @@ function defineAction(definition) {
 	};
 }
 //#endregion
-//#region src/specifications/api/request/http.result.ts
-/** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
-var HttpResult = class extends BaseResult {
-	responseData;
-	constructor(options) {
-		super(options);
-		this.responseData = options.response;
-	}
-	/** Access the HTTP response (status, headers, body) for assertions. */
-	get response() {
-		return new ResponseAccessor(this.responseData, this.testDir, this.captures);
-	}
-	get status() {
-		return this.responseData.status;
-	}
-};
-//#endregion
-//#region src/specifications/api/request/request-file.ts
+//#region src/expectations/http/request-file.ts
 function parseRequestFile(content, fileName) {
 	const { body, headerLines, startLine } = splitSections(content);
 	const start = /^(?<method>[A-Z]+)\s+(?<path>\S+)$/u.exec(startLine.trim());
@@ -2274,6 +2320,23 @@ function parseRequestFile(content, fileName) {
 	};
 }
 //#endregion
+//#region src/specifications/api/request/http.result.ts
+/** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
+var HttpResult = class extends BaseResult {
+	responseData;
+	constructor(options) {
+		super(options);
+		this.responseData = options.response;
+	}
+	/** Access the HTTP response (status, headers, body) for assertions. */
+	get response() {
+		return new ResponseAccessor(this.responseData, this.testDir, this.captures);
+	}
+	get status() {
+		return this.responseData.status;
+	}
+};
+//#endregion
 //#region src/specifications/api/request/route.ts
 /** A path with no `:name` segment is sent as written; `{ params: {} }` states that it is the route. */
 const params = {
@@ -2356,15 +2419,15 @@ const ACCESSORS = [
 		probe: ".directory("
 	}
 ];
-const NO_WORKDIR = { workDir: null };
+const NO_WORKDIR$1 = { workDir: null };
 function bodyOf(body, testDir) {
 	const content = readFileSync(resolve(testDir, body.path), "utf8");
 	return body.path.endsWith(".json") ? JSON.parse(content) : content;
 }
-function writtenRequest(source, testDir) {
+function writtenRequest$1(source, testDir) {
 	return typeof source === "string" ? parseRequestFile(dedent(source), "the request in place") : parseRequestFile(readFileSync(resolve(testDir, source.path), "utf8"), source.path);
 }
-async function send({ body, headers: written, method, path, template }, read, { server }, { config, testDir }) {
+async function send$1({ body, headers: written, method, path, template }, read, { server }, { config, testDir }) {
 	if (isDiskDirectory(body)) throw new TypeError(refusal$1("disk-named-by-relative-path-at-runtime", {
 		fix: `name one file: .${method.toLowerCase()}(${JSON.stringify(path)}, file('./__requests__/body.json'))`,
 		found: `.${method.toLowerCase()}(${JSON.stringify(path)}, directory(${JSON.stringify(body.path)})), a directory where the body is one file`
@@ -2384,15 +2447,15 @@ async function send({ body, headers: written, method, path, template }, read, {
 }
 //#endregion
 //#region src/specifications/api/api.composition.ts
-const composition$6 = {
+const composition$7 = {
 	actions: [
 		defineAction({
 			accessors: ACCESSORS,
 			name: "request",
-			perform: async ([source], read, adapters, run) => await send(writtenRequest(source, run.testDir), read, adapters, run),
+			perform: async ([source], read, adapters, run) => await send$1(writtenRequest$1(source, run.testDir), read, adapters, run),
 			prepare: ([source]) => {
 				if (typeof source !== "string") requireDiskFile("request", source, ".http");
-				return NO_WORKDIR;
+				return NO_WORKDIR$1;
 			},
 			row: {
 				group: "Terminal action",
@@ -2404,13 +2467,13 @@ const composition$6 = {
 			accessors: ACCESSORS,
 			name: "get",
 			options: [params],
-			perform: async ([path, options], read, adapters, run) => await send({
+			perform: async ([path, options], read, adapters, run) => await send$1({
 				method: "GET",
 				...routeRequest("GET", path, options)
 			}, read, adapters, run),
 			prepare: ([path, options]) => {
 				routeRequest("GET", path, options);
-				return NO_WORKDIR;
+				return NO_WORKDIR$1;
 			},
 			row: {
 				group: "Terminal action",
@@ -2422,14 +2485,14 @@ const composition$6 = {
 			accessors: ACCESSORS,
 			name: "post",
 			options: [params],
-			perform: async ([path, body, options], read, adapters, run) => await send({
+			perform: async ([path, body, options], read, adapters, run) => await send$1({
 				body,
 				method: "POST",
 				...routeRequest("POST", path, options)
 			}, read, adapters, run),
 			prepare: ([path, _body, options]) => {
 				routeRequest("POST", path, options);
-				return NO_WORKDIR;
+				return NO_WORKDIR$1;
 			},
 			row: {
 				group: "Terminal action",
@@ -2441,14 +2504,14 @@ const composition$6 = {
 			accessors: ACCESSORS,
 			name: "put",
 			options: [params],
-			perform: async ([path, body, options], read, adapters, run) => await send({
+			perform: async ([path, body, options], read, adapters, run) => await send$1({
 				body,
 				method: "PUT",
 				...routeRequest("PUT", path, options)
 			}, read, adapters, run),
 			prepare: ([path, _body, options]) => {
 				routeRequest("PUT", path, options);
-				return NO_WORKDIR;
+				return NO_WORKDIR$1;
 			},
 			row: {
 				group: "Terminal action",
@@ -2460,13 +2523,13 @@ const composition$6 = {
 			accessors: ACCESSORS,
 			name: "delete",
 			options: [params],
-			perform: async ([path, options], read, adapters, run) => await send({
+			perform: async ([path, options], read, adapters, run) => await send$1({
 				method: "DELETE",
 				...routeRequest("DELETE", path, options)
 			}, read, adapters, run),
 			prepare: ([path, options]) => {
 				routeRequest("DELETE", path, options);
-				return NO_WORKDIR;
+				return NO_WORKDIR$1;
 			},
 			row: {
 				group: "Terminal action",
@@ -2501,7 +2564,7 @@ const composition$6 = {
 	}
 };
 const apiDefinition = defineSpecification()({
-	...composition$6,
+	...composition$7,
 	adapters: (config) => ({
 		clock: processClock,
 		databases: databaseSet(config),
@@ -3601,7 +3664,7 @@ function runFolder(root, cwd) {
 }
 //#endregion
 //#region src/specifications/cli/cli.composition.ts
-const composition$5 = {
+const composition$6 = {
 	actions: [defineAction({
 		accessors: CLI_RESULT_ROWS,
 		name: "exec",
@@ -3713,7 +3776,7 @@ const composition$5 = {
 	}
 };
 const cliDefinition = defineSpecification()({
-	...composition$5,
+	...composition$6,
 	adapters: (config) => ({
 		command: config.command,
 		databases: databaseSet(config),
@@ -3932,6 +3995,453 @@ async function startCli(bin, options = {}) {
 	};
 }
 //#endregion
+//#region src/specifications/deployment/exchange/connect.capability.ts
+/** Read by the exchange, never armed: the address is where one request is sent, not a state of the world. */
+const connect$2 = defineCapability({
+	initial: null,
+	name: "connect",
+	phase: 0,
+	reduce: (_held, [address]) => address,
+	row: {
+		group: "Setup",
+		name: ".connect()",
+		probe: ".connect("
+	}
+});
+//#endregion
+//#region src/specifications/deployment/exchange/exchange.result.ts
+const EXCHANGE_RESULT_ROWS = [{
+	group: "Result accessor",
+	name: ".response",
+	probe: "result.response"
+}, {
+	group: "Result accessor",
+	name: ".tls",
+	probe: "result.tls"
+}];
+/** What one exchange with a deployment hands back: the response, or why none came, and the certificate it was presented. */
+var ExchangeResult = class extends BaseResult {
+	answer;
+	recording;
+	/** The certificate an https exchange was presented and the trust check's verdict; undefined over http, or when no handshake completed. */
+	tls;
+	constructor(options) {
+		super(options);
+		this.answer = options.response;
+		this.recording = options.recording;
+		this.tls = options.tls;
+	}
+	/** The whole response (status, headers, body), or `unreachable: <reason>`, compared whole: `toMatch(<.http text>)` or `toMatch(file(...))`. */
+	get response() {
+		return new ResponseAccessor(this.answer, this.testDir, this.captures, this.recording);
+	}
+};
+//#endregion
+//#region src/specifications/deployment/exchange/target.ts
+const SCHEME = /^[a-z][a-z\d+.-]*:\/\//iu;
+const BRACKETED = /^\[(?<host>[^\]]+)\](?::(?<port>\d+))?$/u;
+const HOST_AND_PORT = /^(?<host>[^:[\]\s]+)(?::(?<port>\d+))?$/u;
+/** The host a URL names, an IPv6 literal without its brackets. */
+function hostOf(url) {
+	return url.hostname.startsWith("[") ? url.hostname.slice(1, -1) : url.hostname;
+}
+/** The port a URL names, or its scheme's. */
+function portOf(url) {
+	if (url.port !== "") return Number(url.port);
+	return url.protocol === "https:" ? 443 : 80;
+}
+function refusedTarget(target, found, fix) {
+	return new Error(refusal$1({
+		fix,
+		found: `${JSON.stringify(target)}, ${found}`,
+		read: "docs/guides/deployment-specs.md#the-target",
+		why: "An exchange goes to one absolute http(s) URL: written whole, or a path from the `url` the specification names."
+	}));
+}
+/** A path is read from the base URL as written, its own path kept: `https://site.test/app` and `/health` are `https://site.test/app/health`. */
+function targetUrl(target, base) {
+	if (SCHEME.test(target)) {
+		const url = new URL(target);
+		if (url.protocol !== "http:" && url.protocol !== "https:") throw refusedTarget(target, `a ${url.protocol.slice(0, -1)} URL`, "name an http:// or https:// URL");
+		return url;
+	}
+	if (!target.startsWith("/")) throw refusedTarget(target, "neither an absolute URL nor a path", "write the URL whole, `https://site.test/health`, or a path from the `url` option, `/health`");
+	if (base === void 0) throw refusedTarget(target, "a path, and the specification names no `url` to read it from", "write the URL whole, or name the base with `specification.deployment({ url })`");
+	return new URL(`${base.replace(/\/+$/u, "")}${target}`);
+}
+/** `host:port`, `[v6]:port`, or a bare host, which keeps the URL's port. */
+function connectAddress(written, url) {
+	const address = written.trim();
+	const match = BRACKETED.exec(address) ?? HOST_AND_PORT.exec(address);
+	const host = match?.groups?.host;
+	if (host === void 0 || address.startsWith("[") && isIP(host) !== 6) throw new Error(refusal$1({
+		fix: "write the address as `.connect('10.0.0.5:30443')`, `.connect('[fd7a::1]:443')` or `.connect('node.test')`",
+		found: `.connect(${JSON.stringify(written)}), no address`,
+		read: "docs/guides/deployment-specs.md#setup-connect",
+		why: "`.connect()` names the one address the socket opens on: a host, and a port when it is not the port of the URL."
+	}));
+	const port = match?.groups?.port;
+	return {
+		host,
+		port: port === void 0 ? portOf(url) : Number(port)
+	};
+}
+//#endregion
+//#region src/specifications/deployment/exchange/tls-facts.ts
+const DAY_MS = 864e5;
+function firstOf(value) {
+	return Array.isArray(value) ? value[0] : value;
+}
+function altNamesOf(certificate) {
+	return (certificate.subjectaltname ?? "").split(",").map((name) => name.trim().slice(name.trim().indexOf(":") + 1)).filter((name) => name !== "");
+}
+/** Read at the moment of the exchange, so `daysRemaining` is the margin the deployment had when it answered. */
+function tlsFacts(certificate, verdict, now) {
+	const validTo = new Date(certificate.valid_to);
+	return {
+		altNames: altNamesOf(certificate),
+		authorizationError: verdict.authorizationError,
+		authorized: verdict.authorizationError === void 0,
+		covers: (host) => checkServerIdentity(host, certificate) === void 0,
+		daysRemaining: Math.floor((validTo.getTime() - now) / DAY_MS),
+		issuer: firstOf(certificate.issuer.CN) ?? firstOf(certificate.issuer.O) ?? "",
+		protocol: verdict.protocol,
+		subject: firstOf(certificate.subject.CN) ?? "",
+		validFrom: new Date(certificate.valid_from),
+		validTo
+	};
+}
+//#endregion
+//#region src/specifications/deployment/exchange/unreachable.ts
+/** Why an exchange never answered, as the `unreachable: <reason>` line of its golden reads it. */
+const TIMEOUT = "timeout";
+const TLS = "tls";
+const REASONS = {
+	EAI_AGAIN: "dns",
+	EAI_FAIL: "dns",
+	EAI_NODATA: "dns",
+	EAI_NONAME: "dns",
+	ECONNABORTED: "reset",
+	ECONNREFUSED: "refused",
+	ECONNRESET: "reset",
+	EHOSTDOWN: "no route",
+	EHOSTUNREACH: "no route",
+	ENETDOWN: "no route",
+	ENETUNREACH: "no route",
+	ENODATA: "dns",
+	ENOTFOUND: "dns",
+	EPIPE: "reset"
+};
+/** The code node raised, when it raised one. */
+function codeOf(error) {
+	if (typeof error === "string") return error === "" ? void 0 : error;
+	const code = error !== null && typeof error === "object" ? Reflect.get(error, "code") : void 0;
+	return typeof code === "string" && code !== "" ? code : void 0;
+}
+/** `dns`, `refused`, `reset`, `no route`, or the code node raised; a handshake's own failure is `tls <CODE>`, its network's reads as the network's. */
+function unreachableReason(error, duringHandshake = false) {
+	const code = codeOf(error);
+	const reason = code === void 0 ? void 0 : REASONS[code];
+	if (reason !== void 0) return reason;
+	if (duringHandshake) return `${TLS} ${code ?? "handshake"}`;
+	return code ?? (error instanceof Error ? error.message : String(error));
+}
+/** A certificate the trust check refused, by the code it refused with. */
+function refusedCertificate(code) {
+	return `${TLS} ${code}`;
+}
+//#endregion
+//#region src/specifications/deployment/exchange/transport.ts
+const USER_AGENT = "@jterrazz/test";
+function flatHeaders(headers) {
+	return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, Array.isArray(value) ? value.join(", ") : String(value)]));
+}
+function headersOf(sent) {
+	const headers = {
+		host: sent.url.host,
+		"user-agent": USER_AGENT
+	};
+	for (const [name, value] of Object.entries(sent.headers)) headers[name.toLowerCase()] = value;
+	return headers;
+}
+async function opened(socket, event) {
+	await new Promise((resolve, reject) => {
+		socket.once(event, () => {
+			resolve();
+		});
+		socket.once("error", reject);
+	});
+}
+async function openSecure(address, url, route, hold) {
+	const name = hostOf(url);
+	const socket = connect$1({
+		checkServerIdentity: (_host, certificate) => checkServerIdentity(name, certificate),
+		host: address.host,
+		port: address.port,
+		rejectUnauthorized: false,
+		...route.ca === void 0 ? {} : { ca: [...getCACertificates("default"), route.ca] },
+		...isIP(name) === 0 ? { servername: name } : {}
+	});
+	hold(socket);
+	try {
+		await opened(socket, "secureConnect");
+	} catch (error) {
+		return {
+			tls: void 0,
+			unreachable: unreachableReason(error, true)
+		};
+	}
+	const refused = socket.authorized ? void 0 : codeOf(socket.authorizationError);
+	const tls = tlsFacts(socket.getPeerCertificate(), {
+		authorizationError: refused,
+		protocol: socket.getProtocol() ?? void 0
+	}, Date.now());
+	return refused === void 0 || route.insecure ? {
+		socket,
+		tls
+	} : {
+		tls,
+		unreachable: refusedCertificate(refused)
+	};
+}
+async function open$1(sent, route, hold) {
+	const address = route.connect ?? {
+		host: hostOf(sent.url),
+		port: portOf(sent.url)
+	};
+	if (sent.url.protocol === "https:") return await openSecure(address, sent.url, route, hold);
+	const socket = connect(address);
+	hold(socket);
+	await opened(socket, "connect");
+	return {
+		socket,
+		tls: void 0
+	};
+}
+async function exchanged(sent, socket) {
+	return await new Promise((resolve, reject) => {
+		const outgoing = request({
+			createConnection: () => socket,
+			headers: headersOf(sent),
+			method: sent.method,
+			path: `${sent.url.pathname}${sent.url.search}`
+		}, (response) => {
+			const chunks = [];
+			response.on("data", (chunk) => {
+				chunks.push(chunk);
+			});
+			response.once("end", () => {
+				resolve({
+					response,
+					text: Buffer.concat(chunks).toString("utf8")
+				});
+			});
+			response.once("error", reject);
+		});
+		outgoing.once("error", reject);
+		outgoing.end(sent.body);
+	});
+}
+async function answered(sent, route, hold, presented) {
+	const opening = await open$1(sent, route, hold);
+	presented(opening.tls);
+	if (!("socket" in opening)) return opening;
+	const { response, text } = await exchanged(sent, opening.socket);
+	return {
+		headers: flatHeaders(response.headers),
+		status: response.statusCode ?? 0,
+		text,
+		tls: opening.tls
+	};
+}
+/** One request and its whole response, under one deadline; a redirect is the answer, never followed. */
+async function exchange(sent, route) {
+	let socket;
+	let tls;
+	let timer;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(() => {
+			resolve({
+				tls,
+				unreachable: TIMEOUT
+			});
+		}, route.timeout);
+	});
+	try {
+		return await Promise.race([answered(sent, route, (held) => {
+			socket = held;
+		}, (facts) => {
+			tls = facts;
+		}), deadline]);
+	} catch (error) {
+		return {
+			tls,
+			unreachable: unreachableReason(error)
+		};
+	} finally {
+		clearTimeout(timer);
+		socket?.destroy();
+	}
+}
+//#endregion
+//#region src/specifications/deployment/exchange/request.action.ts
+const NO_WORKDIR = { workDir: null };
+function responseOf(answer) {
+	if (answer.unreachable !== void 0) return {
+		body: null,
+		headers: {},
+		status: 0,
+		unreachable: answer.unreachable
+	};
+	const contentType = answer.headers["content-type"];
+	return {
+		body: bodyKind(contentType) === "binary" ? null : readBody$1(answer.text, contentType) ?? null,
+		headers: answer.headers,
+		status: answer.status
+	};
+}
+async function send(written, read, { config, testDir }) {
+	const url = targetUrl(written.target, config.baseUrl);
+	const address = read(connect$2);
+	const answer = await exchange({
+		body: written.body,
+		headers: {
+			...written.headers,
+			...read(headers)
+		},
+		method: written.method,
+		url
+	}, {
+		ca: config.ca,
+		connect: address === null ? void 0 : connectAddress(address, url),
+		insecure: config.insecure,
+		timeout: config.timeout
+	});
+	return new ExchangeResult({
+		config,
+		recording: config.recording,
+		response: responseOf(answer),
+		testDir,
+		tls: answer.tls
+	});
+}
+function writtenRequest(source, testDir) {
+	const parsed = typeof source === "string" ? parseRequestFile(dedent(source), "the request in place") : parseRequestFile(readFileSync(resolve(testDir, source.path), "utf8"), source.path);
+	return {
+		body: parsed.body,
+		headers: parsed.headers,
+		method: parsed.method,
+		target: parsed.path
+	};
+}
+/** A redirect is the answer, never followed; an exchange that never answered is the answer too, `unreachable: <reason>`. */
+const get = defineAction({
+	accessors: EXCHANGE_RESULT_ROWS,
+	name: "get",
+	perform: async ([target], read, _adapters, run) => await send({
+		headers: {},
+		method: "GET",
+		target
+	}, read, run),
+	row: {
+		group: "Terminal action",
+		name: ".get()",
+		probe: ".get('/"
+	}
+});
+//#endregion
+//#region src/specifications/deployment/deployment.composition.ts
+const composition$5 = {
+	actions: [defineAction({
+		accessors: EXCHANGE_RESULT_ROWS,
+		name: "request",
+		perform: async ([source], read, _adapters, run) => await send(writtenRequest(source, run.testDir), read, run),
+		prepare: ([source]) => {
+			if (typeof source !== "string") requireDiskFile("request", source, ".http");
+			return NO_WORKDIR;
+		},
+		row: {
+			group: "Terminal action",
+			name: ".request()",
+			probe: ".request(file("
+		}
+	}), get],
+	capabilities: [
+		connect$2,
+		headers,
+		sharing
+	],
+	options: {
+		ca: {
+			group: "Constructor option",
+			name: "ca",
+			probe: "ca:"
+		},
+		insecure: {
+			group: "Constructor option",
+			name: "insecure",
+			probe: "insecure:"
+		},
+		recordedHeaders: {
+			group: "Constructor option",
+			name: "recordedHeaders",
+			probe: "recordedHeaders:"
+		},
+		timeout: {
+			group: "Constructor option",
+			name: "timeout",
+			probe: "timeout:"
+		},
+		url: {
+			group: "Constructor option",
+			name: "url",
+			probe: "url:"
+		}
+	}
+};
+const deploymentDefinition = defineSpecification()({
+	...composition$5,
+	adapters: (_config) => ({}),
+	locate: getCallerDir
+});
+//#endregion
+//#region src/specifications/deployment/deployment.handle.ts
+const DEFAULT_TIMEOUT_MS$1 = 5e3;
+const DEFAULT_RECORDED_HEADERS = ["content-type", "location"];
+/** Refused before the first exchange: a base that is no http(s) URL, and a deadline that is no positive number of milliseconds. */
+function refuseOptions$1(options) {
+	if (options.url !== void 0 && !/^https?:\/\/[^/\s]/u.test(options.url)) throw new Error(refusal$1({
+		fix: "name the deployment's base as an absolute URL, `url: 'https://site.test'`, or leave it out and write each URL whole",
+		found: `specification.deployment({ url: ${JSON.stringify(options.url)} }), no http(s) URL`,
+		read: "docs/guides/deployment-specs.md#options",
+		why: "A path is read from the base `url`, so the base is an absolute http:// or https:// URL."
+	}));
+	if (options.timeout !== void 0 && (!Number.isFinite(options.timeout) || options.timeout <= 0)) throw new Error(refusal$1({
+		fix: "pass the milliseconds one exchange may take, `timeout: 2000`, or leave the 5000 default",
+		found: `specification.deployment({ timeout: ${String(options.timeout)} }), no deadline`,
+		read: "docs/guides/deployment-specs.md#options",
+		why: "An exchange that never answers reads `unreachable: timeout` once its deadline passes, so the deadline is a positive number of milliseconds."
+	}));
+}
+async function startDeployment(options = {}) {
+	await registerMatchers();
+	refuseOptions$1(options);
+	const config = {
+		baseUrl: options.url,
+		ca: options.ca,
+		insecure: options.insecure ?? false,
+		recording: {
+			bodyKeptAbsent: true,
+			headers: options.recordedHeaders ?? DEFAULT_RECORDED_HEADERS
+		},
+		timeout: options.timeout ?? DEFAULT_TIMEOUT_MS$1
+	};
+	return {
+		cleanup: async () => {},
+		deployment: deploymentDefinition.open(config)
+	};
+}
+//#endregion
 //#region src/specifications/integration/call.result.ts
 /** The result of an in-process call: `value` is what it returned, `error` what it threw. */
 var CallResult = class extends BaseResult {
@@ -5442,6 +5952,8 @@ const specification = {
 	api: startApi,
 	/** Test a command binary, each spec in a fresh temp directory. */
 	cli: startCli,
+	/** Probe a running deployment over the network: one complete HTTP exchange, no browser; `.get(url)` or `.request(...)` ends the chain. */
+	deployment: startDeployment,
 	/** Specify a module against real services, or against a golden; `.call()` ends the chain. */
 	integration: startIntegration,
 	/** Test background jobs, in this process; `.trigger(name)` ends the chain. */