@jterrazz/test 16.1.1 → 17.0.0

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

@@ -1,144 +0,0 @@
-<!-- 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

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

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

@@ -1,156 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: ComponentChain
-
-```ts
-type ComponentChain = object;
-```
-
-Defined in: [src/facets/component/component.types.ts:37](https://github.com/jterrazz/package-test/blob/main/src/facets/component/component.types.ts#L37)
-
-The chain. Every setup returns a new one, so the handle a spec imports never
-carries the previous test's contracts, wrapper or clock.
-
-## Properties
-
-### clock
-
-```ts
-clock: (iso) => ComponentChain;
-```
-
-Defined in: [src/facets/component/component.types.ts:39](https://github.com/jterrazz/package-test/blob/main/src/facets/component/component.types.ts#L39)
-
-Pin the page's `Date` for this render — the clock the component reads.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `iso` | `string` |
-
-#### Returns
-
-`ComponentChain`
-
-***
-
-### intercept
-
-```ts
-intercept: {
-  (contracts): ComponentChain;
-  (request, response): ComponentChain;
-};
-```
-
-Defined in: [src/facets/component/component.types.ts:45](https://github.com/jterrazz/package-test/blob/main/src/facets/component/component.types.ts#L45)
-
-Declare what the network replies — the same contracts, the same queue
-and the same strictness as every other facet (D7), served by msw's
-worker instead of its node interceptor.
-
-#### Call Signature
-
-```ts
-(contracts): ComponentChain;
-```
-
-##### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `contracts` | [`ContractInput`](ContractInput.md) |
-
-##### Returns
-
-`ComponentChain`
-
-#### Call Signature
-
-```ts
-(request, response): ComponentChain;
-```
-
-##### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `request` | [`ContractRequest`](ContractRequest.md) |
-| `response` | \| [`ContractResponse`](ContractResponse.md) \| [`ContractResponder`](ContractResponder.md) |
-
-##### Returns
-
-`ComponentChain`
-
-***
-
-### render
-
-```ts
-render: (subject, scenario?) => Promise<RenderResult>;
-```
-
-Defined in: [src/facets/component/component.types.ts:50](https://github.com/jterrazz/package-test/blob/main/src/facets/component/component.types.ts#L50)
-
-Mount the subject, run the scenario, and capture what the page shows.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `subject` | [`RenderSubject`](RenderSubject.md) |
-| `scenario?` | [`ComponentScenario`](ComponentScenario.md) |
-
-#### Returns
-
-`Promise`\<[`RenderResult`](../interfaces/RenderResult.md)\>
-
-***
-
-### viewport
-
-```ts
-viewport: (size) => ComponentChain;
-```
-
-Defined in: [src/facets/component/component.types.ts:56](https://github.com/jterrazz/package-test/blob/main/src/facets/component/component.types.ts#L56)
-
-The page size THIS render gets — the Given of a component that reads
-`matchMedia` or a container query. The project's size is restored when
-the test ends, so a narrow render never leaks into the next one.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `size` | \{ `height`: `number`; `width`: `number`; \} |
-| `size.height` | `number` |
-| `size.width` | `number` |
-
-#### Returns
-
-`ComponentChain`
-
-***
-
-### wrap
-
-```ts
-wrap: (wrapper) => ComponentChain;
-```
-
-Defined in: [src/facets/component/component.types.ts:62](https://github.com/jterrazz/package-test/blob/main/src/facets/component/component.types.ts#L62)
-
-Wrap every render of this chain — the test-local Given a router stub or
-a `<StrictMode>` is. The project's own `wrap` stays outermost: it is the
-app's frame, and one test does not get to sit outside it.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `wrapper` | (`ui`) => [`ComponentUi`](ComponentUi.md) |
-
-#### Returns
-
-`ComponentChain`

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

@@ -1,20 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: ComponentScenario
-
-```ts
-type ComponentScenario = (visitor) => Promise<void>;
-```
-
-Defined in: [src/facets/component/component.types.ts:24](https://github.com/jterrazz/package-test/blob/main/src/facets/component/component.types.ts#L24)
-
-The behaviour of a render; assertions stay in the Then, on the result (W1).
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `visitor` | [`ComponentVisitor`](ComponentVisitor.md) |
-
-## Returns
-
-`Promise`\<`void`\>

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

@@ -1,47 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: ComponentUi
-
-```ts
-type ComponentUi = 
-  | ReactElement
-  | string
-  | number
-  | bigint
-  | Iterable<ReactNode>
-  | ReactPortal
-  | boolean
-  | null
-  | undefined
-  | DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_REACT_NODES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_REACT_NODES]
-| Promise<AwaitedReactNode>;
-```
-
-Defined in: node\_modules/@types/react/index.d.ts:436
-
-Represents all of the things React can render.
-
-Where ReactElement only represents JSX, `ReactNode` represents everything that can be rendered.
-
-## See
-
-[React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/reference/reactnode/)
-
-## Examples
-
-```tsx
-// Typing children
-type Props = { children: ReactNode }
-
-const Component = ({ children }: Props) => <div>{children}</div>
-
-<Component>hello</Component>
-```
-
-```tsx
-// Typing a custom element
-type Props = { customElement: ReactNode }
-
-const Component = ({ customElement }: Props) => <div>{customElement}</div>
-
-<Component customElement={<div>hello</div>} />
-```

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

@@ -1,10 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: ComponentVisitor
-
-```ts
-type ComponentVisitor = ReturnType<typeof componentVerbs>;
-```
-
-Defined in: [src/facets/component/component.types.ts:21](https://github.com/jterrazz/package-test/blob/main/src/facets/component/component.types.ts#L21)
-
-The interaction vocabulary a render scenario is handed — the When.

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

@@ -1,113 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: ContainerPort
-
-```ts
-type ContainerPort = object;
-```
-
-Defined in: [src/model/ports/container.port.ts:5](https://github.com/jterrazz/package-test/blob/main/src/model/ports/container.port.ts#L5)
-
-Abstract container interface.
-Represents a running service (database, cache, etc.)
-
-## Properties
-
-### getConnectionString
-
-```ts
-getConnectionString: () => string;
-```
-
-Defined in: [src/model/ports/container.port.ts:19](https://github.com/jterrazz/package-test/blob/main/src/model/ports/container.port.ts#L19)
-
-Get a full connection string for this service.
-
-#### Returns
-
-`string`
-
-***
-
-### getHost
-
-```ts
-getHost: () => string;
-```
-
-Defined in: [src/model/ports/container.port.ts:16](https://github.com/jterrazz/package-test/blob/main/src/model/ports/container.port.ts#L16)
-
-Get the host to connect to.
-
-#### Returns
-
-`string`
-
-***
-
-### getLogs
-
-```ts
-getLogs: () => Promise<string>;
-```
-
-Defined in: [src/model/ports/container.port.ts:22](https://github.com/jterrazz/package-test/blob/main/src/model/ports/container.port.ts#L22)
-
-Get container logs (stdout + stderr).
-
-#### Returns
-
-`Promise`\<`string`\>
-
-***
-
-### getMappedPort
-
-```ts
-getMappedPort: (containerPort) => number;
-```
-
-Defined in: [src/model/ports/container.port.ts:13](https://github.com/jterrazz/package-test/blob/main/src/model/ports/container.port.ts#L13)
-
-Get the mapped host port for a container port.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `containerPort` | `number` |
-
-#### Returns
-
-`number`
-
-***
-
-### start
-
-```ts
-start: () => Promise<void>;
-```
-
-Defined in: [src/model/ports/container.port.ts:7](https://github.com/jterrazz/package-test/blob/main/src/model/ports/container.port.ts#L7)
-
-Start the container and wait until ready.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-***
-
-### stop
-
-```ts
-stop: () => Promise<void>;
-```
-
-Defined in: [src/model/ports/container.port.ts:10](https://github.com/jterrazz/package-test/blob/main/src/model/ports/container.port.ts#L10)
-
-Stop and remove the container.
-
-#### Returns
-
-`Promise`\<`void`\>

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

@@ -1,68 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: Contract
-
-```ts
-type Contract = object;
-```
-
-Defined in: [src/model/contracts/contract.ts:10](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L10)
-
-A declared external interaction: what to match (`request`) and what to reply
-(`response`), together in one named artifact. Contracts live in TypeScript
-files under `contracts/` next to the tests that use them, so the business
-payload (prompts, JSON responses) is visible at a glance while the real HTTP
-call stays mocked underneath.
-
-## Properties
-
-### request
-
-```ts
-request: ContractRequest;
-```
-
-Defined in: [src/model/contracts/contract.ts:12](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L12)
-
-Which outgoing call this contract speaks for.
-
-***
-
-### required?
-
-```ts
-optional required?: boolean;
-```
-
-Defined in: [src/model/contracts/contract.ts:30](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L30)
-
-When true, the chain FAILS unless the contract was actually requested:
-at least once, or exactly `times` times when `times` is set. Turns a
-silently-unused declaration into a spec failure.
-
-***
-
-### response
-
-```ts
-response: ContractResponseValue;
-```
-
-Defined in: [src/model/contracts/contract.ts:18](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L18)
-
-The reply — a fixed [ContractResponse](ContractResponse.md), or a function
-`(request) => ContractResponse` evaluated per served request when the
-response must derive from the incoming payload.
-
-***
-
-### times?
-
-```ts
-optional times?: number;
-```
-
-Defined in: [src/model/contracts/contract.ts:24](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L24)
-
-How many times this contract may serve. Omitted = unlimited (a
-re-render or a retry replays it). `n` = exhausted after n serves, so an
-ordered sequence is a finite contract followed by an unlimited tail.