@jterrazz/test 16.0.0 → 16.1.0

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

@@ -0,0 +1,290 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: SpecificationConfig
+
+```ts
+type SpecificationConfig = object;
+```
+
+Defined in: [src/model/chain/builder.ts:54](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L54)
+
+Adapter configuration passed to the specification facets at setup time.
+
+## Properties
+
+### backend?
+
+```ts
+optional backend?: StubBackend;
+```
+
+Defined in: [src/model/chain/builder.ts:59](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L59)
+
+The declared stub backend (website/mobile facets) — armed with the
+chain's contracts before every terminal action.
+
+***
+
+### backendUrl?
+
+```ts
+optional backendUrl?: string;
+```
+
+Defined in: [src/model/chain/builder.ts:64](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L64)
+
+Base URL of the running stub backend — allow-listed through the
+browser's `external: 'block'` policy so client-side fetches reach it.
+
+***
+
+### baseUrl?
+
+```ts
+optional baseUrl?: string;
+```
+
+Defined in: [src/model/chain/builder.ts:66](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L66)
+
+Base URL of the website under test (website facet only).
+
+***
+
+### browser?
+
+```ts
+optional browser?: () => Promise<BrowserPort>;
+```
+
+Defined in: [src/model/chain/builder.ts:72](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L72)
+
+Lazy browser accessor (website facet only). The first `.visit()`
+launches the shared browser instance; `.fetch()`-only spec files never
+pay the browser cost.
+
+#### Returns
+
+`Promise`\<[`BrowserPort`](BrowserPort.md)\>
+
+***
+
+### bundleId?
+
+```ts
+optional bundleId?: string;
+```
+
+Defined in: [src/model/chain/builder.ts:80](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L80)
+
+Bundle id of the app under test (mobile facet only) — the app `.open()` relaunches.
+
+***
+
+### command?
+
+```ts
+optional command?: CliPort;
+```
+
+Defined in: [src/model/chain/builder.ts:81](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L81)
+
+***
+
+### database?
+
+```ts
+optional database?: DatabasePort;
+```
+
+Defined in: [src/model/chain/builder.ts:82](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L82)
+
+***
+
+### databaseKeys?
+
+```ts
+optional databaseKeys?: string[];
+```
+
+Defined in: [src/model/chain/builder.ts:88](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L88)
+
+Keys of the declared services record that are databases. Drives the
+CONVENTIONS A7 rule: with 2+ databases the `database` option is
+mandatory on `.seed()` / `.table()`; with exactly one it is forbidden.
+
+***
+
+### databases?
+
+```ts
+optional databases?: Map<string, DatabasePort>;
+```
+
+Defined in: [src/model/chain/builder.ts:89](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L89)
+
+***
+
+### defaultEnv?
+
+```ts
+optional defaultEnv?: CliEnv;
+```
+
+Defined in: [src/model/chain/builder.ts:110](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L110)
+
+Environment applied to every run of the declared binary
+(`specification.cli({ defaults })`) — under a chain's own `.env()` and
+under a document's `env:`, both of which win.
+
+***
+
+### device?
+
+```ts
+optional device?: () => Promise<DevicePort>;
+```
+
+Defined in: [src/model/chain/builder.ts:96](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L96)
+
+Lazy device accessor (mobile facet only). The first `.open()` creates
+the shared driver session; the appium/webdriverio integration stays a
+lazy import so the optional peer is only loaded when a spec opens the
+app.
+
+#### Returns
+
+`Promise`\<[`DevicePort`](DevicePort.md)\>
+
+***
+
+### dockerConfig?
+
+```ts
+optional dockerConfig?: DockerSpecConfig;
+```
+
+Defined in: [src/model/chain/builder.ts:97](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L97)
+
+***
+
+### dockerTestRunId?
+
+```ts
+optional dockerTestRunId?: string;
+```
+
+Defined in: [src/model/chain/builder.ts:104](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L104)
+
+Unique id shared by every spec from this runner instance.
+Stable for the runner's lifetime so multi-step tests (spawn in
+one run, inspect in another) see the same container scope. The
+facet factories auto-populate this when `dockerConfig` is present.
+
+***
+
+### envSets?
+
+```ts
+optional envSets?: Record<string, CliEnv>;
+```
+
+Defined in: [src/model/chain/builder.ts:115](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L115)
+
+Named environment SETS a spec document may name by bare word
+(`env: frozen`). Declared once per app in `specification.cli()`.
+
+***
+
+### external?
+
+```ts
+optional external?: "allow" | "block";
+```
+
+Defined in: [src/model/chain/builder.ts:78](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L78)
+
+Cross-origin request policy for visits (website facet only): `'block'`
+aborts requests leaving the site under test — the browser-side analog
+of strict intercepts.
+
+***
+
+### jobs?
+
+```ts
+optional jobs?: JobHandle[];
+```
+
+Defined in: [src/model/chain/builder.ts:116](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L116)
+
+***
+
+### root?
+
+```ts
+optional root?: string;
+```
+
+Defined in: [src/model/chain/builder.ts:118](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L118)
+
+The project root — the working directory a document's `serve:` command runs from.
+
+***
+
+### server?
+
+```ts
+optional server?: ServerPort;
+```
+
+Defined in: [src/model/chain/builder.ts:119](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L119)
+
+***
+
+### serveRegistry?
+
+```ts
+optional serveRegistry?: Record<string, LiterateServeRegistration>;
+```
+
+Defined in: [src/model/chain/builder.ts:124](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L124)
+
+Named servers a spec document may start (`serve: [mcp]`). Declared once
+per app in `specification.cli()`.
+
+***
+
+### services?
+
+```ts
+optional services?: Record<string, ServiceHandle>;
+```
+
+Defined in: [src/model/chain/builder.ts:131](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L131)
+
+The declared services record. In cli mode, drives the automatic
+connection-URL injection into the child env (CONVENTIONS B6):
+`<KEY>_URL` per service, plus `DATABASE_URL` / `REDIS_URL` when
+unambiguous.
+
+***
+
+### transform?
+
+```ts
+optional transform?: (text) => string;
+```
+
+Defined in: [src/model/chain/builder.ts:136](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L136)
+
+Optional normaliser applied to command stdout/stderr before every
+comparison. Does not mutate the raw `.text` accessor.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `text` | `string` |
+
+#### Returns
+
+`string`

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

@@ -0,0 +1,36 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: SqliteOptions
+
+```ts
+type SqliteOptions = object;
+```
+
+Defined in: [src/seams/sqlite/sqlite.ts:127](https://github.com/jterrazz/package-test/blob/main/src/seams/sqlite/sqlite.ts#L127)
+
+## Properties
+
+### init?
+
+```ts
+optional init?: string;
+```
+
+Defined in: [src/seams/sqlite/sqlite.ts:132](https://github.com/jterrazz/package-test/blob/main/src/seams/sqlite/sqlite.ts#L132)
+
+Path to a SQL file used to initialize the database schema.
+Mutually exclusive with `prismaSchema`.
+
+***
+
+### prismaSchema?
+
+```ts
+optional prismaSchema?: string;
+```
+
+Defined in: [src/seams/sqlite/sqlite.ts:139](https://github.com/jterrazz/package-test/blob/main/src/seams/sqlite/sqlite.ts#L139)
+
+Path to a Prisma schema directory or file, resolved against the current
+working directory. The adapter runs `prisma db push --schema <path>` to
+create the template, so the schema needs no Prisma config at the cwd.
+Mutually exclusive with `init`.

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

@@ -0,0 +1,58 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: SseEvent
+
+```ts
+type SseEvent = object;
+```
+
+Defined in: [src/model/contracts/http.ts:44](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L44)
+
+One server-sent event, as `http.sse()` frames it.
+
+## Properties
+
+### data
+
+```ts
+data: unknown;
+```
+
+Defined in: [src/model/contracts/http.ts:46](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L46)
+
+The `data:` payload. An object is serialised as JSON; a string is sent as-is.
+
+***
+
+### event?
+
+```ts
+optional event?: string;
+```
+
+Defined in: [src/model/contracts/http.ts:48](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L48)
+
+The `event:` name. Omitted for an unnamed (default `message`) event.
+
+***
+
+### id?
+
+```ts
+optional id?: string;
+```
+
+Defined in: [src/model/contracts/http.ts:50](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L50)
+
+The `id:` the client echoes as `Last-Event-ID` when it reconnects.
+
+***
+
+### retry?
+
+```ts
+optional retry?: number;
+```
+
+Defined in: [src/model/contracts/http.ts:52](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/http.ts#L52)
+
+The `retry:` hint, in milliseconds.

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

@@ -0,0 +1,61 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: StreamBody
+
+```ts
+type StreamBody = object;
+```
+
+Defined in: [src/model/contracts/types.ts:84](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L84)
+
+A body that arrives in pieces — what `http.stream()` and `http.sse()` build.
+
+The chunks are written in order, `delayBetweenChunks` milliseconds apart,
+and the connection closes after the last one. It is the chunks and their
+ORDER that a streaming subject is specified against: a client that renders
+tokens as they land, or one that reconnects on a half-read body.
+
+## Properties
+
+### chunks
+
+```ts
+chunks: readonly string[];
+```
+
+Defined in: [src/model/contracts/types.ts:86](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L86)
+
+The pieces, written in order.
+
+***
+
+### contentType
+
+```ts
+contentType: string;
+```
+
+Defined in: [src/model/contracts/types.ts:88](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L88)
+
+The `content-type` the stream is served under.
+
+***
+
+### delayBetweenChunks
+
+```ts
+delayBetweenChunks: number;
+```
+
+Defined in: [src/model/contracts/types.ts:90](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L90)
+
+Milliseconds between two chunks. Default 0 — everything at once.
+
+***
+
+### kind
+
+```ts
+kind: typeof STREAM_BODY;
+```
+
+Defined in: [src/model/contracts/types.ts:91](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L91)

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

@@ -0,0 +1,22 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: TextFilter
+
+```ts
+type TextFilter = Matcher | RegExp | string;
+```
+
+Defined in: [src/model/contracts/filters.ts:20](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/filters.ts#L20)
+
+A text filter on a provider request builder (`openai.chat({ user })`,
+`anthropic.messages({ system })`, …).
+
+A **string is EXACT**. That is deliberate: a substring filter silently
+cross-matches — two prompts sharing a preamble both satisfy the first
+contract, and the spec goes green on the wrong reply. Looser matching is
+explicit, and says which looseness it means:
+
+- a `RegExp` — pattern matching;
+- `match.includes('…')` — containment, the code-only matcher (it never joins
+  the `{{token}}` file vocabulary, CONVENTIONS D4);
+- any other `match.*` matcher, evaluated by the same structural engine the
+  assertions use.

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

@@ -0,0 +1,20 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: VisitScenario
+
+```ts
+type VisitScenario = (visitor) => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:170](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L170)
+
+The behavior of a visit — the When of the spec; assertions stay in the Then.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `visitor` | [`Visitor`](Visitor.md) |
+
+## Returns
+
+`Promise`\<`void`\>

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

@@ -0,0 +1,215 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: Visitor
+
+```ts
+type Visitor = object;
+```
+
+Defined in: [src/model/ports/browser.port.ts:144](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L144)
+
+The visitor — the interaction vocabulary handed to a visit scenario.
+Every action auto-waits (playwright actionability); `see()` is the single
+synchronization primitive: it retries until the element is visible and
+fails at the timeout. There is no sleep and no conditional helper.
+
+## Properties
+
+### check
+
+```ts
+check: (element) => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:146](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L146)
+
+Check a checkbox or radio.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`ElementRef`](ElementRef.md) |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### click
+
+```ts
+click: (element) => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:148](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L148)
+
+Click the element.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`ElementRef`](ElementRef.md) |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### fill
+
+```ts
+fill: (element, value) => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:150](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L150)
+
+Fill a form field with a value.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`ElementRef`](ElementRef.md) |
+| `value` | `string` |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### gone
+
+```ts
+gone: (element) => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:156](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L156)
+
+Wait until the element is GONE — hidden, or never in the document. The
+absence primitive: `see()` cannot answer "the dialog closed", because an
+element that never appears and one that disappeared read the same to it.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`ElementRef`](ElementRef.md) |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### goto
+
+```ts
+goto: (path) => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:158](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L158)
+
+Navigate to a path of the site under test.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### hover
+
+```ts
+hover: (element) => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:160](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L160)
+
+Hover the element.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`ElementRef`](ElementRef.md) |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### press
+
+```ts
+press: (key) => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:162](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L162)
+
+Press a key (e.g. `Enter`).
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `key` | `string` |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### see
+
+```ts
+see: (element) => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:164](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L164)
+
+Wait until the element is visible — the only synchronization primitive.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`ElementRef`](ElementRef.md) |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### select
+
+```ts
+select: (element, option) => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:166](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L166)
+
+Select an option in a select field.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`ElementRef`](ElementRef.md) |
+| `option` | `string` |
+
+#### Returns
+
+`Promise`\<`void`\>