@jterrazz/test 16.0.0 → 16.1.1

package/dist/appium.adapter.js

@@ -1,4 +1,4 @@
-import { r as formatElement, t as AmbiguousElementError } from "./ambiguity.js";
+import { i as AmbiguousElementError, n as warnSubstringOnly, o as formatElement } 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);
+		await 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;
 		} };
@@ -1355,6 +1358,45 @@ function describeAmbiguity(options) {
 	].join("\n");
 }
 //#endregion
+//#region src/model/elements/aria-name.ts
+/**
+* The accessible name an ARIA snapshot states.
+*
+* A descriptor matches the name the BROWSER computes, and that name is not the
+* element's text: `<button><span>Experiments</span><span>9</span></button>`
+* reads as `Experiments9` through `textContent` and is named "Experiments 9",
+* a field's name comes from its label and is nowhere in its text at all, and a
+* name cut at eighty characters resolves to nothing. Reading the name off the
+* snapshot is what makes the spelling the window prints a spelling that can be
+* written back into a spec.
+*
+* The dialect is the one both surfaces already speak — playwright's, on the
+* page directly and through `server.commands` for a mounted component — so the
+* projection is stated once, here, and neither adapter computes a name itself.
+*/
+/**
+* The name of the FIRST node a snapshot describes: `- button "Experiments 9"`,
+* optionally followed by `:` and its children.
+*
+* A quote must follow the role across a SPACE. `- paragraph: "…"` is a node
+* with text and no name, and reading that text as a name would hand the author
+* a spelling no role descriptor matches on.
+*/
+const NAMED = /^-\s+[\w-]+\s+"(?<name>(?:[^"\\]|\\.)*)"/u;
+/** Undo the escaping the snapshot applies to a quote or a backslash inside a name. */
+function unescaped(name) {
+	return name.replaceAll(/\\(?<char>.)/gu, "$<char>");
+}
+/**
+* The accessible name the snapshot gives the node it describes, or `undefined`
+* when that node has none — an unnamed landmark, a paragraph of text.
+*/
+function accessibleNameIn(snapshot) {
+	const [first] = snapshot.split("\n");
+	const name = (first === void 0 ? null : NAMED.exec(first.trim()))?.groups?.name;
+	return name === void 0 ? void 0 : unescaped(name);
+}
+//#endregion
 //#region src/model/elements/substring-warning.ts
 /**
 * The transitional warning for a name that matches only as a SUBSTRING.
@@ -1374,8 +1416,16 @@ 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";
+/** The node side's printer — the default every adapter but the page's uses. */
+function toStandardError(line) {
+	if (typeof process === "undefined") {
+		console.warn(line);
+		return;
+	}
+	process.stderr.write(`${line}\n`);
+}
 /** 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 +1438,100 @@ 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) {
+async function warnSubstringOnly(element, where, found, print = toStandardError) {
 	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()}'.`;
+	await print(`@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;
 }
+/**
+* How long a descriptor is given to ARRIVE before the window concludes it is
+* absent — the budget `settles` spends and no more.
+*
+* A count is one observation, and a verb called right after a navigating
+* `click()` takes it on the page being LEFT. The window may not decide
+* "nothing matches this whole name" on that reading: the destination has not
+* been parsed yet. Long enough for a navigation to commit, far short of the
+* verb's own 30 s, and paid only when there is a substring to widen to.
+*/
+const WINDOW_SETTLE_MS = 5e3;
+/**
+* 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 common case (the name matches
+* whole) costs one count per level, which waits for nothing.
+*/
+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, would designate
+* nothing either way, or turns out to be exact on the surface that ARRIVES.
+*
+* The last is the navigation case, and it is the reason the verdict is not two
+* counts: a `see()` fired right after a navigating `click()` counts the page
+* being left, so a descriptor that is perfectly exact on the DESTINATION read
+* as substring-only — non-deterministically, since which page each count
+* landed on was a race. A widening is therefore only decided once the exact
+* descriptor has been given the settle budget and still designates nothing.
+* The tell of the old fault was the printed name equalling the name written.
+*/
+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;
+		if (!alreadyJudged(candidate) && await probe.settles(candidate)) return;
+		await warnSubstringOnly(candidate, where, await probe.nameOf(loose), probe.print);
+		return loose;
+	} catch {
+		return;
+	}
+}
+/**
+* Has this descriptor already been judged substring-only in this run?
+*
+* The verdict is made once: a scenario that clicks the same link in ten tests
+* pays the settle budget on the first of them and is widened straight away on
+* the nine after it.
+*/
+function alreadyJudged(element) {
+	return reported.has(identityOf(element));
+}
 //#endregion
 //#region src/seams/vitest-browser/vitest-browser.adapter.ts
 /**
@@ -1490,21 +1627,63 @@ function ambiguousLevel(element) {
 	return element;
 }
 /**
+* The name to WRITE for this descriptor — the whole one, never truncated.
+*
+* A role descriptor matches the accessible name the browser computed, and a
+* page cannot compute one: the snapshot comes back from the node side, of the
+* one node the locator's own selector names. Text content would be the wrong
+* answer — it glues inline children with no separator and carries nothing of a
+* field's label — except for a `text` descriptor, which matches text.
+*/
+async function wholeNameOf(element) {
+	const locator = locate(page, element);
+	if (element.kind !== "text") try {
+		const named = accessibleNameIn(await commands.ariaNode(locator.selector));
+		if (named !== void 0) return named;
+	} catch {}
+	const collapsed = (locator.query()?.textContent ?? "").replaceAll(/\s+/gu, " ").trim();
+	return collapsed === "" ? void 0 : collapsed;
+}
+/**
+* Does the descriptor arrive if the subject is given the settle budget?
+*
+* A mounted component never navigates, but it does re-render: a subject whose
+* name arrives with the state after a click is the same question a page asks
+* across a navigation, and one window answers both. The poll is vitest's own,
+* with the window's budget rather than the test's — what is being waited for
+* here is a surface settling, not an assertion coming true.
+*/
+async function settles(element) {
+	try {
+		await expect.poll(() => locate(page, element).elements().length, { timeout: WINDOW_SETTLE_MS }).toBeGreaterThan(0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** 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) => await wholeNameOf(element),
+	print: async (line) => {
+		await commands.notify(line);
+	},
+	settles: async (element) => await settles(element)
+};
+/**
 * Run one visitor action, turning "more than one match" into the W3 refusal.
 * The ambiguous LEVEL is identified first: a scope matching several landmarks
 * is the real fault, and naming the target would send the author to fix the
 * 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 +1694,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
@@ -2801,7 +2962,7 @@ const specification = {
 	mobile: () => refuse("specification.mobile()"),
 	website: () => refuse("specification.website()")
 };
-const process = () => refuse("process()");
+const process$1 = () => refuse("process()");
 const ProcessHandle = nodeOnlyClass("ProcessHandle");
 const postgres = () => refuse("postgres()");
 const redis = () => refuse("redis()");
@@ -2816,4 +2977,4 @@ function text(value) {
 	return new TextAccessor(value, "text", "");
 }
 //#endregion
-export { Matcher, ProcessHandle, anthropic, banner, button, clock, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, focused, form, heading, http, intercept, link, listitem, main, match, mockOf, navigation, openai, option, postgres, process, redis, region, required, row, search, selected, specification, sqlite, status, table, testId, text, valued, waitUntil, within };
+export { Matcher, ProcessHandle, anthropic, banner, button, clock, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, focused, form, heading, http, intercept, link, listitem, main, match, mockOf, navigation, openai, option, postgres, process$1 as process, redis, region, required, row, search, selected, specification, sqlite, status, table, testId, text, valued, waitUntil, within };