@jterrazz/test 9.2.1 → 10.1.0

package/dist/index.js

@@ -2,12 +2,14 @@ import { i as match, n as Matcher, r as TOKEN_KINDS, t as CaptureScope } from ".
 import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { parse } from "yaml";
-import { execSync, spawn, spawnSync } from "node:child_process";
+import { execFile, execSync, spawn, spawnSync } from "node:child_process";
 import { Client } from "pg";
 import { readdir } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
-import { createServer } from "node:net";
+import { createServer } from "node:http";
+import { createServer as createServer$1 } from "node:net";
+import { promisify } from "node:util";
 import Database from "better-sqlite3";
 import { mockDeep } from "vitest-mock-extended";
 import MockDatePackage from "mockdate";
@@ -642,15 +644,15 @@ function escapeRegExp(text) {
 function parsePlaceholderString(expected, scope) {
 	PLACEHOLDER_RE.lastIndex = 0;
 	const refs = [];
-	let pattern = "^";
+	let source = "";
 	let lastIndex = 0;
 	let single = null;
 	let count = 0;
 	for (const found of expected.matchAll(PLACEHOLDER_RE)) {
 		const kind = found.groups.kind;
 		const ref = found.groups.ref;
-		pattern += escapeRegExp(expected.slice(lastIndex, found.index));
-		pattern += `(${placeholderSource(kind, scope)})`;
+		source += escapeRegExp(expected.slice(lastIndex, found.index));
+		source += `(${placeholderSource(kind, scope)})`;
 		refs.push({
 			index: count,
 			kind,
@@ -663,13 +665,22 @@ function parsePlaceholderString(expected, scope) {
 			ref
 		};
 	}
-	pattern += `${escapeRegExp(expected.slice(lastIndex))}$`;
+	source += escapeRegExp(expected.slice(lastIndex));
 	return {
-		pattern: new RegExp(pattern),
+		pattern: new RegExp(`^${source}$`),
 		refs,
-		single
+		single,
+		source
 	};
 }
+/**
+* Unanchored regex source matching a fixture string — plain text escaped
+* verbatim, each `{{token}}` expanded to its embedded grammar. Used to route
+* declared `.http` intercept paths (`/articles/{{uuid}}`) as URL patterns.
+*/
+function placeholderPatternSource(expected) {
+	return parsePlaceholderString(expected, new CaptureScope()).source;
+}
 function placeholderStringMatches(expected, actual, scope) {
 	const parsed = parsePlaceholderString(expected, scope);
 	if (parsed.single) {
@@ -1979,6 +1990,128 @@ async function registerMatchers() {
 	}
 }
 //#endregion
+//#region src/core/http-files/intercept-file.ts
+/** Split a declared path into its pathname and query halves — never through
+* `new URL()`, which would percent-encode `{{token}}` braces away. */
+function splitPath(path) {
+	const separator = path.indexOf("?");
+	if (separator === -1) return {
+		pathname: path,
+		query: new URLSearchParams()
+	};
+	return {
+		pathname: path.slice(0, separator),
+		query: new URLSearchParams(path.slice(separator + 1))
+	};
+}
+/**
+* Parse an `intercepts/*.http` file into its declared exchanges. Malformed
+* files refuse with the exchange number and the expected shape.
+*/
+function parseInterceptFile(content, fileName) {
+	const segments = content.split(/^###.*$/m).map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+	if (segments.length === 0) throw new Error(`${fileName}: no exchanges found — expected "###"-separated request/response pairs`);
+	return segments.map((segment, index) => {
+		const ordinal = index + 1;
+		const lines = segment.split(/\r?\n/);
+		const statusIndex = lines.findIndex((line) => /^HTTP\/1\.1\s/.test(line.trim()));
+		if (statusIndex === -1) throw new Error(`${fileName}: exchange ${ordinal} has no response block — expected an "HTTP/1.1 <status>" line after the request`);
+		const request = parseRequestFile(lines.slice(0, statusIndex).join("\n"), fileName);
+		if (request.body !== void 0) throw new Error(`${fileName}: exchange ${ordinal} declares a request body — matching is method + path + headers only`);
+		const response = parseResponseFile(lines.slice(statusIndex).join("\n"), fileName);
+		const status = Number(response.status);
+		if (!Number.isInteger(status)) throw new Error(`${fileName}: exchange ${ordinal} has a non-numeric status "${response.status}" — an intercept file states the stubbed reply, not an expectation`);
+		return {
+			request: {
+				headers: request.headers,
+				method: request.method,
+				path: request.path
+			},
+			response: {
+				body: response.body,
+				hasBody: response.hasBody,
+				headers: response.headers,
+				status
+			}
+		};
+	});
+}
+/** Token-aware comparison of one declared value against an observed one. */
+function valueMatches(declared, observed) {
+	return textEquals(declared, observed, new CaptureScope());
+}
+/**
+* Does an observed request satisfy a declared exchange request? Method exact,
+* pathname exact (`{{token}}` segments match structurally), declared query
+* params and headers subset-match — extras on the observed side are ignored.
+*/
+function exchangeMatches(declared, observed) {
+	if (declared.method !== observed.method.toUpperCase()) return false;
+	const { pathname, query } = splitPath(declared.path);
+	let observedUrl;
+	try {
+		observedUrl = new URL(observed.url, "http://stub.invalid");
+	} catch {
+		return false;
+	}
+	if (!valueMatches(pathname, observedUrl.pathname) && !valueMatches(pathname, safeDecode(observedUrl.pathname))) return false;
+	for (const key of new Set(query.keys())) {
+		const observedValues = observedUrl.searchParams.getAll(key);
+		if (!query.getAll(key).every((value) => observedValues.some((actual) => valueMatches(value, actual)))) return false;
+	}
+	return Object.entries(declared.headers).every(([name, value]) => {
+		const actual = observed.headers[name.toLowerCase()];
+		return actual !== void 0 && valueMatches(value, actual);
+	});
+}
+/** Decode percent-escapes, falling back to the raw text on malformed input. */
+function safeDecode(text) {
+	try {
+		return decodeURIComponent(text);
+	} catch {
+		return text;
+	}
+}
+/**
+* A URL pattern routing any-origin requests whose pathname is the declared
+* one — `{{token}}` segments expanded to their grammars. Deliberately no
+* wider than {@link exchangeMatches}: the predicate stays the authority.
+*/
+function urlPatternOf(path) {
+	const { pathname } = splitPath(path);
+	return new RegExp(String.raw`^https?:\/\/[^/?#]+${placeholderPatternSource(pathname)}(?:\?[^#]*)?(?:#.*)?$`);
+}
+/**
+* Convert parsed exchanges into generic-http intercept entries for the MSW
+* engine — each exchange becomes one FIFO-consumed contract (CONVENTIONS D7
+* strictness applies unchanged on api/jobs chains).
+*/
+function interceptEntriesOf(exchanges) {
+	return exchanges.map((exchange) => {
+		return {
+			response: {
+				body: exchange.response.hasBody ? exchange.response.body : null,
+				headers: Object.keys(exchange.response.headers).length > 0 ? exchange.response.headers : void 0,
+				status: exchange.response.status
+			},
+			trigger: {
+				adapter: "http",
+				match: (request) => exchangeMatches(exchange.request, {
+					headers: request.headers,
+					method: exchange.request.method,
+					url: request.url
+				}),
+				method: exchange.request.method,
+				url: urlPatternOf(exchange.request.path),
+				wrap: (data) => ({
+					body: data,
+					status: 200
+				})
+			}
+		};
+	});
+}
+//#endregion
 //#region src/core/specification/api/result.ts
 /** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
 var HttpResult = class extends BaseResult {
@@ -1997,6 +2130,30 @@ var HttpResult = class extends BaseResult {
 	}
 };
 //#endregion
+//#region src/core/specification/mobile/result.ts
+/** Result from a `.open()` action — the screen as the device saw it, final state. */
+var ScreenResult = class extends BaseResult {
+	capturedScreen;
+	constructor(options) {
+		super(options);
+		this.capturedScreen = options.screen;
+	}
+	/**
+	* The visible screen texts as one stream, in reading order — the scalpel
+	* for a targeted probe: `expect(result.content).toContain('Bookmarked')`.
+	*/
+	get content() {
+		return new TextAccessor(this.capturedScreen.texts.join("\n"), "content", this.testDir, { captures: this.captures });
+	}
+	/**
+	* The projected accessibility tree as a JSON accessor — the one golden
+	* per screen: `expect(result.screen).toMatch('events.screen.json')`.
+	*/
+	get screen() {
+		return new JsonAccessor(JSON.stringify(this.capturedScreen.tree), this.testDir, void 0, this.captures);
+	}
+};
+//#endregion
 //#region src/core/specification/website/result.ts
 /** Result from a raw `.fetch()` action (robots.txt, sitemaps, redirects). */
 var FetchResult = class extends BaseResult {
@@ -2253,6 +2410,7 @@ function copyPlan(path, testDir, workDir) {
 * only surfaces the methods that make sense for it.
 */
 var SpecificationBuilder = class {
+	backendExchanges = [];
 	commandEnv = {};
 	config;
 	fixtures = [];
@@ -2332,6 +2490,7 @@ var SpecificationBuilder = class {
 	}
 	intercept(triggerOrContracts, maybeResponse) {
 		if (this.config.interceptDisabledReason) throw new Error(`.intercept(): ${this.config.interceptDisabledReason}`);
+		if (typeof triggerOrContracts === "string") return this.interceptFile(triggerOrContracts);
 		if (Array.isArray(triggerOrContracts)) {
 			for (const contract of triggerOrContracts) this.registerIntercept(contract);
 			return this;
@@ -2362,6 +2521,27 @@ var SpecificationBuilder = class {
 		});
 	}
 	/**
+	* Register the exchanges of an `intercepts/<name>.http` file — flat in
+	* the calling test's `intercepts/` directory, the same resolution
+	* `.seed()` / `.request()` use. Website/mobile chains feed the declared
+	* stub backend; api/jobs chains feed the MSW engine (same contract list).
+	*/
+	interceptFile(file) {
+		if (!file.endsWith(".http")) throw new Error(`.intercept(): a single string argument must name an intercepts/*.http file (e.g. 'two-events.http'), got '${file}'`);
+		const stubFacet = this.config.baseUrl !== void 0 || this.config.device !== void 0;
+		if (stubFacet && !this.config.backend) {
+			const facet = this.config.device === void 0 ? "website" : "mobile";
+			throw new Error(`.intercept(): this runner has no declared backend — add \`backend\` to the specification options (specification.${facet}({ …, backend: { … } })) so the chain's .http intercepts have a stub to serve them.`);
+		}
+		const exchanges = parseInterceptFile(readFileSync(resolve(this.testDir, "intercepts", file), "utf8"), `intercepts/${file}`);
+		if (stubFacet) {
+			this.backendExchanges.push(...exchanges);
+			return this;
+		}
+		this.intercepts.push(...interceptEntriesOf(exchanges));
+		return this;
+	}
+	/**
 	* Send the complete request described by `requests/<file>` — first line
 	* `METHOD /path`, then headers until a blank line, then the body.
 	* Headers set via `.headers()` merge on top of the file's headers.
@@ -2479,6 +2659,24 @@ var SpecificationBuilder = class {
 		return this.executeSetup(null, () => this.runVisitAction(path, scenario));
 	}
 	/**
+	* Terminate and relaunch the app on the simulator, apply the deep link,
+	* run the scenario, and resolve with the captured final screen — the
+	* projected accessibility tree and the visible texts. One driver session
+	* per runner; every open starts from a deterministic fresh app state.
+	*
+	* @example
+	*   const result = await mobile.open('news://events');
+	*   expect(result.screen).toMatch('events.screen.json');
+	*
+	*   const result = await mobile.open('news://events', async (visitor) => {
+	*       await visitor.tap(button('Enquête Fauci COVID-19'));
+	*       await visitor.see(content('rapports'));
+	*   });
+	*/
+	open(deepLink, scenario) {
+		return this.executeSetup(null, () => this.runOpenAction(deepLink, scenario));
+	}
+	/**
 	* Execute the named job registered via the `jobs` option of
 	* `specification.jobs()` and resolve with the result.
 	*
@@ -2521,13 +2719,14 @@ var SpecificationBuilder = class {
 			const { registerIntercepts } = await import("./intercept.js");
 			registration = await registerIntercepts(this.intercepts);
 		}
+		this.config.backend?.beginChain(this.backendExchanges);
 		try {
 			const value = await action();
-			const violation = registration?.violation();
+			const violation = registration?.violation() ?? this.config.backend?.violation();
 			if (violation) throw violation;
 			return value;
 		} catch (error) {
-			throw registration?.violation() ?? error;
+			throw registration?.violation() ?? this.config.backend?.violation() ?? error;
 		} finally {
 			registration?.cleanup();
 		}
@@ -2595,6 +2794,7 @@ var SpecificationBuilder = class {
 		const browser = await this.config.browser();
 		const headers = Object.keys(this.requestHeaders).length > 0 ? this.requestHeaders : void 0;
 		const page = await browser.open(`${baseUrl}${path}`, {
+			allowedOrigins: this.config.backendUrl ? [new URL(this.config.backendUrl).origin] : void 0,
 			baseUrl,
 			external: this.config.external ?? "allow",
 			headers,
@@ -2606,6 +2806,19 @@ var SpecificationBuilder = class {
 			testDir: this.testDir
 		});
 	}
+	async runOpenAction(deepLink, scenario) {
+		if (!this.config.device || this.config.bundleId === void 0) throw new Error(".open() requires a device adapter (use specification.mobile())");
+		const screen = await (await this.config.device()).open({
+			bundleId: this.config.bundleId,
+			deepLink,
+			scenario
+		});
+		return new ScreenResult({
+			config: this.config,
+			screen,
+			testDir: this.testDir
+		});
+	}
 	requireBaseUrl(method) {
 		if (!this.config.baseUrl) throw new Error(`.${method}() requires a website under test (use specification.website())`);
 		return this.config.baseUrl;
@@ -2699,7 +2912,7 @@ function createApiFacet(config) {
 		delete: (path) => start().delete(path),
 		get: (path) => start().get(path),
 		headers: (headers) => start().headers(headers),
-		intercept: (triggerOrContracts, response) => Array.isArray(triggerOrContracts) ? start().intercept(triggerOrContracts) : start().intercept(triggerOrContracts, response),
+		intercept: (triggerOrContracts, response) => Array.isArray(triggerOrContracts) || typeof triggerOrContracts === "string" ? start().intercept(triggerOrContracts) : start().intercept(triggerOrContracts, response),
 		post: (path, body) => start().post(path, body),
 		put: (path, body) => start().put(path, body),
 		request: (file) => start().request(file),
@@ -2712,7 +2925,7 @@ function createApiFacet(config) {
 function createJobsFacet(config) {
 	const start = () => new SpecificationBuilder(config, getCallerDir());
 	return {
-		intercept: (triggerOrContracts, response) => Array.isArray(triggerOrContracts) ? start().intercept(triggerOrContracts) : start().intercept(triggerOrContracts, response),
+		intercept: (triggerOrContracts, response) => Array.isArray(triggerOrContracts) || typeof triggerOrContracts === "string" ? start().intercept(triggerOrContracts) : start().intercept(triggerOrContracts, response),
 		seed: (file, options) => start().seed(file, options),
 		trigger: (name) => start().trigger(name)
 	};
@@ -2725,10 +2938,21 @@ function createWebsiteFacet(config) {
 	return {
 		fetch: (path) => start().fetch(path),
 		headers: (headers) => start().headers(headers),
+		intercept: (file) => start().intercept(file),
 		visit: (path, scenario) => start().visit(path, scenario)
 	};
 }
 /**
+* Create the `mobile` facet bound to the given adapter configuration.
+*/
+function createMobileFacet(config) {
+	const start = () => new SpecificationBuilder(config, getCallerDir());
+	return {
+		intercept: (file) => start().intercept(file),
+		open: (deepLink, scenario) => start().open(deepLink, scenario)
+	};
+}
+/**
 * Create the `cli` facet bound to the given adapter configuration.
 */
 function createCliFacet(config) {
@@ -3423,6 +3647,179 @@ async function startJobs(options) {
 	};
 }
 //#endregion
+//#region src/core/specification/shared/stub-backend.ts
+/**
+* The declared stub backend — a small `node:http` server the website and
+* mobile runners start when their `backend` option is present. It serves the
+* exchanges the CURRENT chain declared via `.intercept('<name>.http')`:
+* one chain = one terminal action, and the stub resets between chains the
+* way databases do.
+*
+* Matching is the `intercepts/*.http` grammar (`exchangeMatches`), with the
+* queue semantics a rendered app needs: same-route entries consume FIFO, and
+* once a route's queue is exhausted its LAST entry stays sticky — a page
+* re-fetching the same endpoint (re-render, retry) replays the final reply
+* instead of failing an honest screen.
+*
+* Strictness is the `external: 'block'` analog (CONVENTIONS D7 in spirit): a
+* request matching no declared exchange is answered 501 and RECORDED; once
+* the chain declared at least one intercept, the terminal action throws an
+* error enumerating every unmatched request. Chains with zero intercepts
+* leave the stub unguarded — mirroring how MSW stays off without them.
+*
+* Every response (including the 501 and the OPTIONS preflight) carries
+* permissive CORS headers — a website's client-side fetches are cross-origin
+* to the stub by construction.
+*/
+const CORS_METHODS = "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS";
+const PREFLIGHT_MAX_AGE = "600";
+var StubBackend = class {
+	consumed = [];
+	entries = [];
+	/** Guarded once the current chain declared at least one intercept. */
+	guarded = false;
+	options;
+	server = null;
+	unmatchedRequests = /* @__PURE__ */ new Map();
+	url = "";
+	constructor(options = {}) {
+		this.options = options;
+	}
+	/** Start the server and resolve with its base URL. */
+	async start() {
+		const server = createServer((request, response) => {
+			this.handle(request, response);
+		});
+		this.server = server;
+		await new Promise((resolve, reject) => {
+			server.once("error", reject);
+			server.listen(this.options.port ?? 0, "127.0.0.1", () => resolve());
+		});
+		const address = server.address();
+		if (address === null || typeof address === "string") throw new Error("stub backend: could not determine the listening port");
+		this.url = `http://127.0.0.1:${address.port}`;
+		return this.url;
+	}
+	/** Stop the server (idempotent). */
+	async stop() {
+		const server = this.server;
+		if (!server) return;
+		this.server = null;
+		server.closeAllConnections();
+		await new Promise((resolve) => {
+			server.close(() => resolve());
+		});
+	}
+	/**
+	* Arm the stub for one chain: the declared exchanges replace the previous
+	* chain's wholesale, consumption restarts, and the unmatched log clears —
+	* the reset-between-chains databases already follow.
+	*/
+	beginChain(exchanges) {
+		this.consumed = exchanges.map(() => false);
+		this.entries = exchanges;
+		this.guarded = exchanges.length > 0;
+		this.unmatchedRequests.clear();
+	}
+	/**
+	* The strict failure for the chain, or null — non-null when the chain
+	* declared at least one intercept AND an unmatched request was recorded.
+	* Enumerates every unmatched request (method, path, count) plus the
+	* declared routes, so the missing exchange writes itself.
+	*/
+	violation() {
+		if (!this.guarded || this.unmatchedRequests.size === 0) return null;
+		const unmatched = [...this.unmatchedRequests.values()].map((entry) => `  - ${entry.method} ${entry.path}${entry.count > 1 ? ` (${entry.count} times)` : ""}`).join("\n");
+		return /* @__PURE__ */ new Error(`Unmatched request(s) hit the declared backend during the chain:\n${unmatched}\nDeclared exchanges:\n${this.describeRoutes()}\nEvery backend request of a chain that declares intercepts must match one — add an exchange for it to the chain's intercepts/*.http file.`);
+	}
+	corsHeaders(request) {
+		return {
+			"access-control-allow-headers": request.headers["access-control-request-headers"] ?? "*",
+			"access-control-allow-methods": CORS_METHODS,
+			"access-control-allow-origin": "*",
+			"access-control-max-age": PREFLIGHT_MAX_AGE
+		};
+	}
+	describeRoutes() {
+		if (this.entries.length === 0) return "  (no exchanges declared)";
+		return this.entries.map((entry, i) => `  - ${entry.request.method} ${entry.request.path}${this.consumed[i] ? " (consumed)" : ""}`).join("\n");
+	}
+	handle(request, response) {
+		const method = (request.method ?? "GET").toUpperCase();
+		const cors = this.corsHeaders(request);
+		if (method === "OPTIONS") {
+			response.writeHead(204, cors);
+			response.end();
+			return;
+		}
+		const headers = {};
+		for (const [name, value] of Object.entries(request.headers)) if (typeof value === "string") headers[name.toLowerCase()] = value;
+		const url = request.url ?? "/";
+		const entry = this.take({
+			headers,
+			method,
+			url
+		});
+		if (!entry) {
+			this.record(method, url);
+			response.writeHead(501, {
+				...cors,
+				"content-type": "application/json"
+			});
+			response.end(JSON.stringify({
+				declared: this.entries.map((declared) => `${declared.request.method} ${declared.request.path}`),
+				error: `@jterrazz/test declared backend: no exchange matches ${method} ${url}`
+			}));
+			return;
+		}
+		const { body, hasBody, status } = entry.response;
+		if (!hasBody) {
+			response.writeHead(status, {
+				...cors,
+				...entry.response.headers
+			});
+			response.end();
+			return;
+		}
+		const payload = typeof body === "string" ? body : JSON.stringify(body);
+		const contentType = typeof body === "string" ? "text/plain; charset=utf-8" : "application/json";
+		response.writeHead(status, {
+			...cors,
+			"content-type": contentType,
+			...entry.response.headers
+		});
+		response.end(payload);
+	}
+	record(method, path) {
+		const key = `${method} ${path}`;
+		const existing = this.unmatchedRequests.get(key);
+		if (existing) existing.count += 1;
+		else this.unmatchedRequests.set(key, {
+			count: 1,
+			method,
+			path
+		});
+	}
+	/**
+	* FIFO with a sticky tail: the first unconsumed matching exchange is
+	* consumed; when every matching exchange is spent, the LAST one keeps
+	* replying.
+	*/
+	take(observed) {
+		let sticky = null;
+		for (let i = 0; i < this.entries.length; i++) {
+			const entry = this.entries[i];
+			if (!exchangeMatches(entry.request, observed)) continue;
+			if (!this.consumed[i]) {
+				this.consumed[i] = true;
+				return entry;
+			}
+			sticky = entry;
+		}
+		return sticky;
+	}
+};
+//#endregion
 //#region src/core/specification/website/serve.adapter.ts
 /** Grace period between SIGTERM and the SIGKILL escalation. */
 const KILL_GRACE_MS = 2e3;
@@ -3432,7 +3829,7 @@ const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Ask the OS for a free TCP port. */
 function findFreePort() {
 	return new Promise((resolve, reject) => {
-		const server = createServer();
+		const server = createServer$1();
 		server.listen(0, () => {
 			const address = server.address();
 			if (address === null || typeof address === "string") {
@@ -3458,10 +3855,16 @@ function findFreePort() {
 */
 var ServeAdapter = class {
 	child = null;
+	/** Extra environment injected into the child (e.g. the stub backend URL). */
+	extraEnv;
+	/** The constructor named in error messages — `website`, or `mobile` (appium server). */
+	facet;
 	options;
 	output = "";
 	root;
-	constructor(options, root) {
+	constructor(options, root, facet = "website", extraEnv = {}) {
+		this.extraEnv = extraEnv;
+		this.facet = facet;
 		this.options = options;
 		this.root = root;
 	}
@@ -3476,6 +3879,7 @@ var ServeAdapter = class {
 			detached: process.platform !== "win32",
 			env: {
 				...process.env,
+				...this.extraEnv,
 				PORT: String(port)
 			},
 			shell: true,
@@ -3497,14 +3901,14 @@ var ServeAdapter = class {
 		});
 		const deadline = Date.now() + timeout;
 		for (;;) {
-			if (exited) throw new Error(`specification.website(): server command exited before answering HTTP.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
+			if (exited) throw new Error(`specification.${this.facet}(): server command exited before answering HTTP.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
 			try {
 				await fetch(readyUrl, { redirect: "manual" });
 				return baseUrl;
 			} catch {
 				if (Date.now() >= deadline) {
 					await this.stop();
-					throw new Error(`specification.website(): server did not answer on ${readyUrl} within ${timeout}ms.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
+					throw new Error(`specification.${this.facet}(): server did not answer on ${readyUrl} within ${timeout}ms.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
 				}
 				await delay(READY_POLL_INTERVAL_MS);
 			}
@@ -3544,16 +3948,184 @@ var ServeAdapter = class {
 	}
 };
 //#endregion
+//#region src/core/specification/mobile/appium-server.ts
+const APPIUM_READY_TIMEOUT_MS = 6e4;
+/**
+* The guidance thrown when the optional peers are missing — the exact fix,
+* mirroring the playwright message on `.visit()`.
+*/
+const APPIUM_INSTALL_HINT = "specification.mobile() requires appium and webdriverio (optional peer dependencies): npm install -D appium webdriverio && npx appium driver install xcuitest";
+/**
+* Start the caller project's appium server as a child process on a free port
+* and wait until `/status` answers. The binary is resolved from the project
+* root's `node_modules/.bin` — appium is an optional peer, so its absence
+* refuses with the exact install command. Process lifecycle (free port via
+* `PORT`, readiness poll, SIGTERM→SIGKILL group escalation on stop) is the
+* serve adapter's — one implementation for every child the framework spawns.
+*/
+async function startAppiumServer(root) {
+	const bin = resolve(root, "node_modules", ".bin", "appium");
+	if (!existsSync(bin)) throw new Error(APPIUM_INSTALL_HINT);
+	const serve = new ServeAdapter({
+		command: `"${bin}" --port "$PORT"`,
+		ready: "/status",
+		timeout: APPIUM_READY_TIMEOUT_MS
+	}, root, "mobile");
+	return {
+		stop: () => serve.stop(),
+		url: await serve.start()
+	};
+}
+//#endregion
+//#region src/core/specification/mobile/simulator.ts
+/**
+* Simulator resolution — `device: { name, os? }` → one booted UDID.
+*
+* The selection logic is pure (`simctl list` JSON in, one device out) so the
+* refusals are unit-testable; only the thin wrappers below shell out to
+* `xcrun`. Zero matches and several matches both refuse with the full device
+* listing — the framework never guesses which simulator a spec meant.
+*/
+const run = promisify(execFile);
+const BOOT_TIMEOUT_MS = 12e4;
+/** `com.apple.CoreSimulator.SimRuntime.iOS-26-5` → `iOS 26.5`. */
+function runtimeLabel(runtime) {
+	const match = /SimRuntime\.(?<platform>[A-Za-z]+)-(?<version>[\d-]+)$/.exec(runtime);
+	return match?.groups ? `${match.groups["platform"]} ${match.groups["version"].replaceAll("-", ".")}` : runtime;
+}
+/** Flatten the per-runtime record into one available-device list. */
+function listSimulators(listJson) {
+	const parsed = JSON.parse(listJson);
+	return Object.entries(parsed.devices).flatMap(([runtime, devices]) => devices.filter((device) => device.isAvailable !== false).map((device) => ({
+		name: device.name,
+		os: runtimeLabel(runtime),
+		state: device.state,
+		udid: device.udid
+	})));
+}
+/** `iOS 26.5` matches `os: 'iOS 26.5'` and the bare version `'26.5'`, case-insensitive. */
+function osMatches(deviceOs, wanted) {
+	const normalized = wanted.toLowerCase();
+	return deviceOs.toLowerCase() === normalized || deviceOs.split(" ")[1] === wanted;
+}
+function formatListing(devices) {
+	return devices.map((device) => `  ${device.name} — ${device.os} (${device.state}) ${device.udid}`).join("\n");
+}
+/**
+* Pick exactly one simulator by name (and OS when given). Zero or several
+* matches refuse with the listing needed to fix the options without opening
+* Xcode.
+*/
+function selectSimulator(listJson, criteria) {
+	const available = listSimulators(listJson);
+	const matches = available.filter((device) => device.name === criteria.name && (criteria.os === void 0 || osMatches(device.os, criteria.os)));
+	const wanted = criteria.os === void 0 ? `"${criteria.name}"` : `"${criteria.name}" on ${criteria.os}`;
+	if (matches.length === 0) throw new Error(`specification.mobile(): no simulator matches ${wanted}.\nAvailable devices:\n${formatListing(available)}`);
+	if (matches.length > 1) throw new Error(`specification.mobile(): ${matches.length} simulators match ${wanted} — add \`os:\` or \`udid:\` to pick one.\nMatched:\n${formatListing(matches)}`);
+	return matches[0];
+}
+/** Resolve `device: { name, os? }` to a UDID via `xcrun simctl`. */
+async function resolveSimulatorUdid(criteria) {
+	const { stdout } = await run("xcrun", [
+		"simctl",
+		"list",
+		"devices",
+		"--json"
+	], { maxBuffer: 16 * 1024 * 1024 });
+	return selectSimulator(stdout, criteria).udid;
+}
+/**
+* Boot the simulator when it is shut down and wait until it reports Booted.
+* Idempotent: booting an already-booted device is tolerated, and
+* `bootstatus -b` returns immediately when the device is up.
+*/
+async function ensureBooted(udid) {
+	try {
+		await run("xcrun", [
+			"simctl",
+			"boot",
+			udid
+		]);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (!message.includes("current state: Booted")) throw new Error(`specification.mobile(): could not boot simulator ${udid}.\n${message}`, { cause: error });
+	}
+	await run("xcrun", [
+		"simctl",
+		"bootstatus",
+		udid,
+		"-b"
+	], { timeout: BOOT_TIMEOUT_MS });
+}
+//#endregion
+//#region src/core/specification/mobile/start-mobile.ts
+async function startMobile(options) {
+	const callerDir = getCallerDir();
+	await registerMatchers();
+	const root = resolveRoot(options.root, callerDir);
+	const udid = options.device.udid ?? await resolveSimulatorUdid(options.device);
+	await ensureBooted(udid);
+	const appium = await startAppiumServer(root);
+	let backend = null;
+	let backendUrl;
+	if (options.backend) {
+		backend = new StubBackend({ port: options.backend.port });
+		backendUrl = await backend.start();
+	}
+	let device = null;
+	const getDevice = async () => {
+		if (!device) {
+			const { AppiumAdapter } = await import("./appium.adapter.js");
+			device = new AppiumAdapter({
+				serverUrl: appium.url,
+				udid
+			});
+		}
+		return device;
+	};
+	const config = {
+		backend: backend ?? void 0,
+		backendUrl,
+		bundleId: options.app.bundleId,
+		device: getDevice
+	};
+	return {
+		backendUrl,
+		cleanup: async () => {
+			if (device) {
+				await device.close();
+				device = null;
+			}
+			await appium.stop();
+			if (backend) await backend.stop();
+		},
+		mobile: createMobileFacet(config),
+		udid
+	};
+}
+//#endregion
 //#region src/core/specification/website/start-website.ts
 async function startWebsite(options) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
+	if (options.backend && !options.server) throw new Error("specification.website(): `backend` requires `server` mode — a deployed `url` cannot be pointed at a local stub.");
+	let backend = null;
+	let backendUrl;
+	if (options.backend) {
+		backend = new StubBackend({ port: options.backend.port });
+		backendUrl = await backend.start();
+	}
 	let serve = null;
 	let baseUrl;
 	if (options.server) {
 		const root = resolveRoot(options.root, callerDir);
-		serve = new ServeAdapter(options.server, root);
-		baseUrl = await serve.start();
+		serve = new ServeAdapter(options.server, root, "website", options.backend && backendUrl !== void 0 ? { [options.backend.env]: backendUrl } : {});
+		try {
+			baseUrl = await serve.start();
+		} catch (error) {
+			await backend?.stop();
+			throw error;
+		}
 	} else baseUrl = options.url.replace(/\/$/, "");
 	let browser = null;
 	const getBrowser = async () => {
@@ -3564,6 +4136,8 @@ async function startWebsite(options) {
 		return browser;
 	};
 	const config = {
+		backend: backend ?? void 0,
+		backendUrl,
 		baseUrl,
 		browser: getBrowser,
 		external: options.external ?? (options.server ? "block" : "allow")
@@ -3575,6 +4149,7 @@ async function startWebsite(options) {
 				browser = null;
 			}
 			if (serve) await serve.stop();
+			if (backend) await backend.stop();
 		},
 		url: baseUrl,
 		website: createWebsiteFacet(config)
@@ -3583,7 +4158,7 @@ async function startWebsite(options) {
 //#endregion
 //#region src/core/specification/shared/specification.ts
 /**
-* The three specification constructors (CONVENTIONS A2) — created in a
+* The five specification constructors (CONVENTIONS A2) — created in a
 * `*.specification.ts` file under `specs/`, destructured with canonical
 * names, and cleaned up via `afterAll(cleanup)` (A1/A3/A4).
 *
@@ -3627,6 +4202,13 @@ const specification = {
 	*/
 	jobs: startJobs,
 	/**
+	* Test a native app on the iOS simulator. `device` names the simulator
+	* (resolved and booted via `simctl`); `app` names the bundle under
+	* test. `.open(deepLink?, scenario?)` relaunches the app fresh, runs
+	* the scenario, and captures the final screen.
+	*/
+	mobile: startMobile,
+	/**
 	* Test a deployed or locally-served website. `server` starts the site
 	* (a shell command receiving `PORT`); `url` targets a running one.
 	* `.visit(path)` renders the page in a single shared browser instance;
@@ -3637,42 +4219,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 +4851,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, ScreenResult, 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 };