@jterrazz/test 16.0.0 → 16.1.0

package/dist/appium.adapter.js

@@ -1,4 +1,4 @@
-import { r as formatElement, t as AmbiguousElementError } from "./ambiguity.js";
+import { a as formatElement, r as AmbiguousElementError, t as warnSubstringOnly } from "./substring-warning.js";
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { tmpdir } from "node:os";
@@ -211,6 +211,16 @@ function compilePredicate(element, options) {
 		default: throw new Error(`${formatElement(element)}: landmarks are a website concept — an iOS screen has no '${element.kind}' region. Scope with within(testId('…'), …) instead.`);
 	}
 }
+/**
+* Every element a predicate designates under `scope`.
+*
+* ONE place awaits webdriverio's query: `$$` answers a chainable typed as the
+* array it resolves to, so the await that makes the array real reads to the
+* typechecker as an await of a non-promise.
+*/
+async function matching(scope, element, options) {
+	return await scope.$$(`-ios predicate string:${compilePredicate(element, options)}`);
+}
 /** The outside-in scope chain of a descriptor, ending on the target itself. */
 function scopeChain(element) {
 	const chain = [];
@@ -341,10 +351,16 @@ var AppiumAdapter = class {
 		const chain = scopeChain(element);
 		const deadline = Date.now() + this.actionTimeoutMs;
 		let scrollAttempted = false;
+		let windowAsked = false;
+		let looking = chain;
 		for (;;) {
-			const resolved = await this.resolveChain(driver, chain, cardinality, { tryScroll: !scrollAttempted });
+			const resolved = await this.resolveChain(driver, looking, cardinality, { tryScroll: !scrollAttempted });
 			scrollAttempted = true;
 			if (resolved) return resolved;
+			if (!windowAsked) {
+				windowAsked = true;
+				looking = await this.widenedChain(driver, chain) ?? chain;
+			}
 			if (Date.now() > deadline) throw await this.timeoutError(driver, element, verb);
 			await delay(POLL_INTERVAL_MS);
 		}
@@ -353,11 +369,11 @@ var AppiumAdapter = class {
 	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 matches = await matching(scope, level);
 			const count = await matches.length;
 			if (count === 0) {
 				if (options?.tryScroll) {
-					const first = (await scope.$$(`-ios predicate string:${compilePredicate(level, { anyVisibility: true })}`))[0];
+					const first = (await matching(scope, level, { anyVisibility: true }))[0];
 					if (first !== void 0) try {
 						await driver.executeScript("mobile: scroll", [{
 							elementId: first.elementId,
@@ -378,6 +394,45 @@ var AppiumAdapter = class {
 		}
 		return scope;
 	}
+	/**
+	* The chain to keep polling with, level by level: a descriptor that
+	* designated nothing as a whole label but designates exactly one thing as a
+	* SUBSTRING is widened, with the warning that names the label to write. The
+	* window is the vocabulary's, not one surface's — chapter 13 — so the
+	* screen answers it exactly as a page does.
+	*
+	* `null` when nothing would change, which is the ordinary wait.
+	*/
+	async widenedChain(driver, chain) {
+		let scope = driver;
+		const widened = [];
+		let changed = false;
+		for (const level of chain) {
+			const found = await this.widenedLevel(scope, level);
+			changed ||= found !== null;
+			const candidate = found ?? level;
+			const next = (await matching(scope, candidate))[0];
+			if (next === void 0) return null;
+			scope = next;
+			widened.push(candidate);
+		}
+		return changed ? widened : null;
+	}
+	/** One level of the chain, widened and warned about, or `null`. */
+	async widenedLevel(scope, level) {
+		if (level.exact !== void 0 || level.name === void 0) return null;
+		if (await (await matching(scope, level)).length > 0) return null;
+		const loose = {
+			...level,
+			exact: false
+		};
+		const matches = await matching(scope, loose);
+		const first = matches[0];
+		if (first === void 0 || await matches.length !== 1) return null;
+		const evidence = await captureMatch(first);
+		warnSubstringOnly(level, this.options.udid, evidence.label);
+		return loose;
+	}
 	/** Enumerate the candidates' evidence, truncated. */
 	async captureMatches(matches) {
 		const count = Math.min(await matches.length, MAX_REPORTED_MATCHES);

package/dist/browser/index.js

@@ -129,6 +129,12 @@ function isOptions(value) {
 * The framework owns the seam so a test never has to: this is the one place
 * `fetch` is wrapped, it is put back when the scope ends, and what it does is
 * the one thing a page would have done for free — turn `/api/posts` into a URL.
+*
+* Validating the origin and INSTALLING the wrapper are two steps because they
+* happen at two moments: the refusal of a bad origin belongs before anything
+* starts, while the wrapper may only go on once the engine is listening — it
+* has to sit ON TOP of whatever `fetch` the engine installed, and be taken off
+* before the engine takes its own back.
 */
 function resolveRelativeAgainst(origin) {
 	let base;
@@ -137,10 +143,12 @@ function resolveRelativeAgainst(origin) {
 	} catch {
 		throw new Error(`intercept(): \`origin\` states where a relative request resolves — \`${origin}\` is not an absolute URL (e.g. 'http://console.test').`);
 	}
-	const original = globalThis.fetch;
-	globalThis.fetch = async (input, init) => typeof input === "string" && input.startsWith("/") ? await original(new URL(input, base).toString(), init) : await original(input, init);
 	return () => {
-		globalThis.fetch = original;
+		const engine = globalThis.fetch;
+		globalThis.fetch = async (input, init) => typeof input === "string" && input.startsWith("/") ? await engine(new URL(input, base).toString(), init) : await engine(input, init);
+		return () => {
+			globalThis.fetch = engine;
+		};
 	};
 }
 /**
@@ -155,18 +163,13 @@ function interceptThrough(register) {
 		const options = isOptions(maybeOptions) ? maybeOptions : isOptions(maybeResponseOrOptions) ? maybeResponseOrOptions : void 0;
 		const contracts = declared(requestOrContracts, options === maybeResponseOrOptions ? void 0 : maybeResponseOrOptions);
 		if (contracts.length === 0) throw new Error("intercept(): declare at least one contract — an empty list guards nothing, and a subject with no network needs no intercept at all.");
-		const restoreOrigin = options?.origin === void 0 ? void 0 : resolveRelativeAgainst(options.origin);
-		let registration;
-		try {
-			registration = await register(contracts);
-		} catch (error) {
-			restoreOrigin?.();
-			throw error;
-		}
+		const installOrigin = options?.origin === void 0 ? void 0 : resolveRelativeAgainst(options.origin);
+		const registration = await register(contracts);
+		const restoreOrigin = installOrigin?.();
 		return { [Symbol.asyncDispose]: async () => {
+			restoreOrigin?.();
 			const violation = registration.violation();
 			registration.cleanup();
-			restoreOrigin?.();
 			await Promise.resolve();
 			if (violation) throw violation;
 		} };
@@ -1374,8 +1377,8 @@ function describeAmbiguity(options) {
 * It is printed ONCE per descriptor per process: a scenario that clicks the
 * same link in ten tests has one thing to fix, not ten lines to read.
 */
-/** How long the two-release window lasts, stated in the message itself. */
-const WINDOW = "16.0 and 16.1";
+/** How long the window lasts, stated in the message itself. */
+const WINDOW = "through 16.x";
 /** Descriptors already reported in this process. */
 const reported = /* @__PURE__ */ new Set();
 /** The identity a descriptor is deduplicated by — kind, name, and its scope chain. */
@@ -1388,13 +1391,70 @@ function identityOf(element) {
 * designated something as a substring. Returns whether a line was printed,
 * which is what the adapters' own tests assert on.
 */
-function warnSubstringOnly(element, where) {
+function warnSubstringOnly(element, where, found) {
 	const identity = identityOf(element);
 	if (reported.has(identity)) return false;
 	reported.add(identity);
-	console.warn(`@jterrazz/test: ${element.kind}('${element.name ?? ""}') matched nothing as a whole accessible name, and matched only as a SUBSTRING of a longer one (${where}). Names are exact from 16.0: write the name in full, scope it with \`within(…)\`, or state \`{ exact: false }\` to keep the old behaviour. This warning ships for ${WINDOW}; after that the substring match is gone and this is simply not found.`);
+	const spelling = found === void 0 ? "" : ` The name to write is '${found.replaceAll(/\s+/gu, " ").trim()}'.`;
+	console.warn(`@jterrazz/test: ${element.kind}('${element.name ?? ""}') matched nothing as a whole accessible name, and matched only as a SUBSTRING of a longer one (${where}).${spelling} Names are exact from 16.0: write the name in full, scope it with \`within(…)\`, or state \`{ exact: false }\` to keep the old behaviour. The substring is still resolved, with this warning, ${WINDOW}; gone in 17.0, where the same descriptor is simply not found.`);
 	return true;
 }
+/**
+* The descriptor to retry with, LEVEL by level, or `undefined` when nothing
+* would change.
+*
+* Every level of the chain is asked the same question the target is asked —
+* `within(button('Proof of authorship'), content('Verified'))` against a
+* button named "Proof of authorship Verified" failed on the SCOPE, and a
+* warning that only ever widened the target printed nothing at all. The chain
+* is walked outside-in and rebuilt as it goes, since an inner level's answer
+* is meaningless under a scope that designates nothing.
+*
+* A level that states an `exact` of its own is left alone: an author who wrote
+* `{ exact: false }` chose the substring, and one who wrote `{ exact: true }`
+* was already exact.
+*
+* Asked BEFORE the action, not after it fails: a verb waits its whole
+* actionability budget, which is the test's own budget, so a retry afterwards
+* never runs — the test is already over. The probes are counts, which wait for
+* nothing, and the common case (the name matches whole) costs one per level.
+*/
+async function widenedForWindow(element, where, probe) {
+	const chain = [];
+	for (let level = element; level; level = level.scope) chain.unshift(level);
+	let rebuilt;
+	let widened = false;
+	for (const level of chain) {
+		const candidate = {
+			...level,
+			...rebuilt === void 0 ? {} : { scope: rebuilt }
+		};
+		const loose = await widenedLevel(candidate, where, probe);
+		widened ||= loose !== void 0;
+		rebuilt = loose ?? candidate;
+	}
+	return widened ? rebuilt : void 0;
+}
+/**
+* The one level, widened and warned about, or `undefined` when it designates
+* something already, states its own `exact`, carries no name, or would
+* designate nothing either way.
+*/
+async function widenedLevel(candidate, where, probe) {
+	if (candidate.exact !== void 0 || candidate.name === void 0) return;
+	try {
+		if (await probe.count(candidate) > 0) return;
+		const loose = {
+			...candidate,
+			exact: false
+		};
+		if (await probe.count(loose) !== 1) return;
+		warnSubstringOnly(candidate, where, await probe.nameOf(loose));
+		return loose;
+	} catch {
+		return;
+	}
+}
 //#endregion
 //#region src/seams/vitest-browser/vitest-browser.adapter.ts
 /**
@@ -1489,6 +1549,14 @@ function ambiguousLevel(element) {
 	for (const level of chain.slice(0, -1)) if (locate(page, level).elements().length > 1) return level;
 	return element;
 }
+/** What the transitional window may ask of the mounted page. */
+const PROBE = {
+	count: async (element) => await Promise.resolve(locate(page, element).elements().length),
+	nameOf: async (element) => {
+		const [match] = candidates(locate(page, element));
+		return await Promise.resolve(match?.accessibleName ?? match?.text);
+	}
+};
 /**
 * Run one visitor action, turning "more than one match" into the W3 refusal.
 * The ambiguous LEVEL is identified first: a scope matching several landmarks
@@ -1496,15 +1564,13 @@ function ambiguousLevel(element) {
 * wrong descriptor.
 */
 async function act(element, action) {
-	const locator = locate(page, element);
+	const target = await widenedForWindow(element, globalThis.location.href, PROBE) ?? element;
+	const locator = locate(page, target);
 	try {
 		return await action(locator);
 	} catch (error) {
-		if (locator.elements().length <= 1) {
-			reportSubstringOnly(element);
-			throw error;
-		}
-		const culprit = ambiguousLevel(element);
+		if (locator.elements().length <= 1) throw error;
+		const culprit = ambiguousLevel(target);
 		const matches = candidates(locate(page, culprit));
 		const url = globalThis.location.href;
 		throw new AmbiguousElementError(describeAmbiguity({
@@ -1515,24 +1581,6 @@ async function act(element, action) {
 	}
 }
 /**
-* Say so when a descriptor found NOTHING as a whole name but would have found
-* something as a substring — the one shape the whole-name default changes.
-*
-* Asked only on the failure path, and only for a descriptor that stated no
-* `exact` of its own: an author who wrote `{ exact: false }` chose the
-* substring, and one who wrote `{ exact: true }` was already exact.
-*/
-function reportSubstringOnly(element) {
-	if (element.exact !== void 0 || element.name === void 0) return;
-	try {
-		if (locate(page, element).elements().length > 0) return;
-		if (locate(page, {
-			...element,
-			exact: false
-		}).elements().length > 0) warnSubstringOnly(element, globalThis.location.href);
-	} catch {}
-}
-/**
 * Is this descriptor answered by PRESENCE rather than by visibility?
 *
 * The options of a collapsed `<select>` are in the document and in the