@jterrazz/test 16.1.1 → 17.0.0

package/dist/shared-session-ledger.js

@@ -0,0 +1,301 @@
+import { t as ServedProcess } from "./shared-serve.js";
+import { t as isRecord } from "./shared-json-shape.js";
+import { n as refusal } from "./shared-refusal.js";
+import { l as VITEST_ARTIFACTS_DIR } from "./shared-artifacts.js";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { execFile } from "node:child_process";
+//#region src/specifications/mobile/server/simulator.ts
+async function run(command, args, options = {}) {
+	return await new Promise((resolve, reject) => {
+		execFile(command, args, {
+			encoding: "utf8",
+			...options
+		}, (error, stdout) => {
+			if (error === null) resolve({ stdout });
+			else reject(error);
+		});
+	});
+}
+let firstLaunch;
+async function simctl(args, options = {}) {
+	firstLaunch ??= run("xcodebuild", ["-checkFirstLaunchStatus"]);
+	await firstLaunch;
+	return await run("xcrun", ["simctl", ...args], options);
+}
+const BOOT_TIMEOUT_MS = 12e4;
+const isSimctlDevices = (value) => isRecord(value) && Object.values(value).every((devices) => Array.isArray(devices));
+const RUNTIME_KEY = /^.*SimRuntime\.(?<platform>[A-Za-z]+)-(?<version>[\d-]+)$/u;
+const WORDS = /\s+/u;
+function runtimeLabel(runtime) {
+	return runtime.replace(RUNTIME_KEY, (_key, platform, version) => `${platform} ${version.replaceAll("-", ".")}`);
+}
+function listSimulators(listJson) {
+	const parsed = JSON.parse(listJson);
+	const devices = isRecord(parsed) && isSimctlDevices(parsed.devices) ? parsed.devices : {};
+	return Object.entries(devices).flatMap(([runtime, listed]) => listed.filter((device) => device.isAvailable !== false).map((device) => ({
+		name: device.name,
+		os: runtimeLabel(runtime),
+		state: device.state,
+		udid: device.udid
+	})));
+}
+function runtimeOf(os) {
+	const words = os.trim().split(WORDS);
+	const platform = String(words[0]).toLowerCase();
+	return {
+		platform: words.length > 1 ? platform : void 0,
+		version: String(words.at(-1))
+	};
+}
+/** `'iOS 26.5'` and `'26.5'` name one runtime; two naming platforms must name the same one. */
+function sameRuntime(one, other) {
+	const [a, b] = [runtimeOf(one), runtimeOf(other)];
+	return a.version === b.version && (a.platform === void 0 || b.platform === void 0 || a.platform === b.platform);
+}
+function formatListing(devices) {
+	return devices.map((device) => `  ${device.name}: ${device.os} (${device.state}) ${device.udid}`).join("\n");
+}
+function selectSimulator(listJson, criteria) {
+	const available = listSimulators(listJson);
+	const matches = available.filter((device) => device.name === criteria.name && (criteria.os === void 0 || sameRuntime(device.os, criteria.os)));
+	const wanted = criteria.os === void 0 ? `"${criteria.name}"` : `"${criteria.name}" on ${criteria.os}`;
+	const [only] = matches;
+	if (only === void 0) throw new Error(refusal({
+		fix: "name one of the available devices, or create the simulator in Xcode",
+		found: `specification.mobile(): no simulator matches ${wanted}.\navailable devices:\n${formatListing(available)}`,
+		read: "docs/guides/mobile-specs.md#options",
+		why: "Resolution refuses rather than guesses: a device names exactly one simulator."
+	}));
+	if (matches.length > 1) throw new Error(refusal({
+		fix: "add `os:` or `udid:` to pick one",
+		found: `specification.mobile(): ${matches.length} simulators match ${wanted}.\nmatched:\n${formatListing(matches)}`,
+		read: "docs/guides/mobile-specs.md#options",
+		why: "Resolution refuses rather than guesses: a device names exactly one simulator."
+	}));
+	return only;
+}
+async function resolveSimulatorUdid(criteria) {
+	const { stdout } = await simctl([
+		"list",
+		"devices",
+		"--json"
+	], { maxBuffer: 16777216 });
+	return selectSimulator(stdout, criteria).udid;
+}
+/** Idempotent: an already-booted device is tolerated. */
+async function ensureBooted(udid) {
+	try {
+		await simctl(["boot", udid]);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (!message.includes("current state: Booted")) throw new Error(refusal({
+			fix: "finish Xcode's first launch if it asks (`sudo xcodebuild -runFirstLaunch`), boot it by hand (`xcrun simctl boot <udid>`) and correct what simctl names",
+			found: `specification.mobile(): could not boot simulator ${udid}.\n${message}`,
+			read: "docs/guides/mobile-specs.md#requirements-what-the-machine-must-have",
+			why: "A mobile spec runs on a simulator the machine can boot."
+		}), { cause: error });
+	}
+	await simctl([
+		"bootstatus",
+		udid,
+		"-b"
+	], { timeout: BOOT_TIMEOUT_MS });
+}
+//#endregion
+//#region src/specifications/mobile/server/appium-server.ts
+const APPIUM_READY_TIMEOUT_MS = 6e4;
+const APPIUM_STATUS = "/status";
+/** outside: the XCUITest driver runs WebDriverAgent's xcodebuild in a group of its own and keeps it past the session and past its own exit, beside the runner app it launches inside the simulator. */
+function webDriverAgentOf(udid) {
+	return [{
+		holds: ["WebDriverAgent", `id=${udid}`],
+		program: "xcodebuild"
+	}, {
+		holds: [`/Devices/${udid}/`],
+		program: "WebDriverAgentRunner-Runner"
+	}];
+}
+/** Appium is an optional peer resolved from `node_modules/.bin`; the served process owns port, readiness, the group kill, and the WebDriverAgent the server spawned for the simulator. */
+async function startAppiumServer(root, udid) {
+	const bin = resolve(root, "node_modules", ".bin", "appium");
+	if (!existsSync(bin)) throw new Error(refusal("seam-is-an-optional-peer", {
+		fix: "npm install -D appium webdriverio && npx appium driver install xcuitest",
+		found: `specification.mobile() requires \`appium\`, and ${bin} does not exist`
+	}));
+	const serve = new ServedProcess({
+		command: `"${bin}" --port "$PORT"`,
+		ready: APPIUM_STATUS,
+		strays: webDriverAgentOf(udid),
+		timeout: APPIUM_READY_TIMEOUT_MS
+	}, root, "mobile");
+	return {
+		stop: async () => {
+			await serve.stop();
+		},
+		url: await serve.start()
+	};
+}
+/** The booted simulator is the machine's and outlives the server; its WebDriverAgent is the server's, and does not. */
+async function serveAppium(device, root) {
+	const udid = device.udid ?? await resolveSimulatorUdid(device);
+	await ensureBooted(udid);
+	return {
+		server: await startAppiumServer(root, udid),
+		udid
+	};
+}
+/** The run's Appium server, provided by a `mobile({ device })` project's setup. */
+async function mobileServer() {
+	try {
+		const { inject } = await import("vitest");
+		return inject("mobileServer");
+	} catch {
+		return;
+	}
+}
+function notOurs(url) {
+	return {
+		stop: async () => {},
+		url
+	};
+}
+function named({ name, os, udid }) {
+	return [
+		`'${name}'`,
+		os === void 0 ? "" : ` (${os})`,
+		udid === void 0 ? "" : ` [${udid}]`
+	].join("");
+}
+/** Never another device: no other simulator was booted for the run. */
+function runDevice(device, run) {
+	if (device === void 0) return {
+		...run.device,
+		udid: run.udid
+	};
+	if (!(device.name === run.device.name && (device.os === void 0 || run.device.os !== void 0 && sameRuntime(device.os, run.device.os)) && (device.udid === void 0 || device.udid === run.udid))) throw new Error(refusal({
+		fix: "name that device, or declare no device on mobile() so each file serves its own",
+		found: `specification.mobile() names the device ${named(device)}, and the run's Appium server drives ${named({
+			...run.device,
+			udid: run.udid
+		})}, the device its mobile({ device }) project declares`,
+		read: "docs/guides/mobile-specs.md#one-session-per-run",
+		why: "The run's setup booted the project's device alone."
+	}));
+	return {
+		...run.device,
+		udid: run.udid
+	};
+}
+/** A declared server owns its devices; the run's server drives the one its setup booted; otherwise resolved, booted and spawned here for this file. */
+async function reachAppium({ appium: declared, device }, root, run) {
+	if (declared !== void 0) {
+		if (device === void 0) throw new Error(refusal({
+			fix: "name the simulator with `device: { name }`",
+			found: `specification.mobile() names no device to ask the Appium server at ${declared.url} for`,
+			read: "docs/guides/mobile-specs.md#a-declared-appium-server",
+			why: "A declared server is handed its device by capabilities."
+		}));
+		return {
+			appium: notOurs(declared.url),
+			device,
+			outlivesFile: true
+		};
+	}
+	if (run !== void 0) return {
+		appium: notOurs(run.url),
+		device: runDevice(device, run),
+		outlivesFile: true
+	};
+	if (device === void 0) throw new Error(refusal({
+		fix: "name the simulator with `device: { name }`, or declare it once on the project, mobile({ device, root }), so every file drives the run's",
+		found: "specification.mobile() names no device, and no mobile({ device }) project serves one",
+		read: "docs/guides/mobile-specs.md#one-session-per-run",
+		why: "A mobile spec drives one simulator, named by the runner or by its project."
+	}));
+	const { server, udid } = await serveAppium(device, root);
+	return {
+		appium: server,
+		device: {
+			...device,
+			udid
+		},
+		outlivesFile: false
+	};
+}
+//#endregion
+//#region src/specifications/mobile/session/session-ledger.ts
+const SERVER_CALL_TIMEOUT_MS = 1e4;
+const MOBILE_SESSIONS_DIR = `${VITEST_ARTIFACTS_DIR}/mobile-sessions`;
+function keyOf(serverUrl, requested) {
+	const sorted = Object.entries(requested).toSorted(([a], [b]) => a.localeCompare(b));
+	return JSON.stringify([serverUrl, sorted]);
+}
+function isEntry(value) {
+	return isRecord(value) && [
+		value.key,
+		value.serverUrl,
+		value.sessionId
+	].every((field) => typeof field === "string") && isRecord(value.capabilities);
+}
+function entryFiles(directory) {
+	try {
+		return readdirSync(directory).filter((name) => name.endsWith(".json"));
+	} catch {
+		return [];
+	}
+}
+function entries(directory) {
+	const parsed = (name) => JSON.parse(readFileSync(join(directory, name), "utf8"));
+	return entryFiles(directory).map((name) => parsed(name)).filter((entry) => isEntry(entry));
+}
+function sessionLedger(directory) {
+	return {
+		forget: (sessionId) => {
+			rmSync(join(directory, `${sessionId}.json`), { force: true });
+		},
+		lookup: (serverUrl, requested) => {
+			const key = keyOf(serverUrl, requested);
+			return entries(directory).filter((entry) => entry.key === key).map(({ capabilities, serverUrl: url, sessionId }) => ({
+				capabilities,
+				serverUrl: url,
+				sessionId
+			}));
+		},
+		record: (requested, session) => {
+			const entry = {
+				...session,
+				key: keyOf(session.serverUrl, requested)
+			};
+			mkdirSync(directory, { recursive: true });
+			writeFileSync(join(directory, `${session.sessionId}.json`), `${JSON.stringify(entry)}\n`);
+		}
+	};
+}
+/** A server that no longer answers has taken its sessions with it. */
+async function endSessions(directory) {
+	await Promise.all(entries(directory).map(async (entry) => {
+		try {
+			await (await fetch(`${entry.serverUrl}/session/${entry.sessionId}`, {
+				method: "DELETE",
+				signal: AbortSignal.timeout(SERVER_CALL_TIMEOUT_MS)
+			})).body?.cancel();
+		} catch {}
+	}));
+	rmSync(directory, {
+		force: true,
+		recursive: true
+	});
+}
+async function mobileSessions() {
+	try {
+		const { inject } = await import("vitest");
+		return inject("mobileSessions");
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { sessionLedger as a, serveAppium as c, mobileSessions as i, SERVER_CALL_TIMEOUT_MS as n, mobileServer as o, endSessions as r, reachAppium as s, MOBILE_SESSIONS_DIR as t };
+
+//# sourceMappingURL=shared-session-ledger.js.map

package/dist/shared-setup-entry.js

@@ -0,0 +1,12 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+//#region src/chain/paths/setup-entry.ts
+/** A global setup's source in a checkout, else the entry the build names after it: `<name>.global-setup.js`, beside its owner's chunk. */
+function setupEntry(directory, name) {
+	const source = join(directory, `${name}.global-setup.ts`);
+	return existsSync(source) ? source : join(directory, `${name}.global-setup.js`);
+}
+//#endregion
+export { setupEntry as t };
+
+//# sourceMappingURL=shared-setup-entry.js.map

package/dist/shared-source-scan.js

@@ -0,0 +1,133 @@
+function skipString(text, start) {
+	const quote = text[start];
+	let index = start + 1;
+	while (index < text.length) {
+		const character = text[index];
+		if (character === "\\") {
+			index += 2;
+			continue;
+		}
+		if (character === quote) return index + 1;
+		if (quote === "`" && character === "$" && text[index + 1] === "{") {
+			index = closingOf(text, index + 1) + 1;
+			continue;
+		}
+		index += 1;
+	}
+	return index;
+}
+const BEFORE_REGEX = /(?:^|[(,=:[!&|?{};+\-*%<>~^]|\breturn|\btypeof|\bcase)\s*$/u;
+function opensRegex(text, start) {
+	return text[start] === "/" && text[start + 1] !== "/" && text[start + 1] !== "*" && BEFORE_REGEX.test(text.slice(Math.max(0, start - 16), start));
+}
+function pastFlags(text, close) {
+	let end = close + 1;
+	while (/[a-z]/u.test(text[end] ?? "")) end += 1;
+	return end;
+}
+function regexEnd(text, start) {
+	if (!opensRegex(text, start)) return start;
+	let inClass = false;
+	for (let index = start + 1; index < text.length; index += 1) {
+		const character = text[index];
+		if (character === "\\") index += 1;
+		else if (character === "\n") return start;
+		else if (character === "[" || character === "]") inClass = character === "[";
+		else if (character === "/" && !inClass) return pastFlags(text, index);
+	}
+	return start;
+}
+function literalEnd(text, start) {
+	const character = text[start];
+	if (character === "'" || character === "\"" || character === "`") return skipString(text, start);
+	return regexEnd(text, start);
+}
+function closingOf(text, open) {
+	const pairs = {
+		"(": ")",
+		"[": "]",
+		"{": "}"
+	};
+	const stack = [];
+	let index = open;
+	while (index < text.length) {
+		const character = text[index] ?? "";
+		const past = index === open ? index : literalEnd(text, index);
+		if (past !== index) {
+			index = past;
+			continue;
+		}
+		if (character in pairs) stack.push(pairs[character] ?? "");
+		else if (character === stack.at(-1)) {
+			stack.pop();
+			if (stack.length === 0) return index;
+		}
+		index += 1;
+	}
+	return text.length;
+}
+/** The offsets of the brackets still open at `index`, outermost first; a literal's brackets are none. */
+function openersAt(text, index) {
+	const closers = {
+		")": "(",
+		"]": "[",
+		"}": "{"
+	};
+	const stack = [];
+	let at = 0;
+	while (at < index) {
+		const past = literalEnd(text, at);
+		if (past !== at) {
+			at = past;
+			continue;
+		}
+		const character = text[at] ?? "";
+		if (character === "(" || character === "[" || character === "{") stack.push(at);
+		else if (character in closers && text[stack.at(-1) ?? -1] === closers[character]) stack.pop();
+		at += 1;
+	}
+	return stack;
+}
+/** Each comma-separated argument between `start` and `end`, trimmed, an empty one dropped. */
+function argumentSpans(text, start = 0, end = text.length) {
+	const spans = [];
+	let from = start;
+	const close = (to) => {
+		const raw = text.slice(from, to);
+		if (raw.trim() !== "") {
+			const lead = raw.length - raw.trimStart().length;
+			spans.push({
+				end: from + raw.trimEnd().length,
+				start: from + lead
+			});
+		}
+		from = to + 1;
+	};
+	let index = start;
+	while (index < end) {
+		const past = literalEnd(text, index);
+		const character = text[index];
+		if (past !== index) index = past;
+		else if (character === "(" || character === "[" || character === "{") index = closingOf(text, index) + 1;
+		else {
+			if (character === ",") close(index);
+			index += 1;
+		}
+	}
+	close(end);
+	return spans;
+}
+function argumentsOf(text) {
+	return argumentSpans(text).map(({ end, start }) => text.slice(start, end));
+}
+function literalOf(argument) {
+	const text = argument?.trim() ?? "";
+	const quote = text[0];
+	if (quote !== "'" && quote !== "\"" && quote !== "`" || skipString(text, 0) !== text.length) return;
+	const body = text.slice(1, -1);
+	return quote === "`" ? body.replaceAll(/\$\{[^}]*\}/gu, "\0") : body;
+}
+//#endregion
+export { literalOf as a, literalEnd as i, argumentsOf as n, openersAt as o, closingOf as r, skipString as s, argumentSpans as t };
+
+//# sourceMappingURL=shared-source-scan.js.map