@jterrazz/test 16.1.1 → 18.0.0

package/dist/shared-pause.js

@@ -0,0 +1,22 @@
+//#region src/chain/pause.ts
+async function pause(ms) {
+	if (ms <= 0) return;
+	await new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+/** Asks `probe` until it answers something other than `undefined`, which it hands back, or answers `undefined` once `timeout` has passed. Measured on `performance.now()`, so `clock.at()`, which fakes `Date`, cannot freeze it. */
+async function untilDeadline(probe, { interval = 0, timeout, wait }) {
+	const deadline = performance.now() + timeout;
+	for (;;) {
+		const answer = await probe();
+		if (answer !== void 0) return answer;
+		const remaining = deadline - performance.now();
+		if (remaining <= 0) return;
+		await (wait === void 0 ? pause(interval) : wait(remaining));
+	}
+}
+//#endregion
+export { untilDeadline as n, pause as t };
+
+//# sourceMappingURL=shared-pause.js.map

package/dist/shared-peer.js

@@ -0,0 +1,88 @@
+import { n as installRootOf } from "./shared-resolve.js";
+import { n as refusal } from "./shared-refusal.js";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+//#region src/services/peer.ts
+const INSTALLERS = [
+	{
+		command: "bun add -d",
+		lockfile: "bun.lock",
+		name: "bun"
+	},
+	{
+		command: "bun add -d",
+		lockfile: "bun.lockb",
+		name: "bun"
+	},
+	{
+		command: "pnpm add -D",
+		lockfile: "pnpm-lock.yaml",
+		name: "pnpm"
+	},
+	{
+		command: "yarn add -D",
+		lockfile: "yarn.lock",
+		name: "yarn"
+	},
+	{
+		command: "npm install -D",
+		lockfile: "package-lock.json",
+		name: "npm"
+	}
+];
+const DEFAULT_INSTALLER = {
+	command: "npm install -D",
+	name: "npm"
+};
+const BUILDERS = {
+	bun: (peer) => `bun pm trust ${peer}`,
+	npm: (peer) => `npm install-scripts approve ${peer} && npm rebuild ${peer}`,
+	pnpm: (peer) => `add "${peer}" to \`onlyBuiltDependencies\` in package.json (or \`only-built-dependencies\` in .npmrc), then \`pnpm rebuild ${peer}\``,
+	yarn: (peer) => `yarn rebuild ${peer}`
+};
+const UNBUILT = /could not locate the bindings file|\.node['"]?$|invalid elf header|was compiled against a different node/iu;
+function isUnbuilt(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return UNBUILT.test(message);
+}
+const NATIVE_PEERS = /* @__PURE__ */ new Set(["better-sqlite3"]);
+function installerAt(from) {
+	const root = installRootOf(from);
+	if (root === void 0) return DEFAULT_INSTALLER;
+	return INSTALLERS.find((candidate) => existsSync(resolve(root, candidate.lockfile))) ?? DEFAULT_INSTALLER;
+}
+function buildNote(peer, manager) {
+	if (!NATIVE_PEERS.has(peer) || manager !== "pnpm") return "";
+	return `; under pnpm the binding is not built unless the package is listed: add "${peer}" to \`onlyBuiltDependencies\` in package.json (or \`only-built-dependencies\` in .npmrc) and reinstall`;
+}
+/** A binding the package manager never built surfaces as a `bindings` stack trace; this turns it into a refusal naming the peer and the command. */
+function requireBuiltPeer(peer, what, use, from = process.cwd()) {
+	try {
+		use();
+	} catch (error) {
+		if (!isUnbuilt(error)) throw error;
+		const { name } = installerAt(from);
+		throw new Error(refusal({
+			fix: BUILDERS[name](peer),
+			found: `${what} found \`${peer}\`, and its native binding is not built`,
+			read: "docs/start/set-up-a-project.md#what-to-install",
+			why: `A native peer is built by its install script, and ${name} runs a dependency's install script only once it is told to.`
+		}), { cause: error });
+	}
+}
+/** `load` is the caller's own `import('<peer>')`: the bundler and the resolver need to see the bare specifier. */
+async function loadPeer(peer, what, load, from = process.cwd()) {
+	try {
+		return await load();
+	} catch (error) {
+		const { command, name } = installerAt(from);
+		throw new Error(refusal("seam-is-an-optional-peer", {
+			fix: `${command} ${peer}${buildNote(peer, name)}`,
+			found: `${what} requires \`${peer}\`, and it is not installed`
+		}), { cause: error });
+	}
+}
+//#endregion
+export { requireBuiltPeer as n, loadPeer as t };
+
+//# sourceMappingURL=shared-peer.js.map

package/dist/shared-playwright.adapter.js

@@ -0,0 +1,328 @@
+import { n as refusal } from "./shared-refusal.js";
+import { n as untilDeadline } from "./shared-pause.js";
+import { d as evidenceFile } from "./shared-artifacts.js";
+import { c as scopeChain } from "./shared-landmarks.js";
+import { n as CANDIDATE_LIMITS, o as ambiguousTargetError, r as candidatesOf, s as asWritten, t as scenarioFailure } from "./shared-scenario-failure.js";
+//#region src/specifications/website/browser/page-scripts.ts
+function extractPage() {
+	const links = [...document.querySelectorAll("link")].map((link) => ({
+		href: link.href,
+		hreflang: link.hreflang || void 0,
+		rel: link.rel,
+		type: link.type || void 0
+	}));
+	const metas = [...document.querySelectorAll("meta")].map((meta) => ({
+		content: meta.content,
+		name: meta.name || void 0,
+		property: meta.getAttribute("property") ?? void 0
+	}));
+	const jsonLdBlocks = [...document.querySelectorAll("script[type=\"application/ld+json\"]")].map((script) => script.textContent ?? "");
+	return {
+		html: document.documentElement.outerHTML,
+		jsonLdBlocks,
+		links,
+		metas,
+		text: document.body?.innerText ?? "",
+		title: document.title
+	};
+}
+function seedStorage(state) {
+	if (state === "throws") {
+		for (const store of ["localStorage", "sessionStorage"]) Object.defineProperty(globalThis, store, {
+			configurable: true,
+			get: () => {
+				throw new DOMException("The operation is insecure.", "SecurityError");
+			}
+		});
+		return;
+	}
+	for (const [store, entries] of [["localStorage", state.local], ["sessionStorage", state.session]]) for (const [key, value] of Object.entries(entries ?? {})) try {
+		if (globalThis[store].getItem(key) === null) globalThis[store].setItem(key, value);
+	} catch {}
+}
+//#endregion
+//#region src/specifications/website/browser/shared-browser.ts
+/** Launched on the first ask, again once disconnected; a failed launch is not kept. */
+function createSharedBrowser(launch) {
+	let shared;
+	const attempt = async () => {
+		try {
+			const browser = await launch();
+			browser.on("disconnected", () => {
+				shared = void 0;
+			});
+			return browser;
+		} catch (error) {
+			shared = void 0;
+			throw error;
+		}
+	};
+	return async () => {
+		shared ??= attempt();
+		return await shared;
+	};
+}
+//#endregion
+//#region src/specifications/website/browser/website-visitor.ts
+const VALUE_TIMEOUT_MS = 3e4;
+const VALUE_POLL_MS = 100;
+const FIELD_ROLES = [
+	"checkbox",
+	"combobox",
+	"radio",
+	"searchbox",
+	"slider",
+	"spinbutton",
+	"switch",
+	"textbox"
+];
+function locate(root, target) {
+	const scope = target.scope ? locate(root, target.scope) : root;
+	const exact = target.exact ?? true;
+	const name = target.name ?? "";
+	if (target.kind === "field") {
+		let field = scope.getByLabel(name, { exact });
+		for (const role of FIELD_ROLES) field = field.or(scope.getByRole(role, {
+			exact,
+			name
+		}));
+		return field;
+	}
+	if (target.kind === "testId") return scope.getByTestId(name);
+	if (target.kind === "text") return scope.getByText(name, { exact });
+	return scope.getByRole(target.kind, target.name === void 0 ? { exact } : {
+		exact,
+		name: target.name
+	});
+}
+function isStrictViolation(error) {
+	return error instanceof Error && error.message.includes("strict mode violation");
+}
+async function act(page, target, action) {
+	try {
+		return await action(locate(page, target));
+	} catch (error) {
+		if (!isStrictViolation(error)) throw error;
+		const culprit = await findAmbiguousLevel(page, target);
+		const matches = await locate(page, culprit).evaluateAll(candidatesOf, CANDIDATE_LIMITS);
+		throw ambiguousTargetError({
+			target: culprit,
+			matches,
+			url: page.url()
+		});
+	}
+}
+async function findAmbiguousLevel(page, target) {
+	for (const level of scopeChain(target).slice(0, -1)) if (await locate(page, level).count() > 1) return level;
+	return target;
+}
+function stateOnly(page, locator, target) {
+	if (target.focused === true) return locator.and(page.locator(":focus"));
+	if (target.disabled !== void 0) return locator.and(page.locator(target.disabled ? ":disabled" : ":enabled"));
+	if (target.selected !== void 0) return locator.and(page.locator(target.selected ? ":checked" : ":not(:checked)"));
+	return null;
+}
+function byPresence(target) {
+	return target.kind === "option";
+}
+async function currentValue(locator) {
+	try {
+		return await locator.inputValue({ timeout: VALUE_POLL_MS });
+	} catch (error) {
+		if (isStrictViolation(error)) throw error;
+		return null;
+	}
+}
+async function waitForValue(locator, target, wanted, timeout = VALUE_TIMEOUT_MS) {
+	const value = target.value ?? "";
+	let actual = null;
+	if (await untilDeadline(async () => {
+		actual = await currentValue(locator);
+		return actual === value === wanted || void 0;
+	}, {
+		interval: VALUE_POLL_MS,
+		timeout
+	}) === void 0) throw new Error(refusal({
+		fix: "correct the value the scenario states, or what the page puts in the field",
+		found: `${asWritten(target)} ${wanted ? "never held" : "still holds"} ${JSON.stringify(value)}${actual === null ? " (it is not on the page)" : `, it holds ${JSON.stringify(actual)}`}`,
+		read: "docs/reference/visitor.md#see-and-gone-are-the-synchronization",
+		why: "A verb waits for what it states to hold, within its budget, and never sleeps."
+	}));
+}
+async function settle(page, locator, target, present) {
+	if (target.value !== void 0) {
+		await waitForValue(locator, target, present);
+		return;
+	}
+	const narrowed = stateOnly(page, locator, target);
+	if (narrowed !== null) {
+		await narrowed.waitFor({ state: present ? "attached" : "detached" });
+		return;
+	}
+	const shown = present ? "visible" : "hidden";
+	await locator.waitFor({ state: byPresence(target) ? present ? "attached" : "detached" : shown });
+}
+function createVisitor(page, baseUrl) {
+	return {
+		check: async (target) => {
+			await act(page, target, async (locator) => {
+				await locator.check();
+			});
+		},
+		click: async (target) => {
+			await act(page, target, async (locator) => {
+				await locator.click();
+			});
+		},
+		fill: async (target, value) => {
+			await act(page, target, async (locator) => {
+				await locator.fill(value);
+			});
+		},
+		goto: async (path) => {
+			await page.goto(`${baseUrl}${path}`, { waitUntil: "load" });
+		},
+		hover: async (target) => {
+			await act(page, target, async (locator) => {
+				await locator.hover();
+			});
+		},
+		press: async (key) => {
+			await page.keyboard.press(key);
+		},
+		gone: async (target) => {
+			await act(page, target, async (locator) => {
+				await settle(page, locator, target, false);
+			});
+		},
+		see: async (target) => {
+			await act(page, target, async (locator) => {
+				await settle(page, locator, target, true);
+			});
+		},
+		select: async (target, option) => {
+			await act(page, target, async (locator) => await locator.selectOption(option));
+		}
+	};
+}
+//#endregion
+//#region src/specifications/website/browser/playwright.adapter.ts
+const LAUNCH_OPTIONS = {
+	channel: "chromium-headless-shell",
+	headless: true
+};
+async function launchChromium() {
+	let chromium;
+	try {
+		({chromium} = await import("playwright"));
+	} catch {
+		throw new Error(refusal("seam-is-an-optional-peer", {
+			fix: "npm install -D playwright && npx playwright install chromium",
+			found: ".visit() requires `playwright`, and it is not installed"
+		}));
+	}
+	return await chromium.launch(LAUNCH_OPTIONS);
+}
+/** invariant: with `'block'`, requests leaving the site are aborted; the stub backend stays reachable through `allowedOrigins`. */
+async function blockExternal(context, options) {
+	const aborted = /* @__PURE__ */ new Set();
+	if (options.external !== "block") return aborted;
+	const allowed = new Set([options.baseUrl, ...options.allowedOrigins ?? []].map((at) => new URL(at).origin));
+	await context.route("**/*", (route) => {
+		const url = route.request().url();
+		if (allowed.has(new URL(url).origin)) route.continue();
+		else {
+			aborted.add(url);
+			route.abort();
+		}
+	});
+	return aborted;
+}
+function recordConsole(page, aborted) {
+	const consoleMessages = [];
+	page.on("console", (message) => {
+		if (message.type() === "error" && aborted.has(message.location().url)) return;
+		consoleMessages.push({
+			text: message.text(),
+			type: message.type()
+		});
+	});
+	page.on("pageerror", (error) => {
+		consoleMessages.push({
+			text: `Uncaught ${error.name}: ${error.message}`,
+			type: "error"
+		});
+	});
+	return consoleMessages;
+}
+const workerBrowsers = /* @__PURE__ */ new Map();
+function workerBrowser(launch) {
+	let shared = workerBrowsers.get(launch);
+	if (shared === void 0) {
+		shared = createSharedBrowser(launch);
+		workerBrowsers.set(launch, shared);
+	}
+	return shared;
+}
+/** One browser per worker, launched lazily; each visit gets a fresh `BrowserContext`. */
+var PlaywrightAdapter = class {
+	browser;
+	contexts = /* @__PURE__ */ new Set();
+	constructor(options = {}) {
+		this.browser = workerBrowser(options.launch ?? launchChromium);
+	}
+	async close() {
+		const open = [...this.contexts];
+		this.contexts.clear();
+		await Promise.all(open.map(async (context) => {
+			await context.close();
+		}));
+	}
+	async open(url, options) {
+		const context = await (await this.browser()).newContext({ extraHTTPHeaders: options.headers ?? {} });
+		this.contexts.add(context);
+		try {
+			const aborted = await blockExternal(context, options);
+			if (options.storage !== void 0) await context.addInitScript(seedStorage, options.storage);
+			const page = await context.newPage();
+			if (options.clock !== void 0) await page.clock.setFixedTime(new Date(options.clock));
+			const consoleMessages = recordConsole(page, aborted);
+			const response = await page.goto(url, { waitUntil: "load" });
+			if (options.scenario) try {
+				await options.scenario(createVisitor(page, options.baseUrl));
+			} catch (error) {
+				const evidence = await this.captureEvidence(page);
+				throw scenarioFailure(error, evidence, "visit");
+			}
+			const extraction = await page.evaluate(extractPage);
+			const tree = await page.locator("body").ariaSnapshot();
+			return {
+				consoleMessages,
+				status: response?.status() ?? 0,
+				tree,
+				url: page.url(),
+				...extraction
+			};
+		} finally {
+			this.contexts.delete(context);
+			await context.close();
+		}
+	}
+	/** Screenshot the failing state into the evidence folder; never masks the original error. */
+	async captureEvidence(page) {
+		try {
+			const path = evidenceFile("website");
+			await page.screenshot({
+				fullPage: true,
+				path
+			});
+			return path;
+		} catch {
+			return null;
+		}
+	}
+};
+//#endregion
+export { PlaywrightAdapter };
+
+//# sourceMappingURL=shared-playwright.adapter.js.map

package/dist/shared-process-alive.js

@@ -0,0 +1,13 @@
+//#region src/chain/process-alive.ts
+function processAlive(pid, probe = (target) => process.kill(target, 0)) {
+	try {
+		probe(pid);
+		return true;
+	} catch (error) {
+		return Reflect.get(new Object(error), "code") !== "ESRCH";
+	}
+}
+//#endregion
+export { processAlive as t };
+
+//# sourceMappingURL=shared-process-alive.js.map

package/dist/shared-process.adapter.js

@@ -0,0 +1,74 @@
+import { t as ServedProcess } from "./shared-serve.js";
+import { n as refusal } from "./shared-refusal.js";
+//#region src/services/process/process.adapter.ts
+async function nothingToIsolate() {}
+var ProcessHandle = class {
+	/** Embedded: nothing to pull, nothing to run in a container. */
+	defaultImage = "";
+	defaultPort = 0;
+	environment = {};
+	type = "process";
+	serviceName = null;
+	connectionString = "";
+	started = false;
+	served = null;
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	buildConnectionString(host, port) {
+		return `http://${host}:${port}`;
+	}
+	createDatabaseAdapter() {
+		return null;
+	}
+	async healthcheck() {}
+	async initialize() {}
+	/** Isolation is the run's: one child per evaluation of the specification module, told apart by the minted id. */
+	isolation() {
+		return {
+			acquire: nothingToIsolate,
+			release: nothingToIsolate,
+			reset: nothingToIsolate
+		};
+	}
+	async reset() {}
+	/** Spawn it and wait until it answers; `services` is every sibling, already started. */
+	async spawnWith(root, services, runId) {
+		const stated = typeof this.options.env === "function" ? this.options.env(services) : this.options.env;
+		this.served = new ServedProcess(this.options, root, "process", {
+			...stated,
+			TEST_RUN_ID: runId
+		});
+		this.connectionString = await this.served.start();
+		this.started = true;
+	}
+	/** Terminate the process group. Idempotent. */
+	async shutdown() {
+		await this.served?.stop();
+		this.served = null;
+		this.started = false;
+	}
+	/** What it was declared as: what a specification reads to start it in a slot of its own. */
+	get spec() {
+		return this.options;
+	}
+	/** The base URL it came up on, known only once it is started. */
+	get url() {
+		if (!this.started) throw new Error(refusal({
+			fix: "read it from the started services record (`env: (services) => ...` or `server: (services) => ...`), never at declaration time",
+			found: "process().url read before the process was ready",
+			read: "docs/reference/services.md#process-the-one-shape-an-external-process-takes",
+			why: "A process's URL is known once it is ready."
+		}));
+		return this.connectionString;
+	}
+};
+/** Declare an external process the framework owns for the life of the specification. */
+function processService(options) {
+	return new ProcessHandle(options);
+}
+//#endregion
+export { processService as n, ProcessHandle as t };
+
+//# sourceMappingURL=shared-process.adapter.js.map

package/dist/shared-record-key.js

@@ -0,0 +1,13 @@
+//#region lint/kit/project/record-key.ts
+/** `analyticsDb` gives `analytics-db`. */
+function toKebabCase(key) {
+	return key.replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>-$<upper>").toLowerCase();
+}
+/** `analyticsDb` gives `ANALYTICS_DB`, `db-main` gives `DB_MAIN`. */
+function toConstantCase(key) {
+	return key.replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>_$<upper>").replaceAll(/[^A-Za-z0-9]/gu, "_").toUpperCase();
+}
+//#endregion
+export { toKebabCase as n, toConstantCase as t };
+
+//# sourceMappingURL=shared-record-key.js.map

package/dist/shared-refusal.js

@@ -0,0 +1,35 @@
+import { t as CATALOGUE_CHAPTER } from "./shared-chapter.js";
+import { defineInvariant, refusalBlock } from "@jterrazz/typescript/rules";
+//#region src/chain/refusals/rows.ts
+const REFUSAL_WHY = {
+	"database-named-only-when-several-at-runtime": "With two SQL databases or more, a seed or a table names the `database:` it reads, and with exactly one it names none.",
+	"route-written-as-template-at-runtime": "A request written as its route template is handed exactly the parameters the template names.",
+	"disk-named-by-relative-path-at-runtime": "A verb that reads the disk takes a `file()` or a `directory()`, whose path starts with `./` or `../` and ends in `/` exactly when it names a directory.",
+	"one-verb-per-meaning": "`toMatch` on a result the framework produced compares the WHOLE result, to a value written in place or to a `file()`/`directory()` golden.",
+	"network-strict-after-first-stub": "From its first stub, a chain's network is strict: every outgoing request matches a declared stub.",
+	"target-matches-one-element": "A verb acts on exactly ONE element: a target that matches several is refused, never settled by the first.",
+	"seam-is-an-optional-peer": "Every seam is an optional peer of @jterrazz/test, installed by the project that specifies through it.",
+	"no-landmark-on-mobile": "An iOS screen has no ARIA landmark: a mobile verb is scoped with `within(testId(...), ...)`."
+};
+`${REFUSAL_WHY["route-written-as-template-at-runtime"]}`, `${REFUSAL_WHY["database-named-only-when-several-at-runtime"]}`, `${REFUSAL_WHY["disk-named-by-relative-path-at-runtime"]}`, `${REFUSAL_WHY["network-strict-after-first-stub"]}`, `${REFUSAL_WHY["one-verb-per-meaning"]}`, `${REFUSAL_WHY["target-matches-one-element"]}`, `${REFUSAL_WHY["no-landmark-on-mobile"]}`, `${REFUSAL_WHY["seam-is-an-optional-peer"]}`;
+//#endregion
+//#region src/chain/refusals/refusal.ts
+const invariant = defineInvariant({
+	bugOf: "the framework",
+	notOf: "the test",
+	package: "@jterrazz/test"
+});
+function refusal$1(rowOrLesson, teaching) {
+	if (typeof rowOrLesson !== "string") return refusalBlock(rowOrLesson);
+	if (teaching === void 0) throw invariant(`refusal('${rowOrLesson}') was handed no found and no fix for its case`);
+	return refusalBlock({
+		fix: teaching.fix,
+		found: teaching.found,
+		read: `${CATALOGUE_CHAPTER}#${rowOrLesson}`,
+		why: REFUSAL_WHY[rowOrLesson]
+	});
+}
+//#endregion
+export { refusal$1 as n, invariant as t };
+
+//# sourceMappingURL=shared-refusal.js.map

package/dist/shared-resolve.js

@@ -0,0 +1,24 @@
+import { holdsManifest, nearestRoot } from "@jterrazz/typescript/rules";
+import { existsSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+//#region lint/kit/project/resolve.ts
+const installRootOf = (from) => nearestRoot(from, (directory) => existsSync(join(directory, "package.json")));
+function discoverRoot(startDir) {
+	return nearestRoot(startDir, holdsManifest) ?? startDir;
+}
+function resolveRoot(root, callerDir) {
+	if (root === void 0 || root === "") return discoverRoot(callerDir);
+	return resolve(callerDir, root);
+}
+/** What a child process prints as `$PWD` (macOS resolves the tmpdir symlink); the path itself when it cannot resolve. */
+function safeRealpath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+//#endregion
+export { safeRealpath as i, installRootOf as n, resolveRoot as r, discoverRoot as t };
+
+//# sourceMappingURL=shared-resolve.js.map