@jterrazz/test 15.1.1 → 15.3.0

package/dist/playwright.adapter.js

@@ -1,10 +1,13 @@
-import { n as describeAmbiguity, t as AmbiguousElementError } from "./ambiguity.js";
+import { n as describeAmbiguity, r as formatElement, t as AmbiguousElementError } from "./ambiguity.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
 /** How many candidates the ambiguity error enumerates before truncating. */
 const MAX_REPORTED_MATCHES = 10;
+const VALUE_TIMEOUT_MS = 3e4;
+const VALUE_POLL_MS = 100;
 /**
 * Translate a user-facing descriptor into a playwright locator, resolving
 * `scope` outside-in so `within(navigation(), link('X'))` searches the nav
@@ -14,26 +17,15 @@ const MAX_REPORTED_MATCHES = 10;
 */
 function locate(root, element) {
 	const scope = element.scope ? locate(root, element.scope) : root;
-	const options = element.name === void 0 ? { exact: element.exact ?? false } : {
-		exact: element.exact ?? false,
+	const exact = element.exact ?? false;
+	const name = element.name ?? "";
+	if (element.kind === "field") return scope.getByLabel(name, { exact });
+	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 } : {
+		exact,
 		name: element.name
-	};
-	switch (element.kind) {
-		case "banner":
-		case "complementary":
-		case "contentinfo":
-		case "form":
-		case "main":
-		case "navigation":
-		case "region":
-		case "search": return scope.getByRole(element.kind, options);
-		case "button":
-		case "heading":
-		case "link": return scope.getByRole(element.kind, options);
-		case "field": return scope.getByLabel(element.name ?? "", { exact: element.exact ?? false });
-		case "testId": return scope.getByTestId(element.name ?? "");
-		case "text": return scope.getByText(element.name ?? "", { exact: element.exact ?? false });
-	}
+	});
 }
 /** Playwright signals "more than one match" through this error text. */
 function isStrictViolation(error) {
@@ -48,11 +40,14 @@ async function captureMatches(locator) {
 			const landmark = element.parentElement?.closest(LANDMARKS);
 			const context = landmark ? landmark.getAttribute("role") ?? landmark.tagName.toLowerCase() : null;
 			const detail = element.getAttribute("href") ?? element.getAttribute("name");
+			const text = (element.textContent ?? "").replaceAll(/\s+/gu, " ").trim().slice(0, 80);
+			const label = element.getAttribute("aria-label")?.trim();
 			return {
+				accessibleName: label && label !== text ? label : void 0,
 				context: context ?? void 0,
 				detail: detail ?? void 0,
 				tag: element.tagName.toLowerCase(),
-				text: (element.textContent ?? "").replaceAll(/\s+/gu, " ").trim().slice(0, 80)
+				text
 			};
 		});
 	}, MAX_REPORTED_MATCHES);
@@ -83,6 +78,59 @@ async function findAmbiguousLevel(page, element) {
 	for (const level of chain.slice(0, -1)) if (await locate(page, level).count() > 1) return level;
 	return element;
 }
+/**
+* The same element, narrowed by whatever STATE the descriptor carries — focus,
+* or accepting input — or `null` when it carries none.
+*
+* A second condition on the locator rather than a one-shot probe: the locator
+* keeps playwright's own retry, so `see(focused(x))` waits for the keyboard to
+* arrive instead of asking once and failing on a frame of animation. It also
+* needs nothing but `playwright` — `expect(...).toBeFocused()` lives in
+* `@playwright/test`, which this package deliberately does not carry.
+*/
+function stateOnly(page, locator, element) {
+	if (element.focused === true) return locator.and(page.locator(":focus"));
+	if (element.disabled !== void 0) return locator.and(page.locator(element.disabled ? ":disabled" : ":enabled"));
+	if (element.selected !== void 0) return locator.and(page.locator(element.selected ? ":checked" : ":not(:checked)"));
+	return null;
+}
+/**
+* Is this descriptor answered by PRESENCE rather than by visibility? The
+* options of a collapsed `<select>` are in the document and in the tree, and
+* none of them has a box on the screen until a visitor opens it.
+*/
+function byPresence(element) {
+	return element.kind === "option";
+}
+/** The field's live value, or `null` when nothing (unambiguous) is there yet. */
+async function currentValue(locator) {
+	try {
+		return await locator.inputValue({ timeout: VALUE_POLL_MS });
+	} catch (error) {
+		if (isStrictViolation(error)) throw error;
+		return null;
+	}
+}
+/**
+* Wait until the field holds the value the descriptor carries — or, for
+* `gone()`, until it no longer does.
+*
+* A poll rather than a narrowed locator: a value is a PROPERTY of the node,
+* and the CSS a locator narrows with reads ATTRIBUTES — a controlled input
+* whose `value` attribute never moves would answer for a value it no longer
+* holds. The locator is re-read every round, so a re-rendered field is read
+* again rather than held as a stale handle.
+*/
+async function waitForValue(locator, element, wanted) {
+	const value = element.value ?? "";
+	const deadline = Date.now() + VALUE_TIMEOUT_MS;
+	for (;;) {
+		const actual = await currentValue(locator);
+		if (actual === null ? !wanted : actual === value === wanted) return;
+		if (Date.now() >= deadline) throw new Error(`${formatElement(element)} ${wanted ? "never held" : "still holds"} ${JSON.stringify(value)}${actual === null ? " (it is not on the page)" : `, it holds ${JSON.stringify(actual)}`}`);
+		await setTimeout(VALUE_POLL_MS);
+	}
+}
 /** The visitor implementation — every action auto-waits via playwright actionability. */
 function createVisitor(page, baseUrl) {
 	return {
@@ -112,9 +160,32 @@ function createVisitor(page, baseUrl) {
 		press: async (key) => {
 			await page.keyboard.press(key);
 		},
+		gone: async (element) => {
+			await act(page, element, async (locator) => {
+				if (element.value !== void 0) {
+					await waitForValue(locator, element, false);
+					return;
+				}
+				const narrowed = stateOnly(page, locator, element);
+				if (narrowed !== null) {
+					await narrowed.waitFor({ state: "detached" });
+					return;
+				}
+				await locator.waitFor({ state: byPresence(element) ? "detached" : "hidden" });
+			});
+		},
 		see: async (element) => {
 			await act(page, element, async (locator) => {
-				await locator.waitFor({ state: "visible" });
+				if (element.value !== void 0) {
+					await waitForValue(locator, element, true);
+					return;
+				}
+				const narrowed = stateOnly(page, locator, element);
+				if (narrowed !== null) {
+					await narrowed.waitFor({ state: "attached" });
+					return;
+				}
+				await locator.waitFor({ state: byPresence(element) ? "attached" : "visible" });
 			});
 		},
 		select: async (element, option) => {
@@ -151,6 +222,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({
@@ -192,9 +264,11 @@ var PlaywrightAdapter = class {
 					title: document.title
 				};
 			});
+			const tree = await page.locator("body").ariaSnapshot();
 			return {
 				consoleMessages,
 				status: response?.status() ?? 0,
+				tree,
 				url: page.url(),
 				...extraction
 			};

package/dist/{queue.js → stream.js}

@@ -1,5 +1,5 @@
 import { t as CaptureScope } from "./match.js";
-import { A as placeholderPatternSource, D as hasPlaceholders, P as textEquals } from "./artifacts.js";
+import { I as textEquals, M as placeholderPatternSource, k as hasPlaceholders } from "./artifacts.js";
 //#region src/specification/contracts/contract.ts
 /**
 * Declare one contract. Identity function — its value is the enforced shape
@@ -86,6 +86,35 @@ function contractsOf(input) {
 	return flatten([input]);
 }
 //#endregion
+//#region src/specification/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/specification/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/specification/contracts/queue.ts
 /**
 * The ONE contract queue — pure, engine-agnostic (no MSW, no node:http).
@@ -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/specification/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,4 +1,5 @@
-import { ViteUserConfig } from "vitest/config";
+import { TestProjectInlineConfiguration, ViteUserConfig } from "vitest/config";
+import { UserConfig, UserConfigFn } from "vite";
 //#region src/vitest/literate-plugin.d.ts
 type LiterateOptions = {
   /**
@@ -57,4 +58,131 @@ type SpecConfig = {
 } & ViteUserConfig;
 declare function defineSpecConfig(config?: SpecConfig): ViteUserConfig;
 //#endregion
-export { type LiterateOptions, type LiteratePlugin, type SpecConfig, defineSpecConfig, literate };
+//#region src/vitest/projects.d.ts
+/**
+ * The project helpers — one per kind of test, each the canonical project that
+ * kind runs in.
+ *
+ * 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.
+ */
+/** What every helper accepts on top of its canonical project. */
+type FacetProjectOptions = {
+  /**
+   * 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. */
+  include?: string[];
+  /**
+   * Run this project's files ONE AT A TIME (`fileParallelism: false`) — for
+   * the facets whose files share something a second worker would collide
+   * with: one served app, one database file, one browser profile.
+   */
+  serial?: boolean;
+  /** 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 & {
+  /**
+   * 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[];
+};
+/** `website()` — the assembled product, met through a served page. */
+type WebsiteProjectOptions = FacetProjectOptions;
+/** `component()` — rendered units, beside the components they cover. */
+type ComponentProjectOptions = {
+  /** Freeze the page's `Date` for every render of the project. */
+  clock?: string;
+  /** `Accept-Language` and `Intl` locale of the page. Default `'en-US'`. */
+  locale?: string;
+  /**
+   * The directory `vite` and `wrap` are resolved against. Default: the
+   * directory of the file that CALLED the helper — see
+   * {@link callerDirectory}. State it when the call is not written in the
+   * config it configures (a shared config factory).
+   */
+  root?: string;
+  /** IANA zone the page's `Date` reports in. Default `'UTC'`. */
+  timezone?: string;
+  /**
+   * The app's own Vite pipeline: a config path, the object, or the function
+   * a framework exports. Only the PIPELINE is adopted (see {@link reroot}).
+   */
+  vite?: Promise<UserConfig> | string | UserConfig | UserConfigFn;
+  /** The page size every render gets. Default 1280×720. */
+  viewport?: {
+    height: number;
+    width: number;
+  };
+  /**
+   * A module whose default export is `(ui) => ReactNode` — the providers
+   * every render of this project is dressed in (a theme, a store, an intl
+   * provider). A router belongs on the chain instead: it is a test's Given.
+   */
+  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.
+ *
+ * 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 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;
+/** `integration()` — a module against real services, or against a golden. */
+declare function integration(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+/**
+ * `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 & {
+  /**
+   * 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.
+   */
+  literate?: false | Partial<LiterateOptions>;
+};
+/**
+ * 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
+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 };