@jterrazz/test 15.2.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 = [];
@@ -222,6 +315,7 @@ var PlaywrightAdapter = class {
 		}
 		try {
 			const page = await context.newPage();
+			if (options.clock !== void 0) await page.clock.setFixedTime(new Date(options.clock));
 			const consoleMessages = [];
 			page.on("console", (message) => {
 				consoleMessages.push({
@@ -278,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 { t as ContractQueue } from "./queue.js";
-//#region src/integrations/msw/handlers.ts
+import { a as isStreamBody, n as ContractQueue, t as toReadableStream } from "./stream.js";
+//#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
@@ -31,6 +31,14 @@ function toMswResponse(msw, response) {
 		},
 		status
 	});
+	if (isStreamBody(body)) return new msw.HttpResponse(toReadableStream(body), {
+		headers: {
+			...NEVER_CACHED,
+			"content-type": body.contentType,
+			...headers
+		},
+		status
+	});
 	if (typeof body === "string") return new msw.HttpResponse(body, {
 		headers: {
 			...NEVER_CACHED,
@@ -107,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/{queue.js → 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,36 @@ function contractsOf(input) {
 	return flatten([input]);
 }
 //#endregion
-//#region src/specification/contracts/queue.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,
+* the `node:http` stub) and each of them serialises "an object" as JSON, so a
+* stream declared as a plain value arrives as `{}`. The tag is what each
+* engine recognises before it reaches for `JSON.stringify`.
+*/
+const STREAM_BODY = "@jterrazz/test:stream";
+/** Is this body a declared stream rather than a value to serialise? */
+function isStreamBody(body) {
+	return typeof body === "object" && body !== null && "kind" in body && body.kind === "@jterrazz/test:stream";
+}
+//#endregion
+//#region src/model/timing/pause.ts
+/**
+* One answer to "wait" — the only `setTimeout` the model owns.
+*
+* Two things in the framework genuinely have to wait: the spacing between the
+* pieces of a declared stream, and the poll behind `waitUntil`. Everything
+* else that waits is a spec doing it by hand, which is what J2 refuses. Stated
+* once so there is one place to look when time stops behaving.
+*/
+async function pause(ms) {
+	await new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+//#endregion
+//#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
@@ -259,4 +288,34 @@ var ContractQueue = class {
 	}
 };
 //#endregion
-export { isContract as a, defineContracts as i, contractsOf as n, isContracts as o, defineContract as r, ContractQueue as t };
+//#region src/model/contracts/stream.ts
+/**
+* A declared stream, made real — ONE serialisation for all three engines.
+*
+* msw's server and msw's worker take a `ReadableStream` body verbatim
+* (https://mswjs.io/docs/http/mocking-responses/streaming) and the `node:http`
+* stub pipes one into its response, so what "arriving in pieces" MEANS —
+* the order, the spacing, the close after the last chunk — is stated here and
+* nowhere else. A second copy of it would be a second answer to "what does the
+* subject read", and the facets would drift.
+*/
+/**
+* The pieces of `body`, in order, `delayBetweenChunks` milliseconds apart,
+* closing after the last one.
+*/
+function toReadableStream(body) {
+	const encoder = new TextEncoder();
+	let index = 0;
+	return new ReadableStream({ async pull(controller) {
+		const chunk = body.chunks[index];
+		if (chunk === void 0) {
+			controller.close();
+			return;
+		}
+		if (body.delayBetweenChunks > 0 && index > 0) await pause(body.delayBetweenChunks);
+		index += 1;
+		controller.enqueue(encoder.encode(chunk));
+	} });
+}
+//#endregion
+export { isStreamBody as a, defineContracts as c, STREAM_BODY as i, isContract as l, ContractQueue as n, contractsOf as o, pause as r, defineContract as s, toReadableStream as t, isContracts as u };

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,24 +58,26 @@ 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 CommonOptions = {
+type FacetProjectOptions = {
   /**
-   * Replace the canonical `exclude` globs. A helper whose canonical
-   * `exclude` only guards its canonical `include` drops it when you state
-   * `include` alone, so state both or neither.
+   * Globs this project stays out of. On a facet helper they ADD to the
+   * preset's (`_fixtures/` and vitest's own), because vite concatenates. On
+   * `unit()` and `component()`, whose canonical `exclude` exists only to
+   * guard their canonical `include`, stating one replaces it — so state
+   * both or neither there.
    */
   exclude?: string[];
   /** Replace the canonical `include` globs. */
@@ -89,16 +91,31 @@ type CommonOptions = {
   /** Raise (or lower) the 30s budget for this project alone. */
   timeout?: number;
 };
-/** `unit()` — module tests, beside the modules they cover (CONVENTIONS I2). */
-type UnitProjectOptions = CommonOptions & {
+//#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 = CommonOptions;
+/**
+ * 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. */
@@ -130,14 +147,35 @@ type ComponentProjectOptions = {
    * provider). A router belongs on the chain instead: it is a test's Given.
    */
   wrap?: string;
-} & CommonOptions;
+} & 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.
+ * A component test renders in a real Chromium — the browser the website facet
+ * already drives through the same `playwright` peer.
+ *
+ * The default `include` reaches the whole project, so the default `exclude`
+ * keeps it out of `specs/`, where the assembled product is specified. State
+ * your own `include` and the exclusion is yours to state too.
  */
-declare function unit(options?: UnitProjectOptions): TestProjectInlineConfiguration;
+declare function component(options?: ComponentProjectOptions): Promise<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;
+//#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
@@ -145,14 +183,25 @@ declare function unit(options?: UnitProjectOptions): TestProjectInlineConfigurat
  * 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 trees module tests live in, when they do not live in `src/`. Each
+   * root becomes `<root>/**\/*.test.ts`; `include` states the globs outright.
+   */
+  roots?: string[];
+};
 /**
- * A component test renders in a real Chromium — the browser the website facet
- * already drives through the same `playwright` peer.
- *
- * The default `include` reaches the whole project, so the default `exclude`
- * keeps it out of `specs/`, where the assembled product is specified. State
- * your own `include` and the exclusion is yours to state too.
+ * 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 component(options?: ComponentProjectOptions): Promise<TestProjectInlineConfiguration>;
+declare function unit(options?: UnitProjectOptions): TestProjectInlineConfiguration;
 //#endregion
-export { type ComponentProjectOptions, type LiterateOptions, type LiteratePlugin, type SpecConfig, type UnitProjectOptions, type WebsiteProjectOptions, component, defineSpecConfig, literate, unit, website };
+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 };