@jterrazz/test 17.0.0 → 18.0.0

package/dist/{shared-stream-body.js → shared-stub-reply.js}

@@ -109,6 +109,16 @@ var StubQueue = class {
 };
 //#endregion
 //#region src/stubs/delivery/stream-body.ts
+async function nextTask() {
+	const { port1, port2 } = new MessageChannel();
+	await new Promise((resolve) => {
+		port1.onmessage = () => {
+			port1.close();
+			resolve();
+		};
+		port2.postMessage(null);
+	});
+}
 /** One serialisation for all three deliveries (msw server, msw worker, `node:http` stub). */
 function toReadableStream(body) {
 	const encoder = new TextEncoder();
@@ -119,12 +129,39 @@ function toReadableStream(body) {
 			controller.close();
 			return;
 		}
-		if (body.delayBetweenChunks > 0 && index > 0) await pause(body.delayBetweenChunks);
+		if (index > 0) {
+			await pause(body.delayBetweenChunks);
+			await nextTask();
+		}
 		index += 1;
 		controller.enqueue(encoder.encode(chunk));
 	} });
 }
 //#endregion
-export { StubQueue as n, toReadableStream as t };
+//#region src/stubs/delivery/stub-reply.ts
+/** A request's body as a stub's filter reads it: the parsed JSON, the raw text when it is none, `null` when there is none. */
+function requestBody(raw) {
+	if (raw.length === 0) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+}
+/** The reply a matched stub states for this request, once its delay has passed. */
+async function replyOf(response, observed) {
+	const reply = typeof response === "function" ? response(observed) : response;
+	await pause(reply.delay ?? 0);
+	return reply;
+}
+/** The `error` of the 501 every delivery answers a request it refuses, whichever process serves it. */
+function refusedReply(summary) {
+	return `@jterrazz/test strict stubs: ${summary}`;
+}
+function unmatchedSummary(method, url) {
+	return `unmatched request ${method} ${url}`;
+}
+//#endregion
+export { toReadableStream as a, unmatchedSummary as i, replyOf as n, StubQueue as o, requestBody as r, refusedReply as t };
 
-//# sourceMappingURL=shared-stream-body.js.map
+//# sourceMappingURL=shared-stub-reply.js.map

package/dist/shared-stub-server.js

@@ -1,6 +1,7 @@
+import { n as refusal } from "./shared-refusal.js";
 import { n as isStreamBody } from "./shared-exchange.js";
-import { t as pause } from "./shared-pause.js";
-import { n as StubQueue, t as toReadableStream } from "./shared-stream-body.js";
+import { a as toReadableStream, i as unmatchedSummary, n as replyOf, o as StubQueue, r as requestBody, t as refusedReply } from "./shared-stub-reply.js";
+import { METHODS } from "node:http";
 //#region src/stubs/delivery/msw-handlers.ts
 const NEVER_CACHED = { "cache-control": "no-store" };
 function toMswResponse(msw, response) {
@@ -52,13 +53,14 @@ function handlerOf(msw, method) {
 function buildStubHandlers(msw, stubs, bypass) {
 	const queue = new StubQueue(stubs);
 	let violation = null;
-	const recordViolation = (method, url) => {
-		violation ??= queue.unmatchedError(method, url);
-		return msw.HttpResponse.json({ error: `@jterrazz/test strict stubs: unmatched request ${method} ${url}` }, {
+	const refuse = (error, summary) => {
+		violation ??= error;
+		return msw.HttpResponse.json({ error: refusedReply(summary) }, {
 			headers: NEVER_CACHED,
 			status: 501
 		});
 	};
+	const recordViolation = (method, url) => refuse(queue.unmatchedError(method, url), unmatchedSummary(method, url));
 	const handlers = [];
 	for (const route of queue.routes) for (const method of route.methods) {
 		const handlerFn = handlerOf(msw, method);
@@ -67,90 +69,25 @@ function buildStubHandlers(msw, stubs, bypass) {
 			const observed = await observe(request);
 			const stub = queue.take(observed);
 			if (!stub) return recordViolation(request.method, request.url);
-			const response = typeof stub.response === "function" ? stub.response(observed) : stub.response;
-			await pause(response.delay ?? 0);
-			return toMswResponse(msw, response);
+			return toMswResponse(msw, await replyOf(stub.response, observed));
 		}));
 	}
 	handlers.push(msw.http.all("*", ({ request }) => bypass?.(request.url) === true ? msw.passthrough() : recordViolation(request.method, request.url)));
 	return {
 		handlers,
+		refuse,
 		violation: () => queue.verdict(violation)
 	};
 }
 async function observe(request) {
-	let body = null;
-	const rawText = await request.clone().text();
-	if (rawText) try {
-		body = JSON.parse(rawText);
-	} catch {
-		body = rawText;
-	}
 	return {
-		body,
+		body: requestBody(await request.clone().text()),
 		headers: Object.fromEntries(request.headers),
 		method: request.method.toUpperCase(),
 		url: request.url
 	};
 }
 //#endregion
-//#region src/stubs/delivery/same-process/fetch-refusals.ts
-const PROBE = "http://request-init.invalid/";
-const probeOf = (init) => init.body instanceof ReadableStream ? {
-	...init,
-	body: new Blob()
-} : init;
-/**
-* Wraps `underlying` so a RequestInit that fetch itself refuses rejects with fetch's own TypeError, before any stub can serve it.
-* @see https://fetch.spec.whatwg.org/#dom-request
-*/
-function refusingWhatFetchRefuses(underlying) {
-	return async (input, init) => {
-		if (init === void 0) return await underlying(input);
-		const { method } = new Request(PROBE, probeOf(init));
-		return await underlying(input, {
-			...init,
-			method
-		});
-	};
-}
-//#endregion
-//#region src/stubs/delivery/same-process/owned-body.ts
-async function release(reader, reason) {
-	try {
-		await reader.cancel(reason);
-	} catch {}
-}
-function withOwnedBody(response) {
-	const { body } = response;
-	if (body === null) return response;
-	const reader = body.getReader();
-	const owned = new ReadableStream({
-		cancel: (reason) => {
-			release(reader, reason);
-		},
-		pull: async (controller) => {
-			const { done, value } = await reader.read();
-			if (done) controller.close();
-			else controller.enqueue(value);
-		}
-	});
-	const reply = new Response(owned, {
-		headers: response.headers,
-		status: response.status,
-		statusText: response.statusText
-	});
-	Object.defineProperties(reply, {
-		redirected: { value: response.redirected },
-		type: { value: response.type },
-		url: { value: response.url }
-	});
-	return reply;
-}
-function owningBodies(underlying) {
-	return async (input, init) => withOwnedBody(await underlying(input, init));
-}
-//#endregion
 //#region src/stubs/delivery/same-process/stub-server.ts
 async function loadMsw() {
 	const [{ setupServer }, msw] = await Promise.all([import("msw/node"), import("msw")]);
@@ -160,25 +97,40 @@ async function loadMsw() {
 	};
 }
 let serverInstance = null;
-let installedFetch = null;
+let refuseOffTheWire = null;
+function offTheWireError(request) {
+	return new Error(refusal("network-strict-after-first-stub", {
+		fix: "send a method in the capitals the HTTP parser reads (`PATCH`, not `patch`): fetch upper-cases DELETE, GET, HEAD, OPTIONS, POST and PUT, and sends any other as written",
+		found: `an outgoing request the network double cannot read off the wire, ${request.method} ${request.url}: its method is not one of node's \`http.METHODS\`, so no stub could answer it and it would reach the network`
+	}));
+}
+function guardOffTheWireMethods() {
+	const next = globalThis.fetch;
+	globalThis.fetch = async (input, init) => {
+		const request = new Request(input, init);
+		if (refuseOffTheWire !== null && !METHODS.includes(request.method)) return refuseOffTheWire(request);
+		return await next(request);
+	};
+}
 async function ensureStubServer() {
 	if (serverInstance !== null) return serverInstance;
 	const { setupServer } = await loadMsw();
 	const server = setupServer();
-	server.listen({ onUnhandledRequest: "bypass" });
+	server.listen({ onUnhandledFrame: "bypass" });
+	guardOffTheWireMethods();
 	serverInstance = server;
-	installedFetch = globalThis.fetch;
-	globalThis.fetch = owningBodies(refusingWhatFetchRefuses(installedFetch));
 	return server;
 }
 /** The trailing catch-all records any request no stub accepted; the chain's pipeline rethrows it. */
 async function registerStubs(stubs) {
 	const server = await ensureStubServer();
 	const { msw } = await loadMsw();
-	const { handlers, violation } = buildStubHandlers(msw, stubs);
+	const { handlers, refuse, violation } = buildStubHandlers(msw, stubs);
 	server.use(...handlers);
+	refuseOffTheWire = (request) => refuse(offTheWireError(request), `unreadable request ${request.method} ${request.url}`);
 	return {
 		cleanup: () => {
+			refuseOffTheWire = null;
 			server.resetHandlers();
 		},
 		violation

package/dist/shared-temp-root.global-setup.js

@@ -1,17 +1,10 @@
 import { a as EVIDENCE_DIR } from "./shared-artifacts.js";
 import { t as setupEntry } from "./shared-setup-entry.js";
+import { t as processAlive } from "./shared-process-alive.js";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 //#region src/chain/paths/run-folders.ts
-function isAlive(pid) {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (error) {
-		return error instanceof Error && "code" in error && error.code === "EPERM";
-	}
-}
 function runOf(entry) {
 	const pid = Number(entry.split("-")[0]);
 	return Number.isInteger(pid) && pid > 0 ? pid : null;
@@ -20,7 +13,7 @@ function runOf(entry) {
 function sweepOrphanRoots(parent) {
 	for (const entry of readdirSync(parent)) {
 		const pid = runOf(entry);
-		if (pid !== null && !isAlive(pid)) rmSync(join(parent, entry), {
+		if (pid !== null && !processAlive(pid)) rmSync(join(parent, entry), {
 			force: true,
 			recursive: true
 		});
@@ -31,7 +24,7 @@ function sweepFinishedEvidence(folder) {
 	if (!existsSync(folder)) return;
 	for (const entry of readdirSync(folder)) {
 		const pid = runOf(entry);
-		if (pid === null || !isAlive(pid)) rmSync(join(folder, entry), {
+		if (pid === null || !processAlive(pid)) rmSync(join(folder, entry), {
 			force: true,
 			recursive: true
 		});

package/dist/shared-testcontainers.adapter.js

@@ -1,10 +1,118 @@
 import { t as isRecord } from "./shared-json-shape.js";
-import { t as invariant } from "./shared-refusal.js";
+import { n as refusal, t as invariant } from "./shared-refusal.js";
+import { t as listenedPort } from "./shared-listened-port.js";
 import { t as loadPeer } from "./shared-peer.js";
+import { execSync } from "node:child_process";
 import { once } from "node:events";
 import { createServer } from "node:http";
 import { text } from "node:stream/consumers";
 import { hostname } from "node:os";
+//#region src/services/containers/docker-cli.ts
+const DEFAULT_TIMEOUT = 1e4;
+/** How every refusal of a run that asked for Docker names a daemon that did not answer. */
+const DOCKER_ABSENT = "no Docker daemon answered";
+/** Docker-aware mode reads what the daemon answers: a run where none answers is refused, never passed. */
+function requireDockerDaemon() {
+	try {
+		execSync("docker version --format \"{{.Server.Version}}\"", {
+			stdio: "ignore",
+			timeout: DEFAULT_TIMEOUT
+		});
+	} catch (error) {
+		throw new Error(refusal({
+			fix: "start Docker (Docker Desktop, OrbStack, colima or another) and run again",
+			found: `specification.cli({ docker }) asked for Docker, and ${DOCKER_ABSENT}`,
+			read: "docs/guides/cli-specs.md#docker-aware-mode",
+			why: "Docker-aware mode reads the containers a run spawned, so it needs a Docker daemon."
+		}), { cause: error });
+	}
+}
+function findContainersByLabel(key, value) {
+	try {
+		return execSync(`docker ps -aq -f label=${key}=${value}`, {
+			encoding: "utf8",
+			timeout: DEFAULT_TIMEOUT
+		}).split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+	} catch {
+		return [];
+	}
+}
+/** A field of a value read off docker's JSON or a failed process: absent wherever the value does not hold it. */
+function fieldOf(value, ...keys) {
+	if (typeof value !== "object" || value === null) return;
+	const key = keys.find((candidate) => candidate in value);
+	return key === void 0 ? void 0 : Reflect.get(value, key);
+}
+const streamOf = (error, key) => {
+	const stream = fieldOf(error, key);
+	return typeof stream === "string" ? stream : void 0;
+};
+function inspectContainer(id) {
+	const raw = execSync(`docker inspect ${id}`, {
+		encoding: "utf8",
+		timeout: DEFAULT_TIMEOUT
+	});
+	const parsed = JSON.parse(raw);
+	if (!Array.isArray(parsed)) return parsed;
+	return parsed[0];
+}
+function removeContainers(ids) {
+	if (ids.length === 0) return;
+	try {
+		execSync(`docker rm -f ${ids.join(" ")}`, {
+			encoding: "utf8",
+			stdio: "pipe",
+			timeout: DEFAULT_TIMEOUT
+		});
+	} catch {}
+}
+function containerLogs(id) {
+	try {
+		return execSync(`docker logs ${id}`, {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			timeout: DEFAULT_TIMEOUT
+		});
+	} catch (error) {
+		return streamOf(error, "stdout") ?? streamOf(error, "stderr") ?? "";
+	}
+}
+function readContainerFile(id, path) {
+	return execSync(`docker exec ${id} cat ${JSON.stringify(path)}`, {
+		encoding: "utf8",
+		timeout: DEFAULT_TIMEOUT
+	});
+}
+function execInContainer(id, argv) {
+	try {
+		const quoted = argv.map((a) => JSON.stringify(a)).join(" ");
+		return {
+			exitCode: 0,
+			stderr: "",
+			stdout: execSync(`docker exec ${id} ${quoted}`, {
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				timeout: DEFAULT_TIMEOUT
+			})
+		};
+	} catch (error) {
+		const status = fieldOf(error, "status");
+		return {
+			exitCode: typeof status === "number" ? status : 1,
+			stderr: streamOf(error, "stderr") ?? (error instanceof Error ? error.message : ""),
+			stdout: streamOf(error, "stdout") ?? ""
+		};
+	}
+}
+//#endregion
 //#region src/services/containers/run-containers.ts
 function canonical(value) {
 	return isRecord(value) ? Object.fromEntries(Object.entries(value).toSorted(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, canonical(entry)])) : value;
@@ -95,17 +203,12 @@ async function serveContainers(containers) {
 	const server = createServer((request, response) => {
 		respond(containers, request, response);
 	});
-	server.listen(0, "127.0.0.1");
-	await once(server, "listening");
-	const address = server.address();
-	if (address === null || typeof address === "string") throw invariant("the run containers are served on no port");
-	const { port } = address;
 	return {
 		close: async () => {
 			server.close();
 			await once(server, "close");
 		},
-		url: `http://127.0.0.1:${port}`
+		url: `http://127.0.0.1:${await listenedPort(server, { host: "127.0.0.1" })}`
 	};
 }
 //#endregion
@@ -198,6 +301,6 @@ var TestcontainersAdapter = class {
 	}
 };
 //#endregion
-export { field as a, RunContainers as i, REUSED_LABEL as n, serveContainers as o, TestcontainersAdapter as r, OWNER_LABEL as t };
+export { field as a, containerLogs as c, findContainersByLabel as d, inspectContainer as f, requireDockerDaemon as h, RunContainers as i, execInContainer as l, removeContainers as m, REUSED_LABEL as n, serveContainers as o, readContainerFile as p, TestcontainersAdapter as r, DOCKER_ABSENT as s, OWNER_LABEL as t, fieldOf as u };
 
 //# sourceMappingURL=shared-testcontainers.adapter.js.map

package/dist/temp-root.global-setup.js

@@ -1,2 +1 @@
-import { n as setup, r as tempRootSetup, t as TEMP_ROOTS_PARENT } from "./shared-temp-root.global-setup.js";
-export { TEMP_ROOTS_PARENT, setup as default, tempRootSetup };
+export { t as TEMP_ROOTS_PARENT, n as default, r as tempRootSetup } from "./shared-temp-root.global-setup.js";

package/dist/vitest.d.ts

@@ -13,11 +13,18 @@ type SpecificationProjectOptions = {
   /** Raise (or lower) the 30s budget for this project alone: each test's, and each hook's, which tears down what the test stood on. */
   timeout?: number;
 };
-/** What a specification whose runner boots its subject in this process accepts on top. */
-type InProcessProjectOptions = SpecificationProjectOptions & {
-  /** The `*.specification.ts` module its spec files import their runner from: stated, a worker's files share one module graph and the module runs again before each file, so every file still boots its own subject. */
-  runner?: string;
+/** What a specification whose spec files import their runner from its specification modules accepts on top. */
+type RunnerOption = {
+  /** The `*.specification.ts` modules its spec files import their runner from: stated, a worker's files share one module graph and each module runs again before each file, so every file still boots its own subject. */
+  runner?: readonly string[] | string;
 };
+/** What a specification whose runner boots its subject in this process accepts on top. */
+type InProcessProjectOptions = RunnerOption & SpecificationProjectOptions;
+//#endregion
+//#region src/specifications/api/api.project.d.ts
+/** `api()`: the app met through HTTP. */
+type ApiProjectOptions = InProcessProjectOptions;
+export declare function api(options?: ApiProjectOptions): TestProjectInlineConfiguration;
 //#endregion
 //#region src/specifications/cli/documents/literate-plugin.d.ts
 type LiterateOptions = {
@@ -50,23 +57,18 @@ type LiterateDoor = {
   literate?: false | Partial<LiterateOptions>;
 };
 /** `cli()`: a binary, and the documents that specify it. */
-type CliProjectOptions = LiterateDoor & SpecificationProjectOptions;
+type CliProjectOptions = LiterateDoor & RunnerOption & SpecificationProjectOptions;
 /** A cli project: the specification's `.spec.ts` files and its documents (docs/guides/spec-documents.md); the plugin's glob joins this project's include, never the root config. */
 export declare function cli(options?: CliProjectOptions): TestProjectInlineConfiguration;
 //#endregion
-//#region src/specifications/api/api.project.d.ts
-/** `api()`: the app met through HTTP. */
-type ApiProjectOptions = InProcessProjectOptions;
-export declare function api(options?: ApiProjectOptions): TestProjectInlineConfiguration;
-//#endregion
 //#region src/specifications/component/component.project.d.ts
 type ComponentOptions = {
   /** Freeze the page's `Date` for every render of the project. */
   clock?: string;
   /** `Accept-Language` and `Intl` locale of the page. Default `'en-US'`. */
   locale?: string;
-  /** The directory `vite` and `wrap` resolve against; defaults to the calling file's. */
-  root?: string;
+  /** The directory `vite` and `wrap` resolve against, absolute; `vitestConfig` hands it the project root, or the `root` a declared project states read from it. */
+  root: string;
   /** IANA zone the page's `Date` reports in. Default `'UTC'`. */
   timezone?: string;
   /** The app's Vite pipeline: a config path, the object, or a framework's function. Only the pipeline is adopted. */
@@ -82,7 +84,7 @@ type ComponentOptions = {
 /** `component()`: rendered units, in the `__tests__/` of the folder of the components they cover; under a specs tree, beside them. */
 type ComponentProjectOptions = ComponentOptions & SpecificationProjectOptions;
 /** A component project: renders in a real Chromium; the default `exclude` keeps it out of `specs/`. */
-export declare function component(options?: ComponentProjectOptions): Promise<TestProjectInlineConfiguration>;
+export declare function component(options: ComponentProjectOptions): Promise<TestProjectInlineConfiguration>;
 //#endregion
 //#region src/specifications/integration/integration.project.d.ts
 /** `integration()`: a module against real services, or against a golden. */
@@ -108,12 +110,12 @@ type MobileProjectOptions = SpecificationProjectOptions & ({
   device?: never;
   root?: never;
 });
-/** A simulator cannot share a machine with itself: serial. A global setup holds one driver session for the run. */
+/** A simulator cannot share a machine with itself: serial, unless `serial: false` states a server that gives every session an app of its own. A global setup holds the run's driver sessions, one per worker. */
 export declare function mobile(options?: MobileProjectOptions): TestProjectInlineConfiguration;
 //#endregion
 //#region src/specifications/website/website.project.d.ts
 /** `website()`: the assembled product, met through a served page. */
-type WebsiteProjectOptions = SpecificationProjectOptions;
+type WebsiteProjectOptions = RunnerOption & SpecificationProjectOptions;
 export declare function website(options?: WebsiteProjectOptions): TestProjectInlineConfiguration;
 //#endregion
 //#region src/vitest/unit.project.d.ts
@@ -128,13 +130,6 @@ type UnitProjectOptions = SpecificationProjectOptions & {
 export declare function unit(options?: UnitProjectOptions): TestProjectInlineConfiguration;
 //#endregion
 //#region src/index.vitest.d.ts
-/** A vite/vitest config, merged over the preset's defaults, plus `literate`. */
-export type SpecConfig = ViteUserConfig & {
-  /** Turns matching `<case>.spec.yaml` files into tests; with `projects`, put the plugin in the collecting project instead. */
-  literate?: LiterateOptions;
-};
-/** The shared vitest config: what you pass is merged over the defaults. */
-export declare function defineSpecConfig(config?: SpecConfig): ViteUserConfig;
 export declare const vitestConfig: (configUrl: string) => Promise<ViteUserConfig>;
 //#endregion
 export type { ApiProjectOptions, CliProjectOptions, ComponentProjectOptions, InProcessProjectOptions, IntegrationProjectOptions, JobProjectOptions, LintProjectOptions, LiterateDoor, LiterateOptions, LiteratePlugin, MobileProjectOptions, SpecificationProjectOptions, UnitProjectOptions, WebsiteProjectOptions };