@jterrazz/test 9.2.1 → 10.0.0

package/dist/index.d.ts

@@ -497,15 +497,53 @@ interface InterceptContract {
 declare function defineContract(contract: InterceptContract): InterceptContract;
 //#endregion
 //#region src/core/ports/browser.port.d.ts
+/**
+ * The landmark roles — the standard set of page regions, and the only
+ * containers a scope can name. Closed on purpose: ARIA defines exactly these,
+ * so `within()` never becomes a second selector language.
+ */
+type LandmarkKind = 'banner' | 'complementary' | 'contentinfo' | 'form' | 'main' | 'navigation' | 'region' | 'search';
+/** The interactive//textual element kinds — what a visitor actually acts on. */
+type ElementKind = 'button' | 'field' | 'heading' | 'link' | 'testId' | 'text';
 /**
  * A user-facing element descriptor — pure data, built by the element
  * vocabulary (`button()`, `link()`, `field()`, …) and translated into
  * concrete locators by the browser integration. CSS/XPath selectors are
  * deliberately not expressible: user-facing elements are the only surface.
+ *
+ * A descriptor must designate exactly ONE element at action time; see
+ * {@link ElementMatch} and CONVENTIONS W3.
  */
 interface ElementRef {
-  kind: 'button' | 'field' | 'heading' | 'link' | 'testId' | 'text';
-  name: string;
+  /**
+   * Match the accessible name as a whole string rather than a substring.
+   * Default (`false`) mirrors playwright: `link('Articles')` also matches
+   * "Read Articles".
+   */
+  exact?: boolean;
+  kind: ElementKind | LandmarkKind;
+  /** Landmarks may be anonymous (`main()`, `banner()`); everything else is named. */
+  name?: string;
+  /**
+   * Restrict the search to the elements of another descriptor — built by
+   * `within(scope, target)`. Chains: a scope may itself carry a scope.
+   */
+  scope?: ElementRef;
+}
+/**
+ * One candidate captured when a descriptor matched more than one element —
+ * the evidence the ambiguity error enumerates so the author can disambiguate
+ * without opening a browser.
+ */
+interface ElementMatch {
+  /** Nearest landmark ancestor (`nav`, `footer`, `main`…), when there is one. */
+  context?: string;
+  /** The attribute that disambiguates most — `href` for links, `name` for fields. */
+  detail?: string;
+  /** Tag name, lower-cased. */
+  tag: string;
+  /** Text content, whitespace-collapsed and truncated. */
+  text: string;
 }
 /** A `<link>` element captured from the rendered document's head. */
 interface BrowserLinkElement {
@@ -1468,19 +1506,63 @@ interface ContainerPort {
  * Reads like English (`click(link('Articles'))`), translates to
  * accessibility-first locators in the browser integration. CSS/XPath is
  * deliberately not expressible; `testId()` is the single escape hatch.
+ *
+ * A descriptor must designate exactly ONE element (CONVENTIONS W3). Two knobs
+ * narrow it, in this order of preference:
+ *
+ *   1. `within(scope, target)` — search inside a landmark, the way a person
+ *      would say "the Articles link *in the nav*";
+ *   2. `{ exact: true }` — match the accessible name whole rather than as a
+ *      substring, when two names genuinely overlap.
  */
+/** Options accepted by every named descriptor. */
+interface ElementOptions {
+  /**
+   * Match the accessible name as a whole string. Default is substring —
+   * `link('Articles')` also matches "Read Articles".
+   */
+  exact?: boolean;
+}
 /** A button (or element with the button role), by accessible name. */
-declare const button: (name: string) => ElementRef;
+declare const button: (name: string, options?: ElementOptions) => ElementRef;
 /** A form field, by label. */
-declare const field: (label: string) => ElementRef;
+declare const field: (name: string, options?: ElementOptions) => ElementRef;
 /** A heading, by accessible name. */
-declare const heading: (name: string) => ElementRef;
+declare const heading: (name: string, options?: ElementOptions) => ElementRef;
 /** A link, by accessible name. */
-declare const link: (name: string) => ElementRef;
+declare const link: (name: string, options?: ElementOptions) => ElementRef;
 /** An element containing the given text. */
-declare const content: (value: string) => ElementRef;
+declare const content: (name: string, options?: ElementOptions) => ElementRef;
 /** The escape hatch: an element by `data-testid`. Prefer user-facing elements. */
 declare const testId: (id: string) => ElementRef;
+/** The `banner` landmark — the page header. */
+declare const banner: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `complementary` landmark — an `<aside>`, a sidebar. */
+declare const complementary: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `contentinfo` landmark — the page footer. */
+declare const contentinfo: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `form` landmark — a form carrying an accessible name. */
+declare const form: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `main` landmark — the primary content of the document. */
+declare const main: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `navigation` landmark — a `<nav>`. Name it when a page has several. */
+declare const navigation: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `region` landmark — a `<section>` carrying an accessible name. */
+declare const region: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `search` landmark. */
+declare const search: (name?: string, options?: ElementOptions) => ElementRef;
+/**
+ * Restrict a descriptor to the inside of another — the answer to ambiguity,
+ * and the one the framework prefers over a test id.
+ *
+ *     click(within(navigation(), link('Articles')))
+ *
+ * Composes outside-in: the scope may itself be scoped, so a deeply nested
+ * target reads `within(main(), within(region('Series'), link('Part 2')))`.
+ * Any descriptor works as a scope, including `testId()` when a container has
+ * no landmark role to stand on.
+ */
+declare const within: (scope: ElementRef, target: ElementRef) => ElementRef;
 //#endregion
 //#region src/integrations/postgres/postgres.d.ts
 interface PostgresOptions {
@@ -1809,4 +1891,4 @@ declare module 'vitest' {
   }
 }
 //#endregion
-export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type DatabaseKeys, type DatabasePort, DirectoryAccessor, type DockerSpecConfig, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, HttpResult, type InterceptContract, type InterceptEntry, type InterceptResponder, type InterceptResponse, type InterceptResponseValue, type InterceptTrigger, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type VisitScenario, type Visitor, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, button, content, defineContract, field, findContainersByLabel, heading, http, inspectContainer, link, match, mockOf, mockOfDate, openai, postgres, redis, removeContainers, specification, sqlite, testId, text };
+export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type DatabaseKeys, type DatabasePort, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, HttpResult, type InterceptContract, type InterceptEntry, type InterceptResponder, type InterceptResponse, type InterceptResponseValue, type InterceptTrigger, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type VisitScenario, type Visitor, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, complementary, content, contentinfo, defineContract, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };

package/dist/index.js

@@ -3637,42 +3637,65 @@ const specification = {
 };
 //#endregion
 //#region src/core/specification/website/elements.ts
-/**
-* The element vocabulary — user-facing descriptors for visit scenarios.
-* Reads like English (`click(link('Articles'))`), translates to
-* accessibility-first locators in the browser integration. CSS/XPath is
-* deliberately not expressible; `testId()` is the single escape hatch.
-*/
-/** A button (or element with the button role), by accessible name. */
-const button = (name) => ({
-	kind: "button",
-	name
+const named = (kind) => (name, options) => ({
+	kind,
+	name,
+	...options?.exact ? { exact: true } : {}
 });
+/** A button (or element with the button role), by accessible name. */
+const button = named("button");
 /** A form field, by label. */
-const field = (label) => ({
-	kind: "field",
-	name: label
-});
+const field = named("field");
 /** A heading, by accessible name. */
-const heading = (name) => ({
-	kind: "heading",
-	name
-});
+const heading = named("heading");
 /** A link, by accessible name. */
-const link = (name) => ({
-	kind: "link",
-	name
-});
+const link = named("link");
 /** An element containing the given text. */
-const content = (value) => ({
-	kind: "text",
-	name: value
-});
+const content = named("text");
 /** The escape hatch: an element by `data-testid`. Prefer user-facing elements. */
 const testId = (id) => ({
 	kind: "testId",
 	name: id
 });
+const landmark = (kind) => (name, options) => ({
+	kind,
+	...name === void 0 ? {} : { name },
+	...options?.exact ? { exact: true } : {}
+});
+/** The `banner` landmark — the page header. */
+const banner = landmark("banner");
+/** The `complementary` landmark — an `<aside>`, a sidebar. */
+const complementary = landmark("complementary");
+/** The `contentinfo` landmark — the page footer. */
+const contentinfo = landmark("contentinfo");
+/** The `form` landmark — a form carrying an accessible name. */
+const form = landmark("form");
+/** The `main` landmark — the primary content of the document. */
+const main = landmark("main");
+/** The `navigation` landmark — a `<nav>`. Name it when a page has several. */
+const navigation = landmark("navigation");
+/** The `region` landmark — a `<section>` carrying an accessible name. */
+const region = landmark("region");
+/** The `search` landmark. */
+const search = landmark("search");
+/**
+* Restrict a descriptor to the inside of another — the answer to ambiguity,
+* and the one the framework prefers over a test id.
+*
+*     click(within(navigation(), link('Articles')))
+*
+* Composes outside-in: the scope may itself be scoped, so a deeply nested
+* target reads `within(main(), within(region('Series'), link('Part 2')))`.
+* Any descriptor works as a scope, including `testId()` when a container has
+* no landmark role to stand on.
+*/
+const within = (scope, target) => ({
+	...target,
+	scope: target.scope ? {
+		...target.scope,
+		scope
+	} : scope
+});
 //#endregion
 //#region src/integrations/sqlite/sqlite.ts
 var SqliteHandle = class {
@@ -4246,4 +4269,4 @@ registerComposeServiceFactory("postgres", (service) => postgres({
 }));
 registerComposeServiceFactory("redis", (service) => redis({ composeService: service.name }));
 //#endregion
-export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ResponseAccessor, TableAccessor, TextAccessor, anthropic, button, content, defineContract, field, findContainersByLabel, heading, http, inspectContainer, link, match, mockOf, mockOfDate, openai, postgres, redis, removeContainers, specification, sqlite, testId, text };
+export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ResponseAccessor, TableAccessor, TextAccessor, anthropic, banner, button, complementary, content, contentinfo, defineContract, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };

package/dist/oxlint.cjs

@@ -571,6 +571,15 @@ const RUNTIME_RULES = [
 		name: "d14-tomatch-fixture-name",
 		rationale: "L’instinct hérité de vitest (`toMatch(/re/)`) tomberait sinon sur l’erreur d’extension ou coercerait la regex en `\"/re/\"`. L’argument accesseur n’est jamais littéral côté valeur, et une heuristique statique confondrait le `expect(chaîne).toMatch(/re/)` légitime (D3/D8) — seul le canal runtime refuse proprement, sans faux positifs."
 	},
+	{
+		channel: "runtime",
+		convention: "Un descripteur d’élément doit désigner exactement UN élément : si plusieurs correspondent, l’action est refusée avec une erreur qui énumère les candidats et propose les réécritures (`within(...)`, `{ exact: true }`). Le framework n’agit jamais sur « le premier ».",
+		facet: "website",
+		family: "W",
+		id: "W3",
+		name: "w3-unambiguous-element",
+		rationale: "Agir sur le premier match rend le spec vert alors que le visiteur clique autre chose, et rien ne le signale jamais — une ambiguïté est une faute d’écriture, pas un cas à arbitrer par l’ordre du DOM. Le comptage n’existe qu’à l’exécution : aucune analyse statique ne peut le faire, d’où le canal runtime."
+	},
 	{
 		channel: "runtime",
 		convention: "`.intercept()` n’existe que sur `api`/`jobs` et lève immédiatement en mode compose (MSW est in-process).",

package/dist/oxlint.js

@@ -567,6 +567,15 @@ const RUNTIME_RULES = [
 		name: "d14-tomatch-fixture-name",
 		rationale: "L’instinct hérité de vitest (`toMatch(/re/)`) tomberait sinon sur l’erreur d’extension ou coercerait la regex en `\"/re/\"`. L’argument accesseur n’est jamais littéral côté valeur, et une heuristique statique confondrait le `expect(chaîne).toMatch(/re/)` légitime (D3/D8) — seul le canal runtime refuse proprement, sans faux positifs."
 	},
+	{
+		channel: "runtime",
+		convention: "Un descripteur d’élément doit désigner exactement UN élément : si plusieurs correspondent, l’action est refusée avec une erreur qui énumère les candidats et propose les réécritures (`within(...)`, `{ exact: true }`). Le framework n’agit jamais sur « le premier ».",
+		facet: "website",
+		family: "W",
+		id: "W3",
+		name: "w3-unambiguous-element",
+		rationale: "Agir sur le premier match rend le spec vert alors que le visiteur clique autre chose, et rien ne le signale jamais — une ambiguïté est une faute d’écriture, pas un cas à arbitrer par l’ordre du DOM. Le comptage n’existe qu’à l’exécution : aucune analyse statique ne peut le faire, d’où le canal runtime."
+	},
 	{
 		channel: "runtime",
 		convention: "`.intercept()` n’existe que sur `api`/`jobs` et lève immédiatement en mode compose (MSW est in-process).",

package/dist/playwright.adapter.js

@@ -1,32 +1,226 @@
 import { mkdtempSync } from "node:fs";
 import { resolve } from "node:path";
 import { tmpdir } from "node:os";
+//#region src/core/specification/website/ambiguity.ts
+/**
+* The ambiguity refusal — CONVENTIONS W3.
+*
+* A visit descriptor must designate exactly one element. Acting on "the
+* first match" is the failure mode this module exists to prevent: the spec
+* keeps passing while the visitor clicks something else, and nothing ever
+* reports it. So when a descriptor matches several elements the framework
+* refuses, and the refusal has to carry everything needed to fix it without
+* opening a browser — the descriptor in the caller's own vocabulary, every
+* candidate, and the concrete rewrites that would resolve it.
+*
+* Pure string building: it takes captured data and returns a message, so the
+* wording is unit-testable and the browser integration stays a thin adapter.
+*/
+/** `kind` → the constructor that builds it, so errors echo the caller's source. */
+const CONSTRUCTORS = {
+	banner: "banner",
+	button: "button",
+	complementary: "complementary",
+	contentinfo: "contentinfo",
+	field: "field",
+	form: "form",
+	heading: "heading",
+	link: "link",
+	main: "main",
+	navigation: "navigation",
+	region: "region",
+	search: "search",
+	testId: "testId",
+	text: "content"
+};
+/** The landmark a context string maps back to, for a copy-pasteable suggestion. */
+const CONTEXT_LANDMARKS = {
+	aside: "complementary()",
+	banner: "banner()",
+	complementary: "complementary()",
+	contentinfo: "contentinfo()",
+	footer: "contentinfo()",
+	form: "form()",
+	header: "banner()",
+	main: "main()",
+	nav: "navigation()",
+	navigation: "navigation()",
+	search: "search()"
+};
+/**
+* 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.
+*/
+function formatElement(element) {
+	const bare = formatBare(element);
+	return element.scope ? `within(${formatElement(element.scope)}, ${bare})` : bare;
+}
+function formatBare(element) {
+	const args = [];
+	if (element.name !== void 0) args.push(JSON.stringify(element.name));
+	if (element.exact) args.push("{ exact: true }");
+	return `${CONSTRUCTORS[element.kind]}(${args.join(", ")})`;
+}
+/** `1. <a href="/articles">Articles</a>  in <nav>` — one evidence line per candidate. */
+function formatMatch(match, index) {
+	const attribute = match.detail ? ` ${quoteDetail(match)}` : "";
+	const context = match.context ? `  in <${match.context}>` : "";
+	return `  ${index + 1}. <${match.tag}${attribute}>${match.text}</${match.tag}>${context}`;
+}
+function quoteDetail(match) {
+	return `${match.tag === "a" ? "href" : "name"}=${JSON.stringify(match.detail)}`;
+}
+/**
+* The rewrites worth offering, in the order they should be tried. Scoping is
+* always available; `exact` only when it would actually narrow the set, and
+* the count it would leave is stated so a still-ambiguous suggestion never
+* reads as a fix.
+*/
+function formatFixes(element, matches) {
+	const fixes = [];
+	const landmarks = [...new Set(matches.map((match) => match.context && CONTEXT_LANDMARKS[match.context]).filter((landmark) => Boolean(landmark)))];
+	if (landmarks.length > 0 && !element.scope) fixes.push(`scope it       within(${landmarks[0]}, ${formatBare(element)})${landmarks.length > 1 ? `   [also here: ${landmarks.slice(1).join(", ")}]` : ""}`);
+	else if (!element.scope) fixes.push(`scope it       within(main(), ${formatBare(element)})`);
+	if (!element.exact && 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,
+			exact: true
+		})}   [leaves ${remaining} of ${matches.length}]`);
+	}
+	fixes.push("other element  a heading(), button() or field() may name one thing where this does not");
+	return fixes;
+}
+/**
+* The W3 refusal. A distinct class so the visit wrapper can recognize an
+* already-complete message and let it through instead of nesting it inside
+* `visit scenario failed: …`, which would print the whole thing twice.
+*/
+var AmbiguousElementError = class extends Error {
+	name = "AmbiguousElementError";
+};
+/**
+* Build the refusal thrown when a descriptor matches more than one element.
+*
+* @param options.element The descriptor as the caller wrote it.
+* @param options.matches Every candidate, in DOM order (already truncated).
+* @param options.url The page the visitor was on when it happened.
+*/
+function describeAmbiguity(options) {
+	const { element, matches, url } = options;
+	const fixes = formatFixes(element, matches).map((fix) => `  • ${fix}`);
+	return [
+		`Ambiguous element: ${formatElement(element)} matched ${matches.length} elements on ${url}.`,
+		"",
+		"A spec must designate exactly one element. Acting on the first match would let",
+		"this test keep passing while the visitor interacts with something else.",
+		"",
+		"Matched:",
+		...matches.map((match, index) => formatMatch(match, index)),
+		"",
+		"Disambiguate with one of:",
+		...fixes,
+		"",
+		"Docs: docs/11-website.md#designating-exactly-one-element (CONVENTIONS W3)"
+	].join("\n");
+}
+//#endregion
 //#region src/integrations/playwright/playwright.adapter.ts
-/** Translate a user-facing element descriptor into a playwright locator. */
-function locate(page, element) {
+/** How many candidates the ambiguity error enumerates before truncating. */
+const MAX_REPORTED_MATCHES = 10;
+/**
+* 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
+* behind CONVENTIONS W3, and swallowing it would reintroduce the silent
+* wrong-element bug the rule exists to prevent.
+*/
+function locate(root, element) {
+	const scope = element.scope ? locate(root, element.scope) : root;
+	const options = {
+		exact: element.exact,
+		name: element.name
+	};
 	switch (element.kind) {
-		case "button": return page.getByRole("button", { name: element.name });
-		case "field": return page.getByLabel(element.name);
-		case "heading": return page.getByRole("heading", { name: element.name });
-		case "link": return page.getByRole("link", { name: element.name });
-		case "testId": return page.getByTestId(element.name);
-		case "text": return page.getByText(element.name);
+		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 });
+		case "testId": return scope.getByTestId(element.name ?? "");
+		case "text": return scope.getByText(element.name ?? "", { exact: element.exact });
 	}
 }
+/** Playwright signals "more than one match" through this error text. */
+function isStrictViolation(error) {
+	return error instanceof Error && error.message.includes("strict mode violation");
+}
+/** Capture the candidates in-page — the evidence the refusal enumerates. */
+async function captureMatches(locator) {
+	return locator.evaluateAll((nodes, limit) => {
+		const LANDMARKS = "nav, header, footer, main, aside, section, form, [role]";
+		return nodes.slice(0, limit).map((node) => {
+			const element = node;
+			const landmark = element.parentElement?.closest(LANDMARKS);
+			const context = landmark ? landmark.getAttribute("role") ?? landmark.tagName.toLowerCase() : null;
+			const detail = element.getAttribute("href") ?? element.getAttribute("name");
+			return {
+				context: context ?? void 0,
+				detail: detail ?? void 0,
+				tag: element.tagName.toLowerCase(),
+				text: (element.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 80)
+			};
+		});
+	}, MAX_REPORTED_MATCHES);
+}
+/**
+* Run one visitor action, converting a strict-mode violation into the W3
+* refusal. The ambiguous level is identified before reporting: a scope that
+* matches several landmarks is the real fault, and naming the target instead
+* would send the author to fix the wrong descriptor.
+*/
+async function act(page, element, action) {
+	try {
+		return await action(locate(page, element));
+	} catch (error) {
+		if (!isStrictViolation(error)) throw error;
+		const culprit = await findAmbiguousLevel(page, element);
+		throw new AmbiguousElementError(describeAmbiguity({
+			element: culprit,
+			matches: await captureMatches(locate(page, culprit)),
+			url: page.url()
+		}));
+	}
+}
+/** Walk the scope chain outside-in; the outermost ambiguous level is the fault. */
+async function findAmbiguousLevel(page, element) {
+	const chain = [];
+	for (let current = element; current; current = current.scope) chain.unshift(current);
+	for (const level of chain.slice(0, -1)) if (await locate(page, level).count() > 1) return level;
+	return element;
+}
 /** The visitor implementation — every action auto-waits via playwright actionability. */
 function createVisitor(page, baseUrl) {
 	return {
-		check: (element) => locate(page, element).first().check(),
-		click: (element) => locate(page, element).first().click(),
-		fill: (element, value) => locate(page, element).first().fill(value),
+		check: (element) => act(page, element, (locator) => locator.check()),
+		click: (element) => act(page, element, (locator) => locator.click()),
+		fill: (element, value) => act(page, element, (locator) => locator.fill(value)),
 		goto: async (path) => {
 			await page.goto(`${baseUrl}${path}`, { waitUntil: "load" });
 		},
-		hover: (element) => locate(page, element).first().hover(),
+		hover: (element) => act(page, element, (locator) => locator.hover()),
 		press: (key) => page.keyboard.press(key),
-		see: (element) => locate(page, element).first().waitFor({ state: "visible" }),
+		see: (element) => act(page, element, (locator) => locator.waitFor({ state: "visible" })),
 		select: async (element, option) => {
-			await locate(page, element).first().selectOption(option);
+			await act(page, element, (locator) => locator.selectOption(option));
 		}
 	};
 }
@@ -71,7 +265,12 @@ var PlaywrightAdapter = class {
 				await options.scenario(createVisitor(page, options.baseUrl));
 			} catch (error) {
 				const evidence = await this.captureEvidence(page);
-				throw new Error(`visit scenario failed: ${error instanceof Error ? error.message : String(error)}${evidence ? `\nEvidence: ${evidence}` : ""}`, { cause: error });
+				const suffix = evidence ? `\nEvidence: ${evidence}` : "";
+				if (error instanceof AmbiguousElementError) {
+					error.message += suffix;
+					throw error;
+				}
+				throw new Error(`visit scenario failed: ${error instanceof Error ? error.message : String(error)}${suffix}`, { cause: error });
 			}
 			const extraction = await page.evaluate(() => {
 				const links = [...document.querySelectorAll("link")].map((link) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "9.2.1",
+    "version": "10.0.0",
     "description": "Declarative testing framework for HTTP APIs, CLIs, and background jobs — one entry point, real infrastructure, golden-file assertions, plus an oxlint convention plugin.",
     "keywords": [
         "api-testing",
@@ -49,8 +49,7 @@
         "docs": "npm run build && node dist/catalog.js && typescript docs",
         "lint": "typescript check && node dist/checker.js specs",
         "lint:fix": "typescript fix",
-        "test": "vitest --run",
-        "pretest": "playwright install chromium"
+        "test": "vitest --run"
     },
     "dependencies": {
         "better-sqlite3": "^12.11.1",