@jterrazz/test 15.3.0 → 16.0.0

package/dist/playwright.adapter.js

@@ -3,12 +3,76 @@ 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/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 two-release window lasts, stated in the message itself. */
+const WINDOW = "16.0 and 16.1";
+/** 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) {
+	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.`);
+	return true;
+}
+//#endregion
+//#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 +81,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 } : {
@@ -62,15 +133,37 @@ async function act(page, element, action) {
 	try {
 		return await action(locate(page, element));
 	} catch (error) {
-		if (!isStrictViolation(error)) throw error;
+		if (!isStrictViolation(error)) {
+			await reportSubstringOnly(page, element);
+			throw error;
+		}
 		const culprit = await findAmbiguousLevel(page, element);
+		const matches = await captureMatches(locate(page, culprit));
 		throw new AmbiguousElementError(describeAmbiguity({
 			element: culprit,
-			matches: await captureMatches(locate(page, culprit)),
+			matches,
 			url: page.url()
 		}));
 	}
 }
+/**
+* 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.
+*/
+async function reportSubstringOnly(page, element) {
+	if (element.exact !== void 0 || element.name === void 0) return;
+	try {
+		if (await locate(page, element).count() > 0) return;
+		if (await locate(page, {
+			...element,
+			exact: false
+		}).count() > 0) warnSubstringOnly(element, page.url());
+	} catch {}
+}
 /** Walk the scope chain outside-in; the outermost ambiguous level is the fault. */
 async function findAmbiguousLevel(page, element) {
 	const chain = [];
@@ -279,7 +372,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/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 };