@jterrazz/test 10.0.0 → 11.0.0

package/dist/appium.adapter.js

@@ -0,0 +1,399 @@
+import { r as formatElement, t as AmbiguousElementError } from "./ambiguity.js";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { tmpdir } from "node:os";
+//#region src/core/specification/mobile/ambiguity.ts
+/**
+* The ambiguity refusal, mobile edition — CONVENTIONS W3.
+*
+* A mobile descriptor must designate exactly one element. Acting on "the
+* first match" is the failure mode this module exists to prevent: the spec
+* keeps passing while the visitor taps something else, and nothing ever
+* reports it. So when a descriptor matches several elements the framework
+* refuses, and the refusal carries everything needed to fix it without
+* opening the simulator — the descriptor in the caller's own vocabulary,
+* every candidate, and the concrete rewrites that would resolve it.
+*
+* The element vocabulary is shared with the website facet, so the source
+* rendering (`formatElement`) is too; only the evidence differs — XCUITest
+* types, labels and accessibility identifiers instead of tags and landmarks.
+* Pure string building: the appium integration stays a thin adapter.
+*/
+/** `1. Button "Bookmark"  [testId: event-42]` — one evidence line per candidate. */
+function formatMatch(match, index) {
+	const label = match.label === void 0 ? "" : ` ${JSON.stringify(match.label)}`;
+	const value = match.value === void 0 ? "" : `  value=${JSON.stringify(match.value)}`;
+	const identifier = match.identifier === void 0 ? "" : `  [testId: ${match.identifier}]`;
+	return `  ${index + 1}. ${match.type}${label}${value}${identifier}`;
+}
+/**
+* The rewrites worth offering, in the order they should be tried. Scoping is
+* always available; `exact` only when it would actually narrow the set, and
+* the count it would leave is stated so a still-ambiguous suggestion never
+* reads as a fix; distinct identifiers make `testId()` a concrete rewrite
+* rather than a guess.
+*/
+function formatFixes(element, matches) {
+	const fixes = [];
+	if (!element.scope) fixes.push(`scope it       within(testId('…'), ${formatElement(element)}) — a screen has no landmarks; any descriptor works as the scope`);
+	if (!element.exact && element.name !== void 0) {
+		const remaining = matches.filter((match) => match.label === element.name).length;
+		if (remaining > 0 && remaining < matches.length) fixes.push(`exact name     ${formatElement({
+			exact: true,
+			kind: element.kind,
+			name: element.name
+		})}   [leaves ${remaining} of ${matches.length}]`);
+	}
+	const identifiers = [...new Set(matches.map((match) => match.identifier).filter((identifier) => identifier !== void 0))];
+	if (identifiers.length > 1 && element.kind !== "testId") fixes.push(`test id        testId(${JSON.stringify(identifiers[0])})   [also here: ${identifiers.slice(1).join(", ")}]`);
+	fixes.push("other element  a button() or field() may name one thing where this does not");
+	return fixes;
+}
+/**
+* Build the refusal thrown when a descriptor matches more than one element
+* on the screen.
+*
+* @param options.element The descriptor as the caller wrote it.
+* @param options.matches Every candidate, in screen order (already truncated).
+*/
+function describeMobileAmbiguity(options) {
+	const { element, matches } = options;
+	const fixes = formatFixes(element, matches).map((fix) => `  • ${fix}`);
+	return [
+		`Ambiguous element: ${formatElement(element)} matched ${matches.length} elements on the screen.`,
+		"",
+		"A spec must designate exactly one element. Acting on the first match would let",
+		"this test keep passing while the visitor taps something else.",
+		"",
+		"Matched:",
+		...matches.map((match, index) => formatMatch(match, index)),
+		"",
+		"Disambiguate with one of:",
+		...fixes,
+		"",
+		"Docs: docs/12-mobile.md#designating-exactly-one-element (CONVENTIONS W3)"
+	].join("\n");
+}
+//#endregion
+//#region src/core/specification/mobile/projection.ts
+const TAG_PATTERN = /<(?<openTag>[A-Za-z][\w.]*)(?<rawAttributes>(?:\s+[\w:.-]+="[^"]*")*)\s*(?<selfClosing>\/?)>|<\/(?<closeTag>[\w.]*)\s*>/g;
+const ATTRIBUTE_PATTERN = /(?<key>[\w:.-]+)="(?<value>[^"]*)"/g;
+const NAMED_ENTITIES = {
+	"&amp;": "&",
+	"&apos;": "'",
+	"&gt;": ">",
+	"&lt;": "<",
+	"&quot;": "\""
+};
+/** Decode the XML entities an attribute value can carry. */
+function decodeEntities(value) {
+	return value.replace(/&(?:#x(?<hex>[\dA-Fa-f]+)|#(?<decimal>\d+)|(?<named>amp|apos|gt|lt|quot));/g, (entity, hex, decimal) => {
+		if (hex) return String.fromCodePoint(Number.parseInt(hex, 16));
+		if (decimal) return String.fromCodePoint(Number(decimal));
+		return NAMED_ENTITIES[entity] ?? entity;
+	});
+}
+/** Parse the page source into a raw element tree (strict, attribute-only XML). */
+function parsePageSource(xml) {
+	const stack = [];
+	let root = null;
+	for (const match of xml.matchAll(TAG_PATTERN)) {
+		const { closeTag, openTag, rawAttributes, selfClosing } = match.groups ?? {};
+		if (closeTag !== void 0 || openTag === void 0) {
+			stack.pop();
+			continue;
+		}
+		const attributes = {};
+		for (const attribute of (rawAttributes ?? "").matchAll(ATTRIBUTE_PATTERN)) {
+			const { key, value } = attribute.groups ?? {};
+			if (key !== void 0 && value !== void 0) attributes[key] = decodeEntities(value);
+		}
+		const node = {
+			attributes,
+			children: [],
+			tag: openTag
+		};
+		if (stack.length === 0) root = node;
+		else stack[stack.length - 1].children.push(node);
+		if (!selfClosing) stack.push(node);
+	}
+	if (!root) throw new Error("projectScreen(): the page source contains no XML element");
+	return root;
+}
+/** The substance of a node — what survives projection, or nothing. */
+function substance(node) {
+	const label = node.attributes["label"] || void 0;
+	const value = node.attributes["value"] || void 0;
+	const identifier = node.attributes["name"] || void 0;
+	return {
+		type: node.tag.replace(/^XCUIElementType/, ""),
+		...label === void 0 ? {} : { label },
+		...value === void 0 || value === label ? {} : { value },
+		...identifier === void 0 || identifier === label ? {} : { identifier }
+	};
+}
+function hasSubstance(node) {
+	return node.label !== void 0 || node.value !== void 0 || node.identifier !== void 0;
+}
+/** A childless child that repeats its parent is the same accessibility element twice. */
+function repeatsParent(child, parent) {
+	return child.children === void 0 && child.type === parent.type && child.label === parent.label && child.value === parent.value && child.identifier === parent.identifier;
+}
+/** Project one raw node: a kept node, or (hoisting) the projections of its children. */
+function projectNode(node) {
+	const own = substance(node);
+	const children = node.children.flatMap((child) => projectNode(child)).filter((child) => !repeatsParent(child, own));
+	if (!hasSubstance(own)) return children;
+	return [{
+		...own,
+		...children.length > 0 ? { children } : {}
+	}];
+}
+/** Collect the visible texts in document order, collapsing consecutive repeats. */
+function collectTexts(node, texts) {
+	if (node.attributes["visible"] === "true") {
+		const text = node.attributes["label"] || node.attributes["value"] || void 0;
+		if (text !== void 0 && texts[texts.length - 1] !== text) texts.push(text);
+	}
+	for (const child of node.children) collectTexts(child, texts);
+}
+/**
+* Project a raw XCUITest page source into the captured screen: the collapsed
+* tree (rooted at the application node, which is always kept) and the
+* visible texts in document order.
+*/
+function projectScreen(xml) {
+	let root = parsePageSource(xml);
+	if (root.tag === "AppiumAUT" && root.children.length === 1) root = root.children[0];
+	const texts = [];
+	for (const child of root.children) collectTexts(child, texts);
+	const own = substance(root);
+	const children = root.children.flatMap((child) => projectNode(child)).filter((child) => !repeatsParent(child, own));
+	return {
+		texts,
+		tree: {
+			...own,
+			...children.length > 0 ? { children } : {}
+		}
+	};
+}
+//#endregion
+//#region src/integrations/appium/appium.adapter.ts
+const ACTION_TIMEOUT_MS = 3e4;
+const POLL_INTERVAL_MS = 500;
+/** How many candidates the ambiguity error enumerates before truncating. */
+const MAX_REPORTED_MATCHES = 10;
+/** WebDriverAgent builds once per simulator — the first session is the slow one. */
+const WDA_LAUNCH_TIMEOUT_MS = 24e4;
+const delay = (ms) => new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+/** Escape a name for an NSPredicate single-quoted string literal. */
+function escapePredicate(value) {
+	return value.replaceAll("\\", String.raw`\\`).replaceAll("'", String.raw`\'`);
+}
+/**
+* Translate a user-facing descriptor into an iOS predicate string. Landmarks
+* have no XCUITest analog — the shared vocabulary is wider than a screen,
+* and the boundary is named rather than silently approximated.
+*/
+function compilePredicate(element, options) {
+	const name = escapePredicate(element.name ?? "");
+	const contains = (attribute) => element.exact ? `${attribute} == '${name}'` : `${attribute} CONTAINS '${name}'`;
+	const visible = options?.anyVisibility ? "1 == 1" : "visible == 1";
+	switch (element.kind) {
+		case "button": return `type == 'XCUIElementTypeButton' AND ${contains("label")} AND ${visible}`;
+		case "field": return `type IN {'XCUIElementTypeTextField','XCUIElementTypeSecureTextField'} AND (${contains("label")} OR ${contains("value")}) AND ${visible}`;
+		case "testId": return `name == '${name}' AND ${visible}`;
+		case "text": return `(${contains("label")} OR ${contains("value")}) AND ${visible}`;
+		default: throw new Error(`${formatElement(element)}: landmarks are a website concept — an iOS screen has no '${element.kind}' region. Scope with within(testId('…'), …) instead.`);
+	}
+}
+/** The outside-in scope chain of a descriptor, ending on the target itself. */
+function scopeChain(element) {
+	const chain = [];
+	for (let current = element; current; current = current.scope) chain.unshift(current);
+	return chain;
+}
+/** Capture one candidate's evidence for the ambiguity refusal. */
+async function captureMatch(element) {
+	const [type, label, value, identifier] = await Promise.all([
+		element.getAttribute("type"),
+		element.getAttribute("label"),
+		element.getAttribute("value"),
+		element.getAttribute("name")
+	]);
+	const shortLabel = label ? label.replaceAll(/\s+/g, " ").trim().slice(0, 80) : void 0;
+	return {
+		type: (type ?? "Unknown").replace(/^XCUIElementType/, ""),
+		...shortLabel === void 0 ? {} : { label: shortLabel },
+		...value && value !== label ? { value } : {},
+		...identifier && identifier !== label ? { identifier } : {}
+	};
+}
+/**
+* Device adapter backed by appium's XCUITest driver over webdriverio.
+*
+* ONE driver session per adapter (= per runner = per vitest worker), created
+* lazily on the first `open()` and reused — WebDriverAgent startup is the
+* expensive part, not the app relaunch. Every `open()` terminates and
+* relaunches the app, so each spec starts from a deterministic fresh state.
+*
+* Webdriverio is an optional peer dependency: it is only imported here, and
+* this module is only loaded when a spec calls `.open()`.
+*/
+var AppiumAdapter = class {
+	driver = null;
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	async close() {
+		if (this.driver) {
+			await this.driver.deleteSession();
+			this.driver = null;
+		}
+	}
+	async open(options) {
+		const driver = await this.session(options.bundleId);
+		try {
+			await driver.executeScript("mobile: terminateApp", [{ bundleId: options.bundleId }]);
+		} catch {}
+		await (options.deepLink === void 0 ? driver.executeScript("mobile: activateApp", [{ bundleId: options.bundleId }]) : driver.executeScript("mobile: deepLink", [{
+			bundleId: options.bundleId,
+			url: options.deepLink
+		}]));
+		if (options.scenario) try {
+			await options.scenario(this.createVisitor(driver));
+		} catch (error) {
+			const evidence = await this.captureEvidence(driver);
+			const suffix = evidence ? `\nEvidence: ${evidence}` : "";
+			if (error instanceof AmbiguousElementError) {
+				error.message += suffix;
+				throw error;
+			}
+			throw new Error(`open scenario failed: ${error instanceof Error ? error.message : String(error)}${suffix}`, { cause: error });
+		}
+		return projectScreen(await driver.getPageSource());
+	}
+	/**
+	* The visitor implementation. Acting verbs (tap/fill) poll until exactly
+	* one visible match exists (CONVENTIONS W3); `see()` acts on nothing, so
+	* ANY visible match satisfies it — XCUITest trees legitimately expose the
+	* same text more than once (container/child label duplication), and a
+	* synchronization primitive refusing on that would punish honest screens.
+	*/
+	createVisitor(driver) {
+		return {
+			fill: async (element, value) => {
+				await (await this.resolveOne(driver, element, "fill", "one")).setValue(value);
+			},
+			see: async (element) => {
+				await this.resolveOne(driver, element, "see", "any");
+			},
+			tap: async (element) => {
+				await (await this.resolveOne(driver, element, "tap", "one")).click();
+			}
+		};
+	}
+	/**
+	* Resolve a descriptor: poll until at least one visible match exists,
+	* then enforce the verb's cardinality — `'one'` refuses ambiguity
+	* (CONVENTIONS W3), `'any'` settles for the first match. Scopes stay
+	* strict in BOTH modes: "within one of several containers" designates
+	* nothing, whatever the verb. The chain resolves outside-in, so an
+	* ambiguous scope names ITSELF as the fault rather than sending the
+	* author to fix the target.
+	*/
+	async resolveOne(driver, element, verb, cardinality) {
+		const chain = scopeChain(element);
+		const deadline = Date.now() + ACTION_TIMEOUT_MS;
+		let scrollAttempted = false;
+		for (;;) {
+			const resolved = await this.resolveChain(driver, chain, cardinality, { tryScroll: !scrollAttempted });
+			scrollAttempted = true;
+			if (resolved) return resolved;
+			if (Date.now() > deadline) throw await this.timeoutError(driver, element, verb);
+			await delay(POLL_INTERVAL_MS);
+		}
+	}
+	/** One resolution pass over the chain — `null` means "nothing yet, keep polling". */
+	async resolveChain(driver, chain, cardinality, options) {
+		let scope = driver;
+		for (const [index, level] of chain.entries()) {
+			const matches = await scope.$$(`-ios predicate string:${compilePredicate(level)}`);
+			const count = await matches.length;
+			if (count === 0) {
+				if (options?.tryScroll) {
+					const offscreen = await scope.$$(`-ios predicate string:${compilePredicate(level, { anyVisibility: true })}`);
+					if (await offscreen.length > 0) try {
+						await driver.executeScript("mobile: scroll", [{
+							elementId: offscreen[0].elementId,
+							toVisible: true
+						}]);
+					} catch {}
+				}
+				return null;
+			}
+			const isTarget = index === chain.length - 1;
+			if (count > 1 && (cardinality === "one" || !isTarget)) throw new AmbiguousElementError(describeMobileAmbiguity({
+				element: level,
+				matches: await this.captureMatches(matches)
+			}));
+			scope = matches[0];
+		}
+		return scope;
+	}
+	/** Enumerate the candidates' evidence, truncated. */
+	async captureMatches(matches) {
+		const count = Math.min(await matches.length, MAX_REPORTED_MATCHES);
+		const evidence = [];
+		for (let index = 0; index < count; index++) evidence.push(await captureMatch(matches[index]));
+		return evidence;
+	}
+	/** Screenshot the failing state into a temp file; never masks the original error. */
+	async captureEvidence(driver) {
+		try {
+			const path = resolve(mkdtempSync(resolve(tmpdir(), "spec-mobile-")), "failure.png");
+			writeFileSync(path, Buffer.from(await driver.takeScreenshot(), "base64"));
+			return path;
+		} catch {
+			return null;
+		}
+	}
+	/** The timeout refusal, with a compact excerpt of what IS on screen to aid diagnosis. */
+	async timeoutError(driver, element, verb) {
+		let excerpt = "";
+		try {
+			const source = await driver.getPageSource();
+			const labels = [...new Set([...source.matchAll(/label="(?<label>[^"]{2,60})"/g)].map((match) => match.groups?.["label"] ?? ""))].slice(0, 15);
+			if (labels.length > 0) excerpt = `\nCurrently on screen: ${labels.join(" | ")}`;
+		} catch {}
+		return /* @__PURE__ */ new Error(`${verb}(${formatElement(element)}) timed out after ${ACTION_TIMEOUT_MS}ms — no visible match.${excerpt}`);
+	}
+	/** Create the shared driver session (once), with an actionable error when webdriverio is absent. */
+	async session(bundleId) {
+		if (this.driver) return this.driver;
+		let remoteFn;
+		try {
+			({remote: remoteFn} = await import("webdriverio"));
+		} catch {
+			throw new Error(".open() requires webdriverio (optional peer dependency): npm install -D appium webdriverio && npx appium driver install xcuitest");
+		}
+		const url = new URL(this.options.serverUrl);
+		this.driver = await remoteFn({
+			capabilities: {
+				"appium:automationName": "XCUITest",
+				"appium:bundleId": bundleId,
+				"appium:noReset": true,
+				"appium:udid": this.options.udid,
+				"appium:wdaLaunchTimeout": WDA_LAUNCH_TIMEOUT_MS,
+				platformName: "iOS"
+			},
+			hostname: url.hostname,
+			logLevel: "error",
+			port: Number(url.port)
+		});
+		return this.driver;
+	}
+};
+//#endregion
+export { AppiumAdapter };

package/dist/checker.js

@@ -36,7 +36,6 @@ const PRUNED = /* @__PURE__ */ new Set([
 const CONVENTIONAL_SUBDIRS = /* @__PURE__ */ new Set([
 	"expected",
 	"fixtures",
-	"intercepts",
 	"requests",
 	"seeds"
 ]);