@jterrazz/test 16.0.0 → 16.1.0

package/docs/reference/type-aliases/DatabaseKeys.md

@@ -0,0 +1,16 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: DatabaseKeys\<Services\>
+
+```ts
+type DatabaseKeys<Services> = { [K in keyof Services]: Services[K] extends DatabasePort ? K & string : never }[keyof Services];
+```
+
+Defined in: [src/model/chain/services.ts:19](https://github.com/jterrazz/package-test/blob/main/src/model/chain/services.ts#L19)
+
+Keys of a services record whose handles are databases.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `Services` *extends* [`ServiceRecord`](ServiceRecord.md) |

package/docs/reference/type-aliases/DatabasePort.md

@@ -0,0 +1,72 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: DatabasePort
+
+```ts
+type DatabasePort = object;
+```
+
+Defined in: [src/model/ports/database.port.ts:5](https://github.com/jterrazz/package-test/blob/main/src/model/ports/database.port.ts#L5)
+
+Abstract database interface for specification runners.
+Implement this to plug in your database stack (e.g. Postgres, SQLite).
+
+## Properties
+
+### query
+
+```ts
+query: (table, columns) => Promise<unknown[][]>;
+```
+
+Defined in: [src/model/ports/database.port.ts:10](https://github.com/jterrazz/package-test/blob/main/src/model/ports/database.port.ts#L10)
+
+Query a table and return rows as arrays of values.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `table` | `string` |
+| `columns` | `string`[] |
+
+#### Returns
+
+`Promise`\<`unknown`[][]\>
+
+***
+
+### reset
+
+```ts
+reset: () => Promise<void>;
+```
+
+Defined in: [src/model/ports/database.port.ts:13](https://github.com/jterrazz/package-test/blob/main/src/model/ports/database.port.ts#L13)
+
+Reset database to clean state between tests.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### seed
+
+```ts
+seed: (sql) => Promise<void>;
+```
+
+Defined in: [src/model/ports/database.port.ts:7](https://github.com/jterrazz/package-test/blob/main/src/model/ports/database.port.ts#L7)
+
+Execute raw SQL (for seeding test data).
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `sql` | `string` |
+
+#### Returns
+
+`Promise`\<`void`\>

package/docs/reference/type-aliases/DeviceOpenOptions.md

@@ -0,0 +1,46 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: DeviceOpenOptions
+
+```ts
+type DeviceOpenOptions = object;
+```
+
+Defined in: [src/model/ports/device.port.ts:89](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L89)
+
+Per-open options forwarded to the device session.
+
+## Properties
+
+### bundleId
+
+```ts
+bundleId: string;
+```
+
+Defined in: [src/model/ports/device.port.ts:91](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L91)
+
+The app under test — terminated and relaunched for a fresh, deterministic state.
+
+***
+
+### deepLink?
+
+```ts
+optional deepLink?: string;
+```
+
+Defined in: [src/model/ports/device.port.ts:93](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L93)
+
+Deep link applied after the relaunch (`news://events`); absent opens the app plainly.
+
+***
+
+### scenario?
+
+```ts
+optional scenario?: MobileScenario;
+```
+
+Defined in: [src/model/ports/device.port.ts:95](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L95)
+
+The interaction scenario to run after launch; the capture reflects the final state.

package/docs/reference/type-aliases/DevicePort.md

@@ -0,0 +1,51 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: DevicePort
+
+```ts
+type DevicePort = object;
+```
+
+Defined in: [src/model/ports/device.port.ts:123](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L123)
+
+Abstract device interface for the mobile specification runner.
+One implementation lives in `integrations/appium/` — a single driver
+session per runner, created on the first `open()` and reused; each open
+terminates and relaunches the app for a deterministic fresh state.
+
+## Properties
+
+### close
+
+```ts
+close: () => Promise<void>;
+```
+
+Defined in: [src/model/ports/device.port.ts:125](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L125)
+
+End the driver session (idempotent).
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### open
+
+```ts
+open: (options) => Promise<DeviceScreen>;
+```
+
+Defined in: [src/model/ports/device.port.ts:127](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L127)
+
+Relaunch the app, apply the deep link, run the scenario, capture the final screen.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | [`DeviceOpenOptions`](DeviceOpenOptions.md) |
+
+#### Returns
+
+`Promise`\<[`DeviceScreen`](DeviceScreen.md)\>

package/docs/reference/type-aliases/DeviceScreen.md

@@ -0,0 +1,32 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: DeviceScreen
+
+```ts
+type DeviceScreen = object;
+```
+
+Defined in: [src/model/ports/device.port.ts:83](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L83)
+
+The screen captured by a device open — the FINAL state when a scenario
+ran. The tree is the projected page source; `texts` are the visible
+labels/values in document order, consecutive duplicates collapsed.
+
+## Properties
+
+### texts
+
+```ts
+texts: string[];
+```
+
+Defined in: [src/model/ports/device.port.ts:84](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L84)
+
+***
+
+### tree
+
+```ts
+tree: ScreenNode;
+```
+
+Defined in: [src/model/ports/device.port.ts:85](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L85)

package/docs/reference/type-aliases/DeviceTimeouts.md

@@ -0,0 +1,39 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: DeviceTimeouts
+
+```ts
+type DeviceTimeouts = object;
+```
+
+Defined in: [src/model/ports/device.port.ts:104](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L104)
+
+How long a device session waits, in milliseconds. Every field is optional
+and falls back to the framework's own default, so a runner states only the
+wait it needs to move — the defaults suit a release build, and a project
+that drives a DEV build pays for its bundler's cold boot.
+
+## Properties
+
+### action?
+
+```ts
+optional action?: number;
+```
+
+Defined in: [src/model/ports/device.port.ts:109](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L109)
+
+How long every verb polls for a visible match before refusing.
+Default: `30_000` — enough for a cold app boot on a release bundle.
+
+***
+
+### launch?
+
+```ts
+optional launch?: number;
+```
+
+Defined in: [src/model/ports/device.port.ts:114](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L114)
+
+How long the FIRST session waits for WebDriverAgent to build and
+launch on the simulator. Default: `240_000`.

package/docs/reference/type-aliases/DockerSpecConfig.md

@@ -0,0 +1,43 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: DockerSpecConfig
+
+```ts
+type DockerSpecConfig = object;
+```
+
+Defined in: [src/model/chain/builder.ts:47](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L47)
+
+Configuration for the docker-aware cli mode. When set on
+[SpecificationConfig](SpecificationConfig.md), the cli runner generates a test-run id, injects
+it into the child env under `envVar`, then queries Docker for every
+container carrying `testRunLabel=<id>` after the command exits.
+
+## Properties
+
+### envVar
+
+```ts
+envVar: string;
+```
+
+Defined in: [src/model/chain/builder.ts:48](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L48)
+
+***
+
+### nameLabel
+
+```ts
+nameLabel: string;
+```
+
+Defined in: [src/model/chain/builder.ts:49](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L49)
+
+***
+
+### testRunLabel
+
+```ts
+testRunLabel: string;
+```
+
+Defined in: [src/model/chain/builder.ts:50](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L50)

package/docs/reference/type-aliases/DomMount.md

@@ -0,0 +1,21 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: DomMount
+
+```ts
+type DomMount = (container) => (() => void) | void;
+```
+
+Defined in: [src/seams/vitest-browser/ui.ts:18](https://github.com/jterrazz/package-test/blob/main/src/seams/vitest-browser/ui.ts#L18)
+
+A vanilla DOM subject: a function handed the container it must fill. Its
+optional return is the teardown, the way a DOM library states one.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `container` | `HTMLElement` |
+
+## Returns
+
+(() => `void`) \| `void`

package/docs/reference/type-aliases/ElementKind.md

@@ -0,0 +1,27 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ElementKind
+
+```ts
+type ElementKind = 
+  | "button"
+  | "dialog"
+  | "field"
+  | "heading"
+  | "link"
+  | "listitem"
+  | "option"
+  | "row"
+  | "status"
+  | "table"
+  | "testId"
+  | "text";
+```
+
+Defined in: [src/model/ports/browser.port.ts:24](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L24)
+
+The interactive/textual element kinds — what a visitor actually acts on.
+
+`dialog`, `status`, `table`, `row`, `listitem` and `option` are ARIA roles
+like the landmarks, but they are not CONTAINERS of a page: they are things a
+visitor reads and acts on, and they are the roles the estate's UI specs were
+already reaching for through `getByRole` or, worse, through `.first()`.

package/docs/reference/type-aliases/ElementMatch.md

@@ -0,0 +1,74 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ElementMatch
+
+```ts
+type ElementMatch = object;
+```
+
+Defined in: [src/model/ports/browser.port.ts:100](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L100)
+
+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.
+
+## Properties
+
+### accessibleName?
+
+```ts
+optional accessibleName?: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:106](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L106)
+
+The accessible name, when it differs from the text — an `aria-label` is
+what a role descriptor MATCHED on, and printing the text alone sends the
+author to disambiguate a name they cannot see.
+
+***
+
+### context?
+
+```ts
+optional context?: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:108](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L108)
+
+Nearest landmark ancestor (`nav`, `footer`, `main`…), when there is one.
+
+***
+
+### detail?
+
+```ts
+optional detail?: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:110](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L110)
+
+The attribute that disambiguates most — `href` for links, `name` for fields.
+
+***
+
+### tag
+
+```ts
+tag: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:112](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L112)
+
+Tag name, lower-cased.
+
+***
+
+### text
+
+```ts
+text: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:114](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L114)
+
+Text content, whitespace-collapsed and truncated.

package/docs/reference/type-aliases/ElementOptions.md

@@ -0,0 +1,29 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ElementOptions
+
+```ts
+type ElementOptions = object;
+```
+
+Defined in: [src/model/elements/elements.ts:16](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L16)
+
+Options accepted by every named descriptor.
+
+## Properties
+
+### exact?
+
+```ts
+optional exact?: boolean;
+```
+
+Defined in: [src/model/elements/elements.ts:27](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L27)
+
+Match the accessible name as a whole string. `true` by default since
+16.0.
+
+A substring match is what a person does NOT mean: `link('Articles')`
+designated "Read Articles" as readily as "Articles", so a test could pass
+for years against the element beside the one it named. `{ exact: false }`
+is the opt-out, for a name that genuinely carries a variable part the
+test does not control.

package/docs/reference/type-aliases/ElementRef.md

@@ -0,0 +1,128 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ElementRef
+
+```ts
+type ElementRef = object;
+```
+
+Defined in: [src/model/ports/browser.port.ts:47](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L47)
+
+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
+[ElementMatch](ElementMatch.md) and CONVENTIONS W3.
+
+## Properties
+
+### disabled?
+
+```ts
+optional disabled?: boolean;
+```
+
+Defined in: [src/model/ports/browser.port.ts:71](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L71)
+
+Narrows to "and it is (not) accepting input" — built by `disabled(x)` /
+`enabled(x)`. Like `focused`, a STATE the vocabulary can already name the
+element of; unlike it, one the ARIA tree carries too (`[disabled]`), so
+this modifier is what names the ONE control a test is about, and it
+reaches the direction a behavioural substitute cannot — clicking a
+disabled control is a timeout, never an answer.
+
+***
+
+### exact?
+
+```ts
+optional exact?: boolean;
+```
+
+Defined in: [src/model/ports/browser.port.ts:56](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L56)
+
+Match the accessible name as a whole string rather than a substring.
+
+ABSENT means "the author said nothing", which the adapters read as the
+default — exact — while keeping the information that no choice was made,
+so a name that matches only as a substring can be reported once with the
+transitional warning.
+
+***
+
+### focused?
+
+```ts
+optional focused?: boolean;
+```
+
+Defined in: [src/model/ports/browser.port.ts:62](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L62)
+
+Assert about the element's FOCUS rather than its presence — built by
+`focused(element)`. The accessibility tree carries no focus state, so
+where the keyboard is cannot be goldened; it is asserted by a verb.
+
+***
+
+### kind
+
+```ts
+kind: ElementKind | LandmarkKind;
+```
+
+Defined in: [src/model/ports/browser.port.ts:72](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L72)
+
+***
+
+### name?
+
+```ts
+optional name?: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:74](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L74)
+
+Landmarks may be anonymous (`main()`, `banner()`); everything else is named.
+
+***
+
+### scope?
+
+```ts
+optional scope?: ElementRef;
+```
+
+Defined in: [src/model/ports/browser.port.ts:92](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L92)
+
+Restrict the search to the elements of another descriptor — built by
+`within(scope, target)`. Chains: a scope may itself carry a scope.
+
+***
+
+### selected?
+
+```ts
+optional selected?: boolean;
+```
+
+Defined in: [src/model/ports/browser.port.ts:81](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L81)
+
+Narrows to "and it is (not) the chosen one" — built by `selected(x)`.
+An option of a COLLAPSED select is in the tree and in the document, and
+it has no box on the screen, so this facet of it is read from the node
+(`:checked`) rather than from what a visitor could point at.
+
+***
+
+### value?
+
+```ts
+optional value?: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:87](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L87)
+
+The value the field must hold — built by `valued(field('Title'), '…')`.
+A field's value is a PROPERTY of the node: a controlled input's `value`
+attribute never moves, so nothing but the live value answers for it.

package/docs/reference/type-aliases/ExecOptions.md

@@ -0,0 +1,37 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ExecOptions
+
+```ts
+type ExecOptions = object;
+```
+
+Defined in: [src/model/ports/cli.port.ts:19](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L19)
+
+Options for the long-running form of `.exec()` (CONVENTIONS B2). When
+either option is present the process is spawned and observed: it resolves
+as soon as `waitFor` appears in stdout/stderr, and is killed when `timeout`
+elapses (exit code 124).
+
+## Properties
+
+### timeout?
+
+```ts
+optional timeout?: number;
+```
+
+Defined in: [src/model/ports/cli.port.ts:23](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L23)
+
+Kill the process after this many milliseconds. Defaults to 10 000.
+
+***
+
+### waitFor?
+
+```ts
+optional waitFor?: string;
+```
+
+Defined in: [src/model/ports/cli.port.ts:21](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L21)
+
+Resolve (exit code 0) when stdout/stderr contains this string.

package/docs/reference/type-aliases/FileAccessor.md

@@ -0,0 +1,54 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: FileAccessor
+
+```ts
+type FileAccessor = object;
+```
+
+Defined in: [src/model/result/result.ts:13](https://github.com/jterrazz/package-test/blob/main/src/model/result/result.ts#L13)
+
+Read-only handle to a single file produced by a spec action.
+
+## Properties
+
+### content
+
+```ts
+readonly content: string;
+```
+
+Defined in: [src/model/result/result.ts:15](https://github.com/jterrazz/package-test/blob/main/src/model/result/result.ts#L15)
+
+The UTF-8 text content. Throws if the file does not exist.
+
+***
+
+### exists
+
+```ts
+readonly exists: boolean;
+```
+
+Defined in: [src/model/result/result.ts:16](https://github.com/jterrazz/package-test/blob/main/src/model/result/result.ts#L16)
+
+***
+
+### grep
+
+```ts
+grep: (pattern) => TextAccessor;
+```
+
+Defined in: [src/model/result/result.ts:18](https://github.com/jterrazz/package-test/blob/main/src/model/result/result.ts#L18)
+
+The file text as a [TextAccessor](../interfaces/TextAccessor.md), keeping only blocks matching `pattern`.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `pattern` | `string` |
+
+#### Returns
+
+[`TextAccessor`](../interfaces/TextAccessor.md)