@jterrazz/test 16.1.1 → 18.0.0

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

@@ -1,215 +0,0 @@
-<!-- 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`\>

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

@@ -1,46 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: WaitUntilOptions
-
-```ts
-type WaitUntilOptions = object;
-```
-
-Defined in: [src/model/assertions/wait-until.ts:4](https://github.com/jterrazz/package-test/blob/main/src/model/assertions/wait-until.ts#L4)
-
-How long to wait, and how often to look.
-
-## Properties
-
-### interval?
-
-```ts
-optional interval?: number;
-```
-
-Defined in: [src/model/assertions/wait-until.ts:6](https://github.com/jterrazz/package-test/blob/main/src/model/assertions/wait-until.ts#L6)
-
-Milliseconds between two readings. Default 50.
-
-***
-
-### timeout?
-
-```ts
-optional timeout?: number;
-```
-
-Defined in: [src/model/assertions/wait-until.ts:8](https://github.com/jterrazz/package-test/blob/main/src/model/assertions/wait-until.ts#L8)
-
-How long the condition has to become true. Default 5 000 ms.
-
-***
-
-### why?
-
-```ts
-optional why?: string;
-```
-
-Defined in: [src/model/assertions/wait-until.ts:10](https://github.com/jterrazz/package-test/blob/main/src/model/assertions/wait-until.ts#L10)
-
-What the condition is, named in the failure. Default: the predicate's source.

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

@@ -1,37 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: WebsiteBackendOptions
-
-```ts
-type WebsiteBackendOptions = object;
-```
-
-Defined in: [src/facets/website/website.specification.ts:62](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L62)
-
-The declared stub backend behind the site under test — started before the
-server command, torn down with the runner. Its URL is injected into the
-server child's environment under `env`; the contracts each chain declares
-via `.intercept(...)` are what it serves.
-
-## Properties
-
-### env
-
-```ts
-env: string;
-```
-
-Defined in: [src/facets/website/website.specification.ts:64](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L64)
-
-Env var receiving the stub's URL in the server child (e.g. `'API_URL'`).
-
-***
-
-### port?
-
-```ts
-optional port?: number;
-```
-
-Defined in: [src/facets/website/website.specification.ts:66](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L66)
-
-Fixed port — pins a stable stub URL across runs. Default: a free OS-assigned port.

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

@@ -1,51 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: WebsiteHandle
-
-```ts
-type WebsiteHandle = object;
-```
-
-Defined in: [src/facets/website/website.specification.ts:213](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L213)
-
-The record returned by startWebsite \| specification.website.
-Destructure with the canonical names (CONVENTIONS A3):
-
-    const { website, cleanup } = await specification.website(…);
-
-## Properties
-
-### cleanup
-
-```ts
-cleanup: () => Promise<void>;
-```
-
-Defined in: [src/facets/website/website.specification.ts:215](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L215)
-
-Stop the server process and the shared browser instance.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-***
-
-### url
-
-```ts
-url: string;
-```
-
-Defined in: [src/facets/website/website.specification.ts:217](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L217)
-
-The base URL the specs run against.
-
-***
-
-### website
-
-```ts
-website: WebsiteSpecification;
-```
-
-Defined in: [src/facets/website/website.specification.ts:218](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L218)

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

@@ -1,118 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: WebsiteSpecification
-
-```ts
-type WebsiteSpecification = object;
-```
-
-Defined in: [src/model/chain/builder.ts:302](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L302)
-
-The `website` facet — page chain entry handed out by
-`specification.website()`. Setup methods chain; action methods are
-terminal. `.visit()` renders the page in the shared browser; `.fetch()`
-performs one raw HTTP exchange and never follows redirects.
-
-## Properties
-
-### clock
-
-```ts
-clock: (iso) => WebsiteSpecification;
-```
-
-Defined in: [src/model/chain/builder.ts:307](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L307)
-
-Pin the PAGE's `Date` at `iso` for this chain — what the site's own
-scripts read. A `.fetch()` opens no page and refuses the setup.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `iso` | `string` |
-
-#### Returns
-
-`WebsiteSpecification`
-
-***
-
-### fetch
-
-```ts
-fetch: (path) => Promise<FetchResult>;
-```
-
-Defined in: [src/model/chain/builder.ts:317](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L317)
-
-Perform one raw HTTP GET — redirects surface as 3xx results, never followed.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `path` | `string` |
-
-#### Returns
-
-`Promise`\<[`FetchResult`](../interfaces/FetchResult.md)\>
-
-***
-
-### headers
-
-```ts
-headers: (headers) => WebsiteSpecification;
-```
-
-Defined in: [src/model/chain/builder.ts:309](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L309)
-
-Set HTTP headers for the exchange (incl. User-Agent overrides). Multiple calls merge.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `headers` | `Record`\<`string`, `string`\> |
-
-#### Returns
-
-`WebsiteSpecification`
-
-***
-
-### intercept
-
-```ts
-intercept: InterceptMethod<WebsiteSpecification>;
-```
-
-Defined in: [src/model/chain/builder.ts:314](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L314)
-
-Declare the chain's backend contracts — served by the declared stub
-backend (requires the runner's `backend` option). Multiple calls append.
-
-***
-
-### visit
-
-```ts
-visit: (path, scenario?) => Promise<PageResult>;
-```
-
-Defined in: [src/model/chain/builder.ts:323](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L323)
-
-Render the page in the shared browser and resolve with the captured
-document. With a scenario, the visitor interacts first (the When) and
-the capture reflects the FINAL page state.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `path` | `string` |
-| `scenario?` | [`VisitScenario`](VisitScenario.md) |
-
-#### Returns
-
-`Promise`\<[`PageResult`](../interfaces/PageResult.md)\>

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

@@ -1,40 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: WebsiteSpecificationOptions\<Services\>
-
-```ts
-type WebsiteSpecificationOptions<Services> = object & 
-  | {
-  backend?: WebsiteBackendOptions;
-  server: ServerSpec<Services>;
-  url?: never;
-}
-  | {
-  backend?: never;
-  server?: never;
-  url: string;
-};
-```
-
-Defined in: [src/facets/website/website.specification.ts:77](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L77)
-
-Options for startWebsite \| specification.website. `server` (start
-the site locally) and `url` (target a running site) are mutually
-exclusive BY TYPE — the union makes the invalid combinations
-inexpressible rather than runtime-checked. `backend` requires `server`
-mode for the same reason: a deployed site cannot be pointed at a local
-stub.
-
-## Type Declaration
-
-| Name | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ |
-| `external?` | `"allow"` \| `"block"` | Cross-origin request policy for visits. Default: `'block'` with a local `server` (deterministic — analytics and CDNs never leave the machine), `'allow'` with a deployed `url`. | [src/facets/website/website.specification.ts:83](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L83) |
-| `root?` | `string` | Project-root override (CONVENTIONS A9): the working directory of the `server` command. Auto-discovered from the calling file when absent. | [src/facets/website/website.specification.ts:88](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L88) |
-| `services?` | `Services` | Named services started with the runner, before the site is: a database the site reads, a `process()` backend it calls. They are started in declaration order and stopped with the specification, and `server` may be a function of them — which is how a site is handed the URL of the API it was started beside. | [src/facets/website/website.specification.ts:96](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L96) |
-| `transform()?` | (`text`) => `string` | Escape hatch: normaliser applied to every compared reading of a result — the head projection and the json-ld among them — before the comparison (CONVENTIONS D6). Does NOT mutate the raw `.text` accessor. Prefer `{{token}}` placeholders in fixtures; this is for what a token cannot name, a meta a FRAMEWORK owns and the page never asked for. | [src/facets/website/website.specification.ts:104](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L104) |
-
-## Type Parameters
-
-| Type Parameter | Default type |
-| ------ | ------ |
-| `Services` *extends* [`ServiceRecord`](ServiceRecord.md) | [`ServiceRecord`](ServiceRecord.md) |

package/docs/reference/variables/anthropic.md

@@ -1,19 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: anthropic
-
-```ts
-const anthropic: object;
-```
-
-Defined in: [src/seams/anthropic/anthropic.ts:55](https://github.com/jterrazz/package-test/blob/main/src/seams/anthropic/anthropic.ts#L55)
-
-Anthropic API intercept helpers.
-
-## Type Declaration
-
-| Name | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ |
-| `error()` | (`status`, `message?`) => [`ContractResponse`](../type-aliases/ContractResponse.md) | Response: return an Anthropic error. | [src/seams/anthropic/anthropic.ts:91](https://github.com/jterrazz/package-test/blob/main/src/seams/anthropic/anthropic.ts#L91) |
-| `messages()` | (`filter?`, `url?`) => [`ContractRequest`](../type-aliases/ContractRequest.md) | Request: match Messages API calls, optionally routed through a custom gateway URL. When used with a JSON fixture file, the data is returned as-is (no wrapping) because Anthropic fixtures are typically already in the Messages API response shape. **Example** `anthropic.messages() anthropic.messages({ system: /classify/ }) anthropic.messages({ user: buildPrompt() }) // string = EXACT equality anthropic.messages({ user: /classify/ }, GATEWAY)` | [src/seams/anthropic/anthropic.ts:68](https://github.com/jterrazz/package-test/blob/main/src/seams/anthropic/anthropic.ts#L68) |
-| `reply()` | (`data`) => [`ContractResponse`](../type-aliases/ContractResponse.md) | Response: wrap data in Anthropic messages format. | [src/seams/anthropic/anthropic.ts:86](https://github.com/jterrazz/package-test/blob/main/src/seams/anthropic/anthropic.ts#L86) |
-| `timeout()` | () => [`ContractResponse`](../type-aliases/ContractResponse.md) | Response: simulate a timeout. | [src/seams/anthropic/anthropic.ts:105](https://github.com/jterrazz/package-test/blob/main/src/seams/anthropic/anthropic.ts#L105) |

package/docs/reference/variables/banner.md

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: banner
-
-```ts
-const banner: LandmarkFactory;
-```
-
-Defined in: [src/model/elements/elements.ts:80](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L80)
-
-The `banner` landmark — the page header.

package/docs/reference/variables/button.md

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: button
-
-```ts
-const button: ElementFactory;
-```
-
-Defined in: [src/model/elements/elements.ts:45](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L45)
-
-A button (or element with the button role), by accessible name.

package/docs/reference/variables/clock.md

@@ -1,16 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: clock
-
-```ts
-const clock: object;
-```
-
-Defined in: [src/model/clock/clock.ts:62](https://github.com/jterrazz/package-test/blob/main/src/model/clock/clock.ts#L62)
-
-## Type Declaration
-
-| Name | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ |
-| `advance()` | (`ms`) => `Promise`\<`void`\> | Move the pinned clock forward by `ms` — and, under [clock.run](#run), fire every callback that came due, awaiting what each of them started. Only a pinned clock moves: called with no clock taken, it says so rather than silently doing nothing to the real one. | [src/model/clock/clock.ts:70](https://github.com/jterrazz/package-test/blob/main/src/model/clock/clock.ts#L70) |
-| `at()` | (`iso`) => `Disposable` | Pin `Date` at `iso` for the current scope. `Date` ONLY: the scheduler stays real, so a subject that awaits, renders or polls keeps running. **Example** `using _ = clock.at('2026-03-04T09:30:00Z'); expect(stampedAt()).toBe('2026-03-04T09:30:00.000Z');` | [src/model/clock/clock.ts:88](https://github.com/jterrazz/package-test/blob/main/src/model/clock/clock.ts#L88) |
-| `run()` | (`iso?`) => `Disposable` | Take the scheduler as well as the calendar: `setTimeout`, `setInterval` and their friends queue instead of firing, and [clock.advance](#advance) is what makes them due. For a subject whose behaviour IS elapsed time — a debounce, a retry backoff, a poll — where waiting for real would be the arbitrary sleep J2 forbids. **Example** `using _ = clock.run('2026-03-04T09:30:00Z'); const pending = retrying(failsTwice); await clock.advance(5_000); await expect(pending).resolves.toBe('ok');` | [src/model/clock/clock.ts:105](https://github.com/jterrazz/package-test/blob/main/src/model/clock/clock.ts#L105) |

package/docs/reference/variables/complementary.md

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: complementary
-
-```ts
-const complementary: LandmarkFactory;
-```
-
-Defined in: [src/model/elements/elements.ts:83](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L83)
-
-The `complementary` landmark — an `<aside>`, a sidebar.

package/docs/reference/variables/component.md

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: component
-
-```ts
-const component: ComponentChain;
-```
-
-Defined in: [src/facets/component/component.specification.ts:21](https://github.com/jterrazz/package-test/blob/main/src/facets/component/component.specification.ts#L21)
-
-Present, typed, and refusing — every setup and the terminal action alike.

package/docs/reference/variables/content.md

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: content
-
-```ts
-const content: ElementFactory;
-```
-
-Defined in: [src/model/elements/elements.ts:57](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L57)
-
-An element containing the given text.

package/docs/reference/variables/contentinfo.md

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: contentinfo
-
-```ts
-const contentinfo: LandmarkFactory;
-```
-
-Defined in: [src/model/elements/elements.ts:86](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L86)
-
-The `contentinfo` landmark — the page footer.

package/docs/reference/variables/dialog.md

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: dialog
-
-```ts
-const dialog: LandmarkFactory;
-```
-
-Defined in: [src/model/elements/elements.ts:127](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L127)
-
-A modal or non-modal `<dialog>`, by accessible name. A closed one is absent.

package/docs/reference/variables/field.md

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: field
-
-```ts
-const field: ElementFactory;
-```
-
-Defined in: [src/model/elements/elements.ts:48](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L48)
-
-A form field, by label.

package/docs/reference/variables/form.md

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: form
-
-```ts
-const form: LandmarkFactory;
-```
-
-Defined in: [src/model/elements/elements.ts:89](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L89)
-
-The `form` landmark — a form carrying an accessible name.

package/docs/reference/variables/heading.md

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Variable: heading
-
-```ts
-const heading: ElementFactory;
-```
-
-Defined in: [src/model/elements/elements.ts:51](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L51)
-
-A heading, by accessible name.