@jterrazz/test 15.3.0 → 16.1.0

package/dist/playwright.adapter.js

@@ -1,14 +1,37 @@
-import { n as describeAmbiguity, r as formatElement, t as AmbiguousElementError } from "./ambiguity.js";
+import { a as formatElement, i as describeAmbiguity, n as widenedForWindow, r as AmbiguousElementError } from "./substring-warning.js";
 import { mkdtempSync } from "node:fs";
 import { resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { setTimeout } from "node:timers/promises";
-//#region src/integrations/playwright/playwright.adapter.ts
+//#region src/seams/playwright/playwright.adapter.ts
 /** How many candidates the ambiguity error enumerates before truncating. */
 const MAX_REPORTED_MATCHES = 10;
 const VALUE_TIMEOUT_MS = 3e4;
 const VALUE_POLL_MS = 100;
 /**
+* The roles a FIELD can carry — what `field('Name')` designates.
+*
+* A field is named by its ACCESSIBLE name, not by the text of the label
+* element that happens to wrap it: `<label><span>Channel</span><select>…` has
+* a label whose text carries every option of the select, while the control's
+* accessible name is `Channel` — which is what the ARIA tree shows and what a
+* screen reader reads. Resolving by label text alone made the ordinary
+* wrapping-label form unreachable under the 16.0 whole-name default.
+*
+* The label-text locator stays in the union for the controls ARIA gives no
+* role at all (a date or colour input), which nothing else would find.
+*/
+const FIELD_ROLES = [
+	"checkbox",
+	"combobox",
+	"radio",
+	"searchbox",
+	"slider",
+	"spinbutton",
+	"switch",
+	"textbox"
+];
+/**
 * Translate a user-facing descriptor into a playwright locator, resolving
 * `scope` outside-in so `within(navigation(), link('X'))` searches the nav
 * subtree. No `.first()` anywhere: playwright's strict mode is the mechanism
@@ -17,9 +40,16 @@ const VALUE_POLL_MS = 100;
 */
 function locate(root, element) {
 	const scope = element.scope ? locate(root, element.scope) : root;
-	const exact = element.exact ?? false;
+	const exact = element.exact ?? true;
 	const name = element.name ?? "";
-	if (element.kind === "field") return scope.getByLabel(name, { exact });
+	if (element.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 (element.kind === "testId") return scope.getByTestId(name);
 	if (element.kind === "text") return scope.getByText(name, { exact });
 	return scope.getByRole(element.kind, element.name === void 0 ? { exact } : {
@@ -59,18 +89,30 @@ async function captureMatches(locator) {
 * would send the author to fix the wrong descriptor.
 */
 async function act(page, element, action) {
+	const target = await widenedForWindow(element, page.url(), probeOf(page)) ?? element;
 	try {
-		return await action(locate(page, element));
+		return await action(locate(page, target));
 	} catch (error) {
 		if (!isStrictViolation(error)) throw error;
-		const culprit = await findAmbiguousLevel(page, element);
+		const culprit = await findAmbiguousLevel(page, target);
+		const matches = await captureMatches(locate(page, culprit));
 		throw new AmbiguousElementError(describeAmbiguity({
 			element: culprit,
-			matches: await captureMatches(locate(page, culprit)),
+			matches,
 			url: page.url()
 		}));
 	}
 }
+/** What the transitional window may ask of the page. */
+function probeOf(page) {
+	return {
+		count: async (element) => await locate(page, element).count(),
+		nameOf: async (element) => {
+			const [match] = await captureMatches(locate(page, element));
+			return match?.accessibleName ?? match?.text;
+		}
+	};
+}
 /** Walk the scope chain outside-in; the outermost ambiguous level is the fault. */
 async function findAmbiguousLevel(page, element) {
 	const chain = [];
@@ -279,7 +321,8 @@ var PlaywrightAdapter = class {
 	/** Screenshot the failing state into a temp file; never masks the original error. */
 	async captureEvidence(page) {
 		try {
-			const path = resolve(mkdtempSync(resolve(tmpdir(), "spec-website-")), "failure.png");
+			const dir = mkdtempSync(resolve(tmpdir(), "spec-website-"));
+			const path = resolve(dir, "failure.png");
 			await page.screenshot({
 				fullPage: true,
 				path

package/dist/{intercept.js → server.js}

@@ -1,5 +1,5 @@
 import { a as isStreamBody, n as ContractQueue, t as toReadableStream } from "./stream.js";
-//#region src/integrations/msw/handlers.ts
+//#region src/seams/msw/handlers.ts
 /**
 * What a chain with zero contracts gets where the facet's scope is KNOWN but
 * not total — the node engine, which shares a process with everything else the
@@ -115,7 +115,7 @@ async function observe(request) {
 	};
 }
 //#endregion
-//#region src/integrations/msw/intercept.ts
+//#region src/seams/msw/server.ts
 let mswModule = null;
 let mswHttp = null;
 async function loadMsw() {

package/dist/stream.js

@@ -1,6 +1,6 @@
 import { t as CaptureScope } from "./match.js";
-import { I as textEquals, M as placeholderPatternSource, k as hasPlaceholders } from "./artifacts.js";
-//#region src/specification/contracts/contract.ts
+import { A as placeholderPatternSource, D as hasPlaceholders, P as textEquals } from "./literate.js";
+//#region src/model/contracts/contract.ts
 /**
 * Declare one contract. Identity function — its value is the enforced shape
 * and the naming convention:
@@ -86,7 +86,7 @@ function contractsOf(input) {
 	return flatten([input]);
 }
 //#endregion
-//#region src/specification/contracts/types.ts
+//#region src/model/contracts/types.ts
 /**
 * The marker that tells a STREAMED body from a value that happens to be an
 * object. A body reaches three different engines (msw's server, msw's worker,
@@ -100,7 +100,7 @@ function isStreamBody(body) {
 	return typeof body === "object" && body !== null && "kind" in body && body.kind === "@jterrazz/test:stream";
 }
 //#endregion
-//#region src/specification/timing/pause.ts
+//#region src/model/timing/pause.ts
 /**
 * One answer to "wait" — the only `setTimeout` the model owns.
 *
@@ -115,7 +115,7 @@ async function pause(ms) {
 	});
 }
 //#endregion
-//#region src/specification/contracts/queue.ts
+//#region src/model/contracts/queue.ts
 /**
 * The ONE contract queue — pure, engine-agnostic (no MSW, no node:http).
 * Both engines consume it: the MSW integration on api/jobs chains, and the
@@ -288,7 +288,7 @@ var ContractQueue = class {
 	}
 };
 //#endregion
-//#region src/specification/contracts/stream.ts
+//#region src/model/contracts/stream.ts
 /**
 * A declared stream, made real — ONE serialisation for all three engines.
 *

package/dist/{ambiguity.js → substring-warning.js}

@@ -1,4 +1,4 @@
-//#region src/specification/facets/website/ambiguity.ts
+//#region src/model/elements/ambiguity.ts
 /**
 * The ambiguity refusal — CONVENTIONS W3.
 *
@@ -52,8 +52,9 @@ const CONTEXT_LANDMARKS = {
 };
 /**
 * Render a descriptor as the source that would build it — `link('Articles')`,
-* `within(navigation(), link('Articles', { exact: true }))`. The error speaks
-* the vocabulary the author wrote, never playwright's.
+* `within(navigation(), link('Articles', { exact: false }))`. The error speaks
+* the vocabulary the author wrote, never playwright's — so the option appears
+* only when the AUTHOR stated one, whichever way.
 */
 function formatElement(element) {
 	const bare = formatBare(element);
@@ -62,7 +63,7 @@ function formatElement(element) {
 function formatBare(element) {
 	const args = [];
 	if (element.name !== void 0) args.push(JSON.stringify(element.name));
-	if (element.exact) args.push("{ exact: true }");
+	if (element.exact !== void 0) args.push(`{ exact: ${String(element.exact)} }`);
 	return `${CONSTRUCTORS[element.kind]}(${args.join(", ")})`;
 }
 /** `1. <a href="/articles">Articles</a>  in <nav>` — one evidence line per candidate. */
@@ -98,7 +99,7 @@ function formatFixes(element, matches) {
 		const alsoHere = rest.length > 0 ? `   [also here: ${rest.map(([name]) => name).join(", ")}]` : "";
 		fixes.push(first === void 0 ? `scope it       within(<a container holding only this one>, ${formatBare(element)})` : `scope it       within(${first[0]}, ${formatBare(element)})   [leaves ${first[1]} of ${matches.length}]${alsoHere}`);
 	}
-	if (!element.exact && element.name !== void 0) {
+	if (element.exact === false && element.name !== void 0) {
 		const remaining = matches.filter((match) => match.text === element.name).length;
 		if (remaining > 0 && remaining < matches.length) fixes.push(`exact name     ${formatBare({
 			...element,
@@ -138,8 +139,106 @@ function describeAmbiguity(options) {
 		"Disambiguate with one of:",
 		...fixes,
 		"",
-		"Docs: docs/14-website.md#designating-exactly-one-element (CONVENTIONS W3)"
+		"Docs: docs/13-elements.md#designating-exactly-one-element (CONVENTIONS W3)"
 	].join("\n");
 }
 //#endregion
-export { describeAmbiguity as n, formatElement as r, AmbiguousElementError as t };
+//#region src/model/elements/substring-warning.ts
+/**
+* The transitional warning for a name that matches only as a SUBSTRING.
+*
+* Until 16.0 a descriptor's name matched any element whose accessible name
+* CONTAINED it, so `link('Articles')` also designated "Read Articles" — and a
+* test could pass for years against the wrong element without anyone noticing,
+* because the wrong element was usually next to the right one. Exact is the
+* default now.
+*
+* A lint rule cannot carry this: whether a name matched whole or in part is a
+* fact about a RUN, and a verdict fed by a previous run's artefact is not
+* deterministic. So it is a runtime warning, printed by the adapter that did
+* the looking, at the moment it has both answers in hand — nothing found under
+* exact, something found under substring.
+*
+* 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 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. */
+function identityOf(element) {
+	const own = `${element.kind}:${element.name ?? ""}`;
+	return element.scope === void 0 ? own : `${identityOf(element.scope)}>${own}`;
+}
+/**
+* Report that `element` designated nothing as a whole name, but would have
+* designated something as a substring. Returns whether a line was printed,
+* which is what the adapters' own tests assert on.
+*/
+function warnSubstringOnly(element, where, found) {
+	const identity = identityOf(element);
+	if (reported.has(identity)) return false;
+	reported.add(identity);
+	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
+export { formatElement as a, describeAmbiguity as i, widenedForWindow as n, AmbiguousElementError as r, warnSubstringOnly as t };

package/dist/vitest.d.ts

@@ -1,6 +1,6 @@
 import { TestProjectInlineConfiguration, ViteUserConfig } from "vitest/config";
 import { UserConfig, UserConfigFn } from "vite";
-//#region src/vitest/literate-plugin.d.ts
+//#region src/runner/literate-plugin.d.ts
 type LiterateOptions = {
   /**
    * Globs added to the project's test include. Default: every `.spec.yaml`
@@ -40,7 +40,7 @@ type LiteratePlugin = {
 };
 declare function literate(options: LiterateOptions): LiteratePlugin;
 //#endregion
-//#region src/vitest/preset.d.ts
+//#region src/runner/preset.d.ts
 /**
  * Options are a vite/vitest config plus one key of the framework's own.
  * Everything stated here wins over the preset's defaults.
@@ -58,17 +58,17 @@ type SpecConfig = {
 } & ViteUserConfig;
 declare function defineSpecConfig(config?: SpecConfig): ViteUserConfig;
 //#endregion
-//#region src/vitest/projects.d.ts
+//#region src/runner/facet-project.d.ts
 /**
- * The project helpers — one per kind of test, each the canonical project that
- * kind runs in.
+ * The node facets' canonical projects.
  *
- * A project is not a matter of taste: `--project component` has to mean the
- * same thing in every repository of the ecosystem, and what a browser project
- * needs (a provider pinned to the runner, a service worker, a Vite pipeline,
- * an artefact directory that is not the repository root) is the framework's to
- * know, not the consumer's to rediscover. So the consumer names the kind and
- * states only what is theirs.
+ * Each one collects the facet's own tree — `specs/<facet>/**\/*.spec.ts`, the
+ * suffix that says "the assembled product" — carries the preset's budgets and
+ * artefact directory, and runs in group 0 — the browser facets follow, so two
+ * Chromiums never share a slot on a two-vCPU runner. `{ include, exclude,
+ * timeout, serial }` is what a repository states when its tree, its budget or
+ * its parallelism differs;
+ * everything else is the framework's.
  */
 /** What every helper accepts on top of its canonical project. */
 type FacetProjectOptions = {
@@ -91,16 +91,31 @@ type FacetProjectOptions = {
   /** Raise (or lower) the 30s budget for this project alone. */
   timeout?: number;
 };
-/** `unit()` — module tests, beside the modules they cover (CONVENTIONS I2). */
-type UnitProjectOptions = FacetProjectOptions & {
+//#endregion
+//#region src/facets/api/api.project.d.ts
+/** `api()` — the app met through HTTP. */
+declare function api(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+//#endregion
+//#region src/facets/cli/cli.project.d.ts
+/** `cli()` — a binary, and the documents that specify it. */
+type CliProjectOptions = FacetProjectOptions & {
   /**
-   * The trees module tests live in, when they do not live in `src/`. Each
-   * root becomes `<root>/**\/*.test.ts`; `include` states the globs outright.
+   * The literate door, wired by default: every `specs/cli/**\/*.spec.yaml`
+   * becomes a test file bound to `specs/cli/cli.specification.ts`. State
+   * `specification` to name another runner, `include` to narrow the glob, or
+   * `false` to collect no documents at all.
    */
-  roots?: string[];
+  literate?: false | Partial<LiterateOptions>;
 };
-/** `website()` — the assembled product, met through a served page. */
-type WebsiteProjectOptions = FacetProjectOptions;
+/**
+ * A cli project collects the facet's `.test.ts` files AND its documents: a
+ * `<case>.spec.yaml` is a test file of its own (docs/07 § the literate door),
+ * so the plugin's glob has to join the include of the project that collects
+ * them — which is this one, never the root config.
+ */
+declare function cli(options?: CliProjectOptions): TestProjectInlineConfiguration;
+//#endregion
+//#region src/facets/component/component.project.d.ts
 /** `component()` — rendered units, beside the components they cover. */
 type ComponentProjectOptions = {
   /** Freeze the page's `Date` for every render of the project. */
@@ -133,20 +148,6 @@ type ComponentProjectOptions = {
    */
   wrap?: string;
 } & FacetProjectOptions;
-/**
- * A module test runs beside the module it covers: no DOM, no browser, no
- * pipeline. `.test.tsx` is excluded because a rendered thing is a component
- * test — a project's dependency scan reads every file its globs match, and a
- * `.tsx` collected here would be optimised for a page that never opens.
- */
-declare function unit(options?: UnitProjectOptions): TestProjectInlineConfiguration;
-/**
- * A website spec meets the assembled product through a served page, in the
- * Chromium playwright drives. It opens a browser, so it is scheduled before the
- * component project and never beside it: two Chromiums must not share a slot on
- * a 2-vCPU runner.
- */
-declare function website(options?: WebsiteProjectOptions): TestProjectInlineConfiguration;
 /**
  * A component test renders in a real Chromium — the browser the website facet
  * already drives through the same `playwright` peer.
@@ -156,33 +157,51 @@ declare function website(options?: WebsiteProjectOptions): TestProjectInlineConf
  * your own `include` and the exclusion is yours to state too.
  */
 declare function component(options?: ComponentProjectOptions): Promise<TestProjectInlineConfiguration>;
-/** `api()` — the app met through HTTP. */
-declare function api(options?: FacetProjectOptions): TestProjectInlineConfiguration;
-/** `jobs()` — what a name triggers in-process. */
-declare function jobs(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+//#endregion
+//#region src/facets/integration/integration.project.d.ts
 /** `integration()` — a module against real services, or against a golden. */
 declare function integration(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+//#endregion
+//#region src/facets/jobs/jobs.project.d.ts
+/** `jobs()` — what a name triggers in-process. */
+declare function jobs(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+//#endregion
+//#region src/facets/mobile/mobile.project.d.ts
 /**
  * `mobile()` — the app on a simulator. A simulator is the one thing that
  * cannot share a machine with itself, so it runs last and alone (group 3).
  */
 declare function mobile(options?: FacetProjectOptions): TestProjectInlineConfiguration;
-/** `cli()` — a binary, and the documents that specify it. */
-type CliProjectOptions = FacetProjectOptions & {
+//#endregion
+//#region src/facets/website/website.project.d.ts
+/** `website()` — the assembled product, met through a served page. */
+type WebsiteProjectOptions = FacetProjectOptions;
+/**
+ * A website spec meets the assembled product through a served page, in the
+ * Chromium playwright drives. It opens a browser, so it is scheduled before the
+ * component project and never beside it: two Chromiums must not share a slot on
+ * a 2-vCPU runner.
+ */
+declare function website(options?: WebsiteProjectOptions): TestProjectInlineConfiguration;
+//#endregion
+//#region src/runner/projects.d.ts
+/** `unit()` — module tests, beside the modules they cover (CONVENTIONS I2). */
+type UnitProjectOptions = FacetProjectOptions & {
   /**
-   * The literate door, wired by default: every `specs/cli/**\/*.spec.yaml`
-   * becomes a test file bound to `specs/cli/cli.specification.ts`. State
-   * `specification` to name another runner, `include` to narrow the glob, or
-   * `false` to collect no documents at all.
+   * The trees module tests live in, when they do not live in `src/`. Each
+   * root becomes `<root>/**\/*.test.ts`; `include` states the globs outright.
    */
-  literate?: false | Partial<LiterateOptions>;
+  roots?: string[];
 };
 /**
- * A cli project collects the facet's `.test.ts` files AND its documents: a
- * `<case>.spec.yaml` is a test file of its own (docs/07 § the literate door),
- * so the plugin's glob has to join the include of the project that collects
- * them — which is this one, never the root config.
+ * A module test runs beside the module it covers: no DOM, no browser, no
+ * pipeline. Its suffix is `.test.ts` and its place is OUTSIDE `specs/`, where
+ * the assembled product is specified in `.spec.ts` — the two exclusions say
+ * exactly that. `.test.tsx` is the third exclusion because a rendered thing is
+ * a component test: a project's dependency scan reads every file its globs
+ * match, and a `.tsx` collected here would be optimised for a page that never
+ * opens.
  */
-declare function cli(options?: CliProjectOptions): TestProjectInlineConfiguration;
+declare function unit(options?: UnitProjectOptions): TestProjectInlineConfiguration;
 //#endregion
 export { type CliProjectOptions, type ComponentProjectOptions, type FacetProjectOptions, type LiterateOptions, type LiteratePlugin, type SpecConfig, type UnitProjectOptions, type WebsiteProjectOptions, api, cli, component, defineSpecConfig, integration, jobs, literate, mobile, unit, website };