@jterrazz/test 15.3.0 → 16.1.0

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

@@ -0,0 +1,132 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: BrowserPage
+
+```ts
+type BrowserPage = object;
+```
+
+Defined in: [src/model/ports/browser.port.ts:206](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L206)
+
+The rendered page captured by a browser visit — the FINAL state when a
+scenario ran. Extraction happens in-page (the browser IS the HTML
+parser); interpretation of the raw elements belongs to the model.
+
+## Properties
+
+### consoleMessages
+
+```ts
+consoleMessages: BrowserConsoleMessage[];
+```
+
+Defined in: [src/model/ports/browser.port.ts:208](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L208)
+
+Console messages emitted while loading and interacting, in order.
+
+***
+
+### html
+
+```ts
+html: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:210](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L210)
+
+Serialized DOM after rendering (`document.documentElement.outerHTML`).
+
+***
+
+### jsonLdBlocks
+
+```ts
+jsonLdBlocks: string[];
+```
+
+Defined in: [src/model/ports/browser.port.ts:212](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L212)
+
+Raw text content of every `application/ld+json` script, in DOM order.
+
+***
+
+### links
+
+```ts
+links: BrowserLinkElement[];
+```
+
+Defined in: [src/model/ports/browser.port.ts:214](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L214)
+
+`<link>` elements of the head, in DOM order.
+
+***
+
+### metas
+
+```ts
+metas: BrowserMetaElement[];
+```
+
+Defined in: [src/model/ports/browser.port.ts:216](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L216)
+
+`<meta>` elements of the head, in DOM order.
+
+***
+
+### status
+
+```ts
+status: number;
+```
+
+Defined in: [src/model/ports/browser.port.ts:218](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L218)
+
+HTTP status of the main document response (0 when unavailable).
+
+***
+
+### text
+
+```ts
+text: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:220](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L220)
+
+Rendered `document.body.innerText`.
+
+***
+
+### title
+
+```ts
+title: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:224](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L224)
+
+`document.title` after rendering.
+
+***
+
+### tree
+
+```ts
+tree: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:222](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L222)
+
+The ARIA snapshot of the rendered `<body>` — the outline a golden pins.
+
+***
+
+### url
+
+```ts
+url: string;
+```
+
+Defined in: [src/model/ports/browser.port.ts:226](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L226)
+
+Final URL after redirects and scenario navigation.

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

@@ -0,0 +1,51 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: BrowserPort
+
+```ts
+type BrowserPort = object;
+```
+
+Defined in: [src/model/ports/browser.port.ts:234](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L234)
+
+Abstract browser interface for the website specification runner.
+One implementation lives in `integrations/playwright/` — a single shared
+browser instance per runner; each `open()` gets a fresh, isolated context.
+
+## Properties
+
+### close
+
+```ts
+close: () => Promise<void>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:236](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L236)
+
+Close the shared browser instance (idempotent).
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### open
+
+```ts
+open: (url, options) => Promise<BrowserPage>;
+```
+
+Defined in: [src/model/ports/browser.port.ts:238](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L238)
+
+Load `url` in a fresh context, run the scenario, capture the final page.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `url` | `string` |
+| `options` | [`BrowserOpenOptions`](BrowserOpenOptions.md) |
+
+#### Returns
+
+`Promise`\<[`BrowserPage`](BrowserPage.md)\>

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

@@ -0,0 +1,11 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: CliEnv
+
+```ts
+type CliEnv = Record<string, null | string>;
+```
+
+Defined in: [src/model/ports/cli.port.ts:30](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L30)
+
+Extra environment variables to set for the child process.
+Values are merged on top of process.env. A `null` value unsets the variable.

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

@@ -0,0 +1,80 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: CliHandle\<DatabaseKey\>
+
+```ts
+type CliHandle<DatabaseKey> = object;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:84](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L84)
+
+The record returned by startCli \| specification.cli. Destructure
+with the canonical names (CONVENTIONS A3):
+
+    const { cli, cleanup, docker } = await specification.cli(…);
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `DatabaseKey` *extends* `string` | `string` |
+
+## Properties
+
+### cleanup
+
+```ts
+cleanup: () => Promise<void>;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:86](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L86)
+
+Stop all infrastructure started by this specification.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### cli
+
+```ts
+cli: CliSpecification<DatabaseKey>;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:87](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L87)
+
+***
+
+### docker
+
+```ts
+docker: (containerId) => ContainerAccessor;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:92](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L92)
+
+Read a running container by id — returns a [ContainerAccessor](../interfaces/ContainerAccessor.md)
+usable with `await expect(...).toBeRunning()` and read accessors.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `containerId` | `string` |
+
+#### Returns
+
+[`ContainerAccessor`](../interfaces/ContainerAccessor.md)
+
+***
+
+### orchestrator
+
+```ts
+orchestrator: null | Orchestrator;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:94](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L94)
+
+The orchestrator managing the test infrastructure lifecycle.

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

@@ -0,0 +1,36 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: CliInput
+
+```ts
+type CliInput = object;
+```
+
+Defined in: [src/model/ports/cli.port.ts:41](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L41)
+
+What one invocation is handed beyond its arguments — the two per-run inputs a
+spec document may state. Both are absent by default: the child gets an
+immediately-closed stdin (never a TTY) and the adapter's own timeout.
+
+## Properties
+
+### stdin?
+
+```ts
+optional stdin?: string;
+```
+
+Defined in: [src/model/ports/cli.port.ts:43](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L43)
+
+Written to the child's stdin, which is then closed.
+
+***
+
+### timeout?
+
+```ts
+optional timeout?: number;
+```
+
+Defined in: [src/model/ports/cli.port.ts:45](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L45)
+
+Milliseconds after which the run is killed (exit code 124).

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

@@ -0,0 +1,46 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: CliOutput
+
+```ts
+type CliOutput = object;
+```
+
+Defined in: [src/model/ports/cli.port.ts:4](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L4)
+
+Raw output from a command execution, including exit code and captured output streams.
+
+## Properties
+
+### exitCode
+
+```ts
+exitCode: number;
+```
+
+Defined in: [src/model/ports/cli.port.ts:6](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L6)
+
+Process exit code (0 = success).
+
+***
+
+### stderr
+
+```ts
+stderr: string;
+```
+
+Defined in: [src/model/ports/cli.port.ts:10](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L10)
+
+Captured standard error.
+
+***
+
+### stdout
+
+```ts
+stdout: string;
+```
+
+Defined in: [src/model/ports/cli.port.ts:8](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L8)
+
+Captured standard output.

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

@@ -0,0 +1,58 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: CliPort
+
+```ts
+type CliPort = object;
+```
+
+Defined in: [src/model/ports/cli.port.ts:48](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L48)
+
+## Properties
+
+### exec
+
+```ts
+exec: (args, cwd, env?, input?) => Promise<CliOutput>;
+```
+
+Defined in: [src/model/ports/cli.port.ts:50](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L50)
+
+Execute a command with the given arguments in the given working directory.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `args` | `string` |
+| `cwd` | `string` |
+| `env?` | [`CliEnv`](CliEnv.md) |
+| `input?` | [`CliInput`](CliInput.md) |
+
+#### Returns
+
+`Promise`\<[`CliOutput`](CliOutput.md)\>
+
+***
+
+### watch
+
+```ts
+watch: (args, cwd, options, env?) => Promise<CliOutput>;
+```
+
+Defined in: [src/model/ports/cli.port.ts:53](https://github.com/jterrazz/package-test/blob/main/src/model/ports/cli.port.ts#L53)
+
+Run a long-running process and wait for a pattern or timeout.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `args` | `string` |
+| `cwd` | `string` |
+| `options` | [`ExecOptions`](ExecOptions.md) |
+| `env?` | [`CliEnv`](CliEnv.md) |
+
+#### Returns
+
+`Promise`\<[`CliOutput`](CliOutput.md)\>

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

@@ -0,0 +1,144 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: CliSpecification\<DatabaseKey\>
+
+```ts
+type CliSpecification<DatabaseKey> = object;
+```
+
+Defined in: [src/model/chain/builder.ts:264](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L264)
+
+The `cli` facet — command chain entry handed out by `specification.cli()`.
+Setup methods chain; `.exec()` is the single terminal action (CONVENTIONS
+B2) — `{ waitFor?, timeout? }` covers long-running processes.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `DatabaseKey` *extends* `string` | `string` |
+
+## Properties
+
+### env
+
+```ts
+env: (env) => CliSpecification<DatabaseKey>;
+```
+
+Defined in: [src/model/chain/builder.ts:266](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L266)
+
+Set environment variables on the child process. `$WORKDIR` expands; `null` unsets.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `env` | [`CliEnv`](CliEnv.md) |
+
+#### Returns
+
+`CliSpecification`\<`DatabaseKey`\>
+
+***
+
+### exec
+
+```ts
+exec: (args?, options?) => Promise<CliResult>;
+```
+
+Defined in: [src/model/chain/builder.ts:285](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L285)
+
+Execute the command (or sequence of commands) and resolve with the
+result. Called with no arguments (`cli.exec()`), the binary runs bare —
+no CLI arguments. With `{ waitFor, timeout }`, the process is
+long-running: it resolves when the pattern appears and is killed at the
+timeout.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `args?` | `string` \| `string`[] |
+| `options?` | [`ExecOptions`](ExecOptions.md) |
+
+#### Returns
+
+`Promise`\<[`CliResult`](../interfaces/CliResult.md)\>
+
+***
+
+### fixture
+
+```ts
+fixture: (path) => CliSpecification<DatabaseKey>;
+```
+
+Defined in: [src/model/chain/builder.ts:274](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L274)
+
+Copy a fixture into the working directory before execution. The path is
+feature-local (`<test-dir>/fixtures/<path>`) or, with a `$FIXTURES/`
+prefix, from the shared pool at `<specs-root>/fixtures/`. A trailing
+slash spreads a directory's contents into the cwd; without one a
+directory (or file) is copied under its own name. Chained calls layer.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+#### Returns
+
+`CliSpecification`\<`DatabaseKey`\>
+
+***
+
+### run
+
+```ts
+run: (file, options?) => Promise<CliResult>;
+```
+
+Defined in: [src/model/chain/builder.ts:293](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L293)
+
+Run a `<case>.spec.yaml` document — its ground (fixtures, env sets,
+servers) and every run, each asserted — and resolve with the LAST run's
+result, so a `.test.ts` can add an assertion the document cannot express
+(a directory golden, a grep). The path is relative to the test file's own
+directory, where the document lives.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `file` | `string` |
+| `options?` | [`LiterateRunFlags`](LiterateRunFlags.md) |
+
+#### Returns
+
+`Promise`\<[`CliResult`](../interfaces/CliResult.md)\>
+
+***
+
+### seed
+
+```ts
+seed: (file, options?) => CliSpecification<DatabaseKey>;
+```
+
+Defined in: [src/model/chain/builder.ts:276](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L276)
+
+Queue a SQL seed file from `_seeds/` to run against a database before the action.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `file` | `string` |
+| `options?` | \{ `database?`: `DatabaseKey`; \} |
+| `options.database?` | `DatabaseKey` |
+
+#### Returns
+
+`CliSpecification`\<`DatabaseKey`\>

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

@@ -0,0 +1,134 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: CliSpecificationOptions\<Services\>
+
+```ts
+type CliSpecificationOptions<Services> = object;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:23](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L23)
+
+Options for startCli \| specification.cli.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Services` *extends* [`ServiceRecord`](ServiceRecord.md) | [`ServiceRecord`](ServiceRecord.md) |
+
+## Properties
+
+### defaults?
+
+```ts
+optional defaults?: CliEnv;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:39](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L39)
+
+Environment applied to EVERY run of this binary — the variables the
+product needs to be deterministic at all (`TZ`, `NO_COLOR`, `LANG`,
+a config home under the spec's own workdir). Stated once per app
+instead of repeated on every chain and in every document; a chained
+`.env()` and a document's `env:` both win over it.
+
+***
+
+### docker?
+
+```ts
+optional docker?: DockerSpecConfig;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:31](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L31)
+
+Opt-in Docker awareness. When set, every spec generates a unique
+test-run id, injects it into the child process env under `envVar`,
+and exposes `.container(name)` accessors on the result that lazily
+query Docker. Always declare results with `await using` so leaked
+containers get force-removed at scope exit (CONVENTIONS B5).
+
+***
+
+### env?
+
+```ts
+optional env?: Record<string, CliEnv>;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:46](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L46)
+
+Named environment SETS for `<case>.spec.yaml` documents. An `env:` entry
+`frozen` applies the whole `frozen` record; `$WORKDIR` expands and `null`
+unsets, exactly as in `.env()`. Declared once per app so a document
+states WHICH ground it stands on, not how to build it.
+
+***
+
+### root?
+
+```ts
+optional root?: string;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:61](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L61)
+
+Project-root override (CONVENTIONS A9) — the single meaning of `root`:
+it anchors the local-bin resolution of the tested binary, in place of
+the walk to the nearest `package.json`. It is NOT a fixtures root;
+`.fixture()` resolves feature-local or `$FIXTURES/` paths on its own.
+
+***
+
+### serve?
+
+```ts
+optional serve?: Record<string, LiterateServeRegistration>;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:54](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L54)
+
+Named servers a `<case>.spec.yaml` document may start (`serve: [mcp]`, or
+`- mcp: { KEY: value }` to add env to that one). Each entry names the
+shell `command`, the `ready` regex whose capture group holds the port the
+server announces, the `url(port)` builder, and the `env` variable that
+URL is bound to in every run's child.
+
+***
+
+### services?
+
+```ts
+optional services?: Services;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:68](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L68)
+
+Named infrastructure record started via testcontainers. Connection
+URLs are injected automatically into the child env: `<KEY>_URL` per
+service, plus `DATABASE_URL` / `REDIS_URL` when unambiguous
+(CONVENTIONS B6). `.env()` overrides.
+
+***
+
+### transform?
+
+```ts
+optional transform?: (text) => string;
+```
+
+Defined in: [src/facets/cli/cli.specification.ts:75](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.specification.ts#L75)
+
+Escape hatch: normaliser applied to result.stdout / result.stderr
+before every comparison, AFTER the default ANSI strip (CONVENTIONS
+D6). Does NOT mutate the raw `.text` accessor. Prefer `{{token}}`
+placeholders in fixtures.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `text` | `string` |
+
+#### Returns
+
+`string`