@jterrazz/test 9.0.0 → 9.2.0

package/dist/index.js

@@ -7,6 +7,7 @@ import { Client } from "pg";
 import { readdir } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
+import { createServer } from "node:net";
 import Database from "better-sqlite3";
 import { mockDeep } from "vitest-mock-extended";
 import MockDatePackage from "mockdate";
@@ -1926,7 +1927,15 @@ async function toMatchRows(received, expected) {
 	};
 }
 async function toBeEmpty(received) {
-	if (!(received instanceof TableAccessor)) throw new TypeError("toBeEmpty: unsupported subject — expected result.table(...).");
+	if (received instanceof TextAccessor) {
+		const content = received.comparableText;
+		const pass = content === "";
+		return {
+			message: () => pass ? `expected ${received.streamName} not to be empty` : `Expected ${received.streamName} to be empty, but it contains:\n${content}`,
+			pass
+		};
+	}
+	if (!(received instanceof TableAccessor)) throw new TypeError("toBeEmpty: unsupported subject — expected result.table(...) or a text accessor.");
 	const rows = await received.query(["*"]);
 	const pass = rows.length === 0;
 	return {
@@ -1988,6 +1997,128 @@ var HttpResult = class extends BaseResult {
 	}
 };
 //#endregion
+//#region src/core/specification/website/result.ts
+/** Result from a raw `.fetch()` action (robots.txt, sitemaps, redirects). */
+var FetchResult = class extends BaseResult {
+	exchange;
+	constructor(options) {
+		super(options);
+		this.exchange = options.exchange;
+	}
+	/** The response body as a text accessor (`toMatch('robots.txt')`, `.grep()`). */
+	get body() {
+		return new TextAccessor(this.exchange.body, "body", this.testDir, { captures: this.captures });
+	}
+	/** Response headers as a flat, lower-cased key-value map. */
+	get headers() {
+		return this.exchange.headers;
+	}
+	/** The response body parsed as JSON. */
+	get json() {
+		return new JsonAccessor(this.exchange.body, this.testDir, void 0, this.captures);
+	}
+	/** The `location` header of a redirect response, or undefined. */
+	get location() {
+		return this.exchange.headers["location"];
+	}
+	/** The HTTP response status code — redirects surface as 3xx, never followed. */
+	get status() {
+		return this.exchange.status;
+	}
+};
+/** Result from a rendered `.visit()` action — the page as a browser saw it. */
+var PageResult = class extends BaseResult {
+	page;
+	constructor(options) {
+		super(options);
+		this.page = options.page;
+	}
+	/** Hreflang alternates declared in the head, keyed by language code. */
+	get alternates() {
+		const alternates = {};
+		for (const link of this.page.links) if (link.rel === "alternate" && link.hreflang) alternates[link.hreflang] = link.href;
+		return alternates;
+	}
+	/** The canonical URL declared in the head, or null. */
+	get canonical() {
+		return this.page.links.find((link) => link.rel === "canonical")?.href ?? null;
+	}
+	/**
+	* The browser console as a stream — one message per line, prefixed by
+	* its type — same shape as `stdout` on a cli result. Assert emptiness
+	* with `toBeEmpty()`, or snapshot with `toMatch('home.console.txt')`.
+	*/
+	get console() {
+		return new TextAccessor(this.page.consoleMessages.map((m) => `[${m.type}] ${m.text}`).join("\n"), "console", this.testDir, { captures: this.captures });
+	}
+	/**
+	* Console messages of type `error` only — the stream you usually want
+	* empty: `expect(result.errors).toBeEmpty()`. Same shape as `stderr` on
+	* a cli result.
+	*/
+	get errors() {
+		return new TextAccessor(this.page.consoleMessages.filter((m) => m.type === "error").map((m) => m.text).join("\n"), "errors", this.testDir, { captures: this.captures });
+	}
+	/**
+	* The document-head projection as a JSON accessor — title, canonical,
+	* hreflang alternates, and named metas — for one golden per page:
+	* `expect(result.head).toMatch('home.head.json')`.
+	*/
+	get head() {
+		const summary = {
+			alternates: this.alternates,
+			canonical: this.canonical,
+			metas: namedMetas(this.page.metas),
+			title: this.page.title
+		};
+		return new JsonAccessor(JSON.stringify(summary), this.testDir, void 0, this.captures);
+	}
+	/** The rendered DOM serialization as a text accessor. */
+	get html() {
+		return new TextAccessor(this.page.html, "html", this.testDir, { captures: this.captures });
+	}
+	/**
+	* Every `application/ld+json` block of the page, parsed, as one JSON
+	* array — `expect(result.jsonLd).toMatch('article.jsonld.json')`.
+	*/
+	get jsonLd() {
+		return new JsonAccessor(`[${this.page.jsonLdBlocks.join(",")}]`, this.testDir, void 0, this.captures);
+	}
+	/** `<link>` elements of the head, in DOM order. */
+	get links() {
+		return this.page.links;
+	}
+	/** The content of a named meta — `meta('description')`, `meta('og:image')`. */
+	meta(name) {
+		return this.page.metas.find((m) => m.name === name || m.property === name)?.content;
+	}
+	/** HTTP status of the main document response. */
+	get status() {
+		return this.page.status;
+	}
+	/** Rendered body text as a text accessor. */
+	get content() {
+		return new TextAccessor(this.page.text, "text", this.testDir, { captures: this.captures });
+	}
+	/** The document title as a text accessor. */
+	get title() {
+		return new TextAccessor(this.page.title, "title", this.testDir, { captures: this.captures });
+	}
+	/** Final URL after redirects. */
+	get url() {
+		return this.page.url;
+	}
+};
+/** Collapse meta elements into a flat name → content map (property wins the key). */
+function namedMetas(metas) {
+	const named = {};
+	for (const meta of metas) {
+		const key = meta.name ?? meta.property;
+		if (key) named[key] = meta.content;
+	}
+	return named;
+}
+//#endregion
 //#region src/core/specification/shared/binding.ts
 /**
 * Compose-binding resolution and the case conversions it shares with the
@@ -2316,6 +2447,38 @@ var SpecificationBuilder = class {
 		});
 	}
 	/**
+	* Perform one raw HTTP GET against the website under test and resolve
+	* with the exchange. Redirects are never followed — a 308 IS the result,
+	* with its `location` readable on the result. The scalpel for wire-level
+	* surfaces: robots.txt, sitemaps, llms.txt, redirect policies.
+	*
+	* @example
+	*   const result = await website.fetch('/robots.txt');
+	*   expect(result.status).toBe(200);
+	*   expect(result.body).toMatch('robots.txt');
+	*/
+	fetch(path) {
+		return this.executeSetup(null, () => this.runFetchAction(path));
+	}
+	/**
+	* Render the page in the shared browser instance and resolve with the
+	* captured document — rendered title, head elements, JSON-LD blocks,
+	* body text, console errors. One browser per runner; each visit gets a
+	* fresh, isolated context.
+	*
+	* @example
+	*   const result = await website.visit('/articles');
+	*   expect(result.head).toMatch('articles.head.json');
+	*
+	*   const result = await website.visit('/', async (visitor) => {
+	*       await visitor.click(link('Articles'));
+	*   });
+	*   expect(result.url).toContain('/articles');
+	*/
+	visit(path, scenario) {
+		return this.executeSetup(null, () => this.runVisitAction(path, scenario));
+	}
+	/**
 	* Execute the named job registered via the `jobs` option of
 	* `specification.jobs()` and resolve with the result.
 	*
@@ -2404,6 +2567,49 @@ var SpecificationBuilder = class {
 			testDir: this.testDir
 		});
 	}
+	async runFetchAction(path) {
+		const baseUrl = this.requireBaseUrl("fetch");
+		const headers = Object.keys(this.requestHeaders).length > 0 ? this.requestHeaders : void 0;
+		const response = await fetch(`${baseUrl}${path}`, {
+			headers,
+			redirect: "manual"
+		});
+		const body = await response.text();
+		const responseHeaders = {};
+		response.headers.forEach((value, key) => {
+			responseHeaders[key] = value;
+		});
+		return new FetchResult({
+			config: this.config,
+			exchange: {
+				body,
+				headers: responseHeaders,
+				status: response.status
+			},
+			testDir: this.testDir
+		});
+	}
+	async runVisitAction(path, scenario) {
+		const baseUrl = this.requireBaseUrl("visit");
+		if (!this.config.browser) throw new Error(".visit() requires a browser adapter (use specification.website())");
+		const browser = await this.config.browser();
+		const headers = Object.keys(this.requestHeaders).length > 0 ? this.requestHeaders : void 0;
+		const page = await browser.open(`${baseUrl}${path}`, {
+			baseUrl,
+			external: this.config.external ?? "allow",
+			headers,
+			scenario
+		});
+		return new PageResult({
+			config: this.config,
+			page,
+			testDir: this.testDir
+		});
+	}
+	requireBaseUrl(method) {
+		if (!this.config.baseUrl) throw new Error(`.${method}() requires a website under test (use specification.website())`);
+		return this.config.baseUrl;
+	}
 	async runJobAction(name) {
 		if (!this.config.jobs?.length) throw new Error("Job actions require jobs registered via the jobs option of specification.jobs()");
 		const job = this.config.jobs.find((j) => j.name === name);
@@ -2512,6 +2718,17 @@ function createJobsFacet(config) {
 	};
 }
 /**
+* Create the `website` facet bound to the given adapter configuration.
+*/
+function createWebsiteFacet(config) {
+	const start = () => new SpecificationBuilder(config, getCallerDir());
+	return {
+		fetch: (path) => start().fetch(path),
+		headers: (headers) => start().headers(headers),
+		visit: (path, scenario) => start().visit(path, scenario)
+	};
+}
+/**
 * Create the `cli` facet bound to the given adapter configuration.
 */
 function createCliFacet(config) {
@@ -2900,7 +3117,7 @@ function isTransientConnectionError(error) {
 	const cause = error.cause;
 	return cause?.code !== void 0 && TRANSIENT_CONNECTION_CODES.has(cause.code) || error.message.includes("fetch failed");
 }
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const delay$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
 * Server adapter that sends real HTTP requests via the Fetch API.
 * Used by the `e2e()` specification runner to hit a live server.
@@ -2941,7 +3158,7 @@ var FetchAdapter = class {
 			return await fetch(url, init);
 		} catch (error) {
 			if (attempt >= MAX_ATTEMPTS || !isTransientConnectionError(error)) throw error;
-			await delay(BASE_BACKOFF_MS * 2 ** (attempt - 1));
+			await delay$1(BASE_BACKOFF_MS * 2 ** (attempt - 1));
 		}
 	}
 };
@@ -3004,7 +3221,7 @@ async function startApi(options) {
 //#region src/core/specification/cli/exec.adapter.ts
 const DEFAULT_WATCH_TIMEOUT = 1e4;
 /** Grace period between SIGTERM and the SIGKILL escalation. */
-const KILL_GRACE_MS = 2e3;
+const KILL_GRACE_MS$1 = 2e3;
 /**
 * Build a child-process env from the parent env plus user overrides.
 * `null` overrides delete keys (e.g. `INIT_CWD: null`).
@@ -3047,7 +3264,7 @@ function observeProcess(child, options) {
 			child.kill("SIGTERM");
 			killTimer = setTimeout(() => {
 				if (!exited) child.kill("SIGKILL");
-			}, KILL_GRACE_MS);
+			}, KILL_GRACE_MS$1);
 		};
 		const finish = (exitCode) => {
 			if (resolved) return;
@@ -3206,6 +3423,164 @@ async function startJobs(options) {
 	};
 }
 //#endregion
+//#region src/core/specification/website/serve.adapter.ts
+/** Grace period between SIGTERM and the SIGKILL escalation. */
+const KILL_GRACE_MS = 2e3;
+const DEFAULT_READY_TIMEOUT = 3e4;
+const READY_POLL_INTERVAL_MS = 250;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Ask the OS for a free TCP port. */
+function findFreePort() {
+	return new Promise((resolve, reject) => {
+		const server = createServer();
+		server.listen(0, () => {
+			const address = server.address();
+			if (address === null || typeof address === "string") {
+				server.close();
+				reject(/* @__PURE__ */ new Error("could not determine a free port"));
+				return;
+			}
+			const { port } = address;
+			server.close(() => resolve(port));
+		});
+		server.on("error", reject);
+	});
+}
+/**
+* Starts the site under test as a child process and waits until it answers
+* HTTP. Any HTTP status counts as ready — a 404 on the ready path is still a
+* listening server; only connection failures keep the poll going.
+*
+* The child runs through the shell in its own process group (POSIX) so
+* `stop()` can terminate the whole tree — a `next start` grandchild must not
+* outlive the spec run (same escalation as the cli exec adapter: SIGTERM,
+* then SIGKILL after a 2 s grace).
+*/
+var ServeAdapter = class {
+	child = null;
+	options;
+	output = "";
+	root;
+	constructor(options, root) {
+		this.options = options;
+		this.root = root;
+	}
+	/** Start the server and resolve with its base URL once it answers HTTP. */
+	async start() {
+		const port = this.options.port ?? await findFreePort();
+		const baseUrl = `http://127.0.0.1:${port}`;
+		const readyUrl = `${baseUrl}${this.options.ready ?? "/"}`;
+		const timeout = this.options.timeout ?? DEFAULT_READY_TIMEOUT;
+		this.child = spawn(this.options.command, [], {
+			cwd: this.root,
+			detached: process.platform !== "win32",
+			env: {
+				...process.env,
+				PORT: String(port)
+			},
+			shell: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		this.child.stdout?.on("data", (data) => {
+			this.output += data.toString();
+		});
+		this.child.stderr?.on("data", (data) => {
+			this.output += data.toString();
+		});
+		let exited = false;
+		this.child.on("exit", () => {
+			exited = true;
+		});
+		const deadline = Date.now() + timeout;
+		for (;;) {
+			if (exited) throw new Error(`specification.website(): server command exited before answering HTTP.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
+			try {
+				await fetch(readyUrl, { redirect: "manual" });
+				return baseUrl;
+			} catch {
+				if (Date.now() >= deadline) {
+					await this.stop();
+					throw new Error(`specification.website(): server did not answer on ${readyUrl} within ${timeout}ms.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
+				}
+				await delay(READY_POLL_INTERVAL_MS);
+			}
+		}
+	}
+	/** Terminate the server process group (idempotent). */
+	async stop() {
+		const child = this.child;
+		if (!child) return;
+		this.child = null;
+		await new Promise((resolve) => {
+			let exited = false;
+			child.on("exit", () => {
+				exited = true;
+				resolve();
+			});
+			if (child.exitCode !== null || child.signalCode !== null) {
+				resolve();
+				return;
+			}
+			this.kill(child, "SIGTERM");
+			setTimeout(() => {
+				if (!exited) {
+					this.kill(child, "SIGKILL");
+					resolve();
+				}
+			}, KILL_GRACE_MS).unref?.();
+		});
+	}
+	/** Group-aware kill: signal the process group, fall back to the child. */
+	kill(child, signal) {
+		if (child.pid !== void 0 && process.platform !== "win32") try {
+			process.kill(-child.pid, signal);
+			return;
+		} catch {}
+		child.kill(signal);
+	}
+};
+//#endregion
+//#region src/core/specification/website/start-website.ts
+async function startWebsite(options) {
+	const callerDir = getCallerDir();
+	await registerMatchers();
+	let serve = null;
+	let baseUrl;
+	if (options.server) {
+		const root = resolveRoot(options.root, callerDir);
+		serve = new ServeAdapter(options.server, root);
+		baseUrl = await serve.start();
+	} else baseUrl = options.url.replace(/\/$/, "");
+	let browser = null;
+	const getBrowser = async () => {
+		if (!browser) {
+			const { PlaywrightAdapter } = await import("./playwright.adapter.js");
+			browser = new PlaywrightAdapter();
+		}
+		return browser;
+	};
+	const config = {
+		baseUrl,
+		browser: getBrowser,
+		external: options.external ?? (options.server ? "block" : "allow")
+	};
+	return {
+		cleanup: async () => {
+			if (browser) {
+				await browser.close();
+				browser = null;
+			}
+			if (serve) await serve.stop();
+		},
+		url: baseUrl,
+		website: createWebsiteFacet(config)
+	};
+}
+//#endregion
 //#region src/core/specification/shared/specification.ts
 /**
 * The three specification constructors (CONVENTIONS A2) — created in a
@@ -3250,9 +3625,55 @@ const specification = {
 	* Test background jobs. Jobs run in-process by definition — no HTTP
 	* server, no mode. `.trigger(name)` is the terminal action.
 	*/
-	jobs: startJobs
+	jobs: startJobs,
+	/**
+	* Test a deployed or locally-served website. `server` starts the site
+	* (a shell command receiving `PORT`); `url` targets a running one.
+	* `.visit(path)` renders the page in a single shared browser instance;
+	* `.fetch(path)` performs one raw HTTP exchange (redirects never
+	* followed).
+	*/
+	website: startWebsite
 };
 //#endregion
+//#region src/core/specification/website/elements.ts
+/**
+* The element vocabulary — user-facing descriptors for visit scenarios.
+* Reads like English (`click(link('Articles'))`), translates to
+* accessibility-first locators in the browser integration. CSS/XPath is
+* deliberately not expressible; `testId()` is the single escape hatch.
+*/
+/** A button (or element with the button role), by accessible name. */
+const button = (name) => ({
+	kind: "button",
+	name
+});
+/** A form field, by label. */
+const field = (label) => ({
+	kind: "field",
+	name: label
+});
+/** A heading, by accessible name. */
+const heading = (name) => ({
+	kind: "heading",
+	name
+});
+/** A link, by accessible name. */
+const link = (name) => ({
+	kind: "link",
+	name
+});
+/** An element containing the given text. */
+const content = (value) => ({
+	kind: "text",
+	name: value
+});
+/** The escape hatch: an element by `data-testid`. Prefer user-facing elements. */
+const testId = (id) => ({
+	kind: "testId",
+	name: id
+});
+//#endregion
 //#region src/integrations/sqlite/sqlite.ts
 var SqliteHandle = class {
 	type = "sqlite";
@@ -3825,4 +4246,4 @@ registerComposeServiceFactory("postgres", (service) => postgres({
 }));
 registerComposeServiceFactory("redis", (service) => redis({ composeService: service.name }));
 //#endregion
-export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, ResponseAccessor, TableAccessor, TextAccessor, anthropic, defineContract, findContainersByLabel, http, inspectContainer, match, mockOf, mockOfDate, openai, postgres, redis, removeContainers, specification, sqlite, text };
+export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ResponseAccessor, TableAccessor, TextAccessor, anthropic, button, content, defineContract, field, findContainersByLabel, heading, http, inspectContainer, link, match, mockOf, mockOfDate, openai, postgres, redis, removeContainers, specification, sqlite, testId, text };