@jterrazz/test 10.0.0 → 10.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @jterrazz/test
 
-Declarative testing framework for APIs, jobs, CLIs, and websites. Four constructors — `specification.api()`, `specification.jobs()`, `specification.cli()`, `specification.website()` — and specs that read as sentences: given → action → assertions. The vitest test name is the spec's description; all assertions go through `expect()` with auto-registered, subject-typed matchers.
+Declarative testing framework for APIs, jobs, CLIs, websites, and mobile apps. Five constructors — `specification.api()`, `specification.jobs()`, `specification.cli()`, `specification.website()`, `specification.mobile()` — and specs that read as sentences: given → action → assertions. The vitest test name is the spec's description; all assertions go through `expect()` with auto-registered, subject-typed matchers.
 
 ```bash
 npm install -D @jterrazz/test vitest
@@ -105,9 +105,38 @@ test('captures the full head surface of a rendered page', async () => {
 });
 ```
 
-Actions are **terminal**: `.request()`, `.get()`, `.trigger()`, `.exec()`, `.fetch()`, `.visit()` execute the spec and resolve to a precisely typed result. There is no `.run()`, no label, and no `.spawn()`.
+### Mobile testing (iOS simulator)
 
-## The four constructors
+```typescript
+// specs/mobile/mobile.specification.ts
+import { specification } from '@jterrazz/test';
+import { afterAll } from 'vitest';
+
+export const { cleanup, mobile } = await specification.mobile({
+    app: { bundleId: 'com.jterrazz.fakenews' },
+    device: { name: 'iPhone 17', os: '26.5' },
+});
+
+afterAll(cleanup);
+```
+
+```typescript
+// specs/mobile/events/feed.test.ts
+import { expect, test } from 'vitest';
+import { mobile } from '../mobile.specification.js';
+
+test('shows the events feed behind its deep link', async () => {
+    // Given - the events screen
+    const result = await mobile.open('news://events');
+
+    // Then - one golden covers the whole projected accessibility tree
+    expect(result.screen).toMatch('events.screen.json');
+});
+```
+
+Actions are **terminal**: `.request()`, `.get()`, `.trigger()`, `.exec()`, `.fetch()`, `.visit()`, `.open()` execute the spec and resolve to a precisely typed result. There is no `.run()`, no label, and no `.spawn()`.
+
+## The five constructors
 
 One constructor per tested interface, each returning a record destructured with its canonical name:
 
@@ -117,6 +146,7 @@ One constructor per tested interface, each returning a record destructured with
 | `specification.jobs(options)`     | `{ jobs, cleanup, orchestrator }`        | `.trigger(name)`                                             |
 | `specification.cli(bin, options)` | `{ cli, cleanup, docker, orchestrator }` | `.exec(args, { waitFor?, timeout? }?)`                       |
 | `specification.website(options)`  | `{ website, cleanup, url }`              | `.fetch(path)`, `.visit(path, scenario?)`                    |
+| `specification.mobile(options)`   | `{ mobile, cleanup, udid }`              | `.open(deepLink?, scenario?)`                                |
 
 ### `specification.api({ services, server, mode?, root? })`
 
@@ -176,9 +206,9 @@ export const { cli, cleanup } = await specification.cli('my-migrate-tool', {
 const result = await cli.seed('legacy-schema.sql').exec('up');
 ```
 
-### `specification.website({ server?, url?, external?, root? })`
+### `specification.website({ server?, url?, backend?, external?, root? })`
 
-Tests a rendered website: `.fetch(path)` for a raw HTTP exchange (redirects never followed), `.visit(path, scenario?)` for a page rendered in a real chromium. Exactly one of `server` (start the site locally — a free port injected as `PORT`, polled on `ready`) or `url` (target a running site) is required.
+Tests a rendered website: `.fetch(path)` for a raw HTTP exchange (redirects never followed), `.visit(path, scenario?)` for a page rendered in a real chromium. Exactly one of `server` (start the site locally — a free port injected as `PORT`, polled on `ready`) or `url` (target a running site) is required. `backend: { env, port? }` (server mode only) additionally starts a declared stub backend and injects its URL into the server child under `env`; each chain declares what it serves via `.intercept('<name>.http')`.
 
 ```typescript
 export const { website, cleanup } = await specification.website({
@@ -196,6 +226,25 @@ const page = await website.visit('/', async (visitor) => {
 
 The handle destructures to `{ website, cleanup, url }` — no `docker`, no `orchestrator`. `.visit()` needs playwright (`npm install -D playwright && npx playwright install chromium`) — an optional peer dependency, only loaded when a spec actually renders a page. Full reference: [docs/11-website.md](docs/11-website.md).
 
+### `specification.mobile({ app, device, backend?, root? })`
+
+Tests a native app on the iOS simulator through a real XCUITest session (appium): `.open(deepLink?, scenario?)` terminates and relaunches the app (deterministic fresh state), applies the deep link, runs the scenario, and captures the final screen — the projected accessibility tree plus the visible texts. The simulator is resolved by `device: { name, os?, udid? }` via `xcrun simctl` (refusing on zero or several matches) and booted when shut down; the appium server is spawned from the caller project on a free port.
+
+```typescript
+export const { mobile, cleanup, udid } = await specification.mobile({
+    app: { bundleId: 'com.jterrazz.fakenews' },
+    device: { name: 'iPhone 17', os: '26.5' },
+});
+
+// A screen behind its deep link, driven by a scenario (the When)
+const result = await mobile.open('news://events', async (visitor) => {
+    await visitor.tap(button('Enquête Fauci COVID-19'));
+    await visitor.see(content('rapports'));
+});
+```
+
+The handle destructures to `{ mobile, cleanup, udid }` (plus `backendUrl` with `backend: { port? }` — a declared stub backend whose URL the CALLER wires into its own bundler env; the framework never touches Metro). The element vocabulary is the website facet's, unchanged — `button`, `field`, `content`, `testId`, `within` — landmarks excepted (an iOS screen has no ARIA regions; they refuse at runtime). Requires the app installed on the simulator plus the optional peers: `npm install -D appium webdriverio && npx appium driver install xcuitest`. Full reference: [docs/12-mobile.md](docs/12-mobile.md).
+
 ### Root auto-discovery
 
 When `root` is absent, the framework walks up from the specification file to the first directory containing `docker/compose.test.yaml`, else the first containing `package.json`. Pass `root` only when the convention does not fit. `root` is strictly the **project root** (compose detection + local-bin resolution, or the cwd of a `specification.website()` server command) — it is not a fixtures root; `.fixture()` resolves its own paths.
@@ -213,20 +262,22 @@ When `root` is absent, the framework walks up from the specification file to the
 | `.headers({ "Accept-Language": "fr" })` | api, website | Set HTTP request headers (merge on top of `.http` file headers, or on the browser context)             |
 | `.intercept(contract)`                  | api, jobs    | Intercept an outgoing HTTP call with a declared contract                                               |
 | `.intercept(trigger, response)`         | api, jobs    | Inline intercept for one-off cases                                                                     |
+| `.intercept("two-events.http")`         | all but cli  | Declared exchanges from `intercepts/<name>.http` — MSW on api/jobs, the stub backend on website/mobile |
 
 ### Actions (terminal)
 
-| Method                                     | Facet   | Resolves to   | Description                                                                           |
-| ------------------------------------------ | ------- | ------------- | ------------------------------------------------------------------------------------- |
-| `.request("create-user.http")`             | api     | `HttpResult`  | Send the COMPLETE request from `requests/<file>` (method, path, headers, raw body)    |
-| `.get(path)` / `.delete(path)`             | api     | `HttpResult`  | Inline requests for simple cases                                                      |
-| `.post(path, body?)` / `.put(path, body?)` | api     | `HttpResult`  | Inline body: plain object, JSON-serialized                                            |
-| `.trigger("name")`                         | jobs    | `BaseResult`  | Execute a registered job                                                              |
-| `.exec("args")`                            | cli     | `CliResult`   | Run the command                                                                       |
-| `.exec(["build", "start"])`                | cli     | `CliResult`   | Sequence in the same cwd; stops on first non-zero exit                                |
-| `.exec("dev", { waitFor, timeout? })`      | cli     | `CliResult`   | Long-running: resolves at the pattern, killed at `timeout` (default 10 s)             |
-| `.fetch(path)`                             | website | `FetchResult` | One raw HTTP exchange — redirects surface as 3xx, never followed                      |
-| `.visit(path, scenario?)`                  | website | `PageResult`  | Render the page in a shared chromium; with a scenario, the capture is the final state |
+| Method                                     | Facet   | Resolves to    | Description                                                                              |
+| ------------------------------------------ | ------- | -------------- | ---------------------------------------------------------------------------------------- |
+| `.request("create-user.http")`             | api     | `HttpResult`   | Send the COMPLETE request from `requests/<file>` (method, path, headers, raw body)       |
+| `.get(path)` / `.delete(path)`             | api     | `HttpResult`   | Inline requests for simple cases                                                         |
+| `.post(path, body?)` / `.put(path, body?)` | api     | `HttpResult`   | Inline body: plain object, JSON-serialized                                               |
+| `.trigger("name")`                         | jobs    | `BaseResult`   | Execute a registered job                                                                 |
+| `.exec("args")`                            | cli     | `CliResult`    | Run the command                                                                          |
+| `.exec(["build", "start"])`                | cli     | `CliResult`    | Sequence in the same cwd; stops on first non-zero exit                                   |
+| `.exec("dev", { waitFor, timeout? })`      | cli     | `CliResult`    | Long-running: resolves at the pattern, killed at `timeout` (default 10 s)                |
+| `.fetch(path)`                             | website | `FetchResult`  | One raw HTTP exchange — redirects surface as 3xx, never followed                         |
+| `.visit(path, scenario?)`                  | website | `PageResult`   | Render the page in a shared chromium; with a scenario, the capture is the final state    |
+| `.open(deepLink?, scenario?)`              | mobile  | `ScreenResult` | Relaunch the app fresh on the simulator; with a scenario, the capture is the final state |
 
 One chain = one terminal action; databases reset at the start of every chain. Every cli spec runs in a fresh, empty temp directory.
 
@@ -307,7 +358,7 @@ export default defineContract({
 const result = await jobs.intercept(classifyProduct).trigger('nightly-report');
 ```
 
-Inline `.intercept(trigger, response)` and JSON fixtures (`intercepts/<provider>/<name>.json`) remain for one-off cases. Failure simulation: `openai.error(429)`, `anthropic.timeout()`, `openai.malformed('not json')`. Intercepts queue FIFO per trigger. MSW ships as a direct dependency — no separate install.
+Inline `.intercept(trigger, response)` and JSON fixtures (`intercepts/<provider>/<name>.json`) remain for one-off cases; `.intercept('<name>.http')` loads declared exchanges from a bi-block `intercepts/<name>.http` file — the form website/mobile chains use, served by the declared `backend` stub. Failure simulation: `openai.error(429)`, `anthropic.timeout()`, `openai.malformed('not json')`. Intercepts queue FIFO per trigger. MSW ships as a direct dependency — no separate install.
 
 ## Docker-aware CLIs
 
@@ -359,7 +410,7 @@ specs/<facet>/                  # api | jobs | cli | integrations | lint
     ├── seeds/          # *.sql ONLY — database state
     ├── requests/       # *.http — inputs: COMPLETE request (method, path, headers, body)
     ├── contracts/      # <name>.<provider>.ts — declared external interactions
-    ├── intercepts/     # <provider>/<name>.json — inline intercept fixtures
+    ├── intercepts/     # <provider>/<name>.json — inline intercept fixtures; <name>.http — declared exchanges (flat)
     ├── fixtures/       # domain-local files/dirs copied into the cwd (cli) — shared pool lives at specs/fixtures/
     └── expected/       # ALL expected fixtures, FLAT (incl. response *.http) — a slash in the name creates a subfolder
 ```
@@ -374,14 +425,15 @@ These conventions are not just prose: the package ships an oxlint plugin (`@jter
 
 ## Requirements
 
-- **Docker** - testcontainers for node mode, docker compose for compose mode; not needed for `sqlite()`, plain cli specs, or website specs
+- **Docker** - testcontainers for node mode, docker compose for compose mode; not needed for `sqlite()`, plain cli specs, website specs, or mobile specs
 - **vitest** - peer dependency
 - **playwright** - optional peer dependency, only needed for `.visit()`: `npm install -D playwright && npx playwright install chromium`
+- **appium + webdriverio** - optional peer dependencies, only needed for `specification.mobile()`: `npm install -D appium webdriverio && npx appium driver install xcuitest` — plus Xcode, a simulator, and the app installed on it
 - **msw** - bundled as a direct dependency (powers `.intercept()`); no separate install
 - **hono** (or any web framework) - supplied by your project for in-process apps; the adapter only needs an object with a `request()` method, so it is not a peer
 
 ## Docs
 
-- Guide (chapters): [docs/README.md](docs/README.md) — getting started, API/jobs/CLI/website specs, assertions, tokens, contracts, services, conventions, linting
+- Guide (chapters): [docs/README.md](docs/README.md) — getting started, API/jobs/CLI/website/mobile specs, assertions, tokens, contracts, services, conventions, linting
 - API reference: committed under [docs/reference/](docs/reference/) — compiled from source by `npm run docs`
 - Agent skill: [skills/jterrazz-test/](skills/jterrazz-test/) — mental model, per-facet references, generated rule reference

package/dist/ambiguity.js

@@ -0,0 +1,126 @@
+//#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
+export { describeAmbiguity as n, formatElement as r, AmbiguousElementError as t };