@jterrazz/test 16.0.0 → 16.1.0

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

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

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

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

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

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

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

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

@@ -0,0 +1,13 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ContractInput
+
+```ts
+type ContractInput = 
+  | Contract
+  | Contract[]
+  | Contracts;
+```
+
+Defined in: [src/model/contracts/contract.ts:50](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L50)
+
+Any accepted contract input: one, a list, or a composite.

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

@@ -0,0 +1,95 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ContractRequest
+
+```ts
+type ContractRequest = object;
+```
+
+Defined in: [src/model/contracts/types.ts:26](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L26)
+
+The request half of a contract: which outgoing call it speaks for.
+
+`url` is either an absolute URL (string or RegExp), or a PATH FORM starting
+with `/` (`/articles/{{uuid}}`) which matches any origin — the shape a
+website/mobile app's own backend calls take. `{{token}}` segments compare
+structurally, declared query params are a subset of the observed ones.
+
+## Properties
+
+### adapter
+
+```ts
+adapter: string;
+```
+
+Defined in: [src/model/contracts/types.ts:28](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L28)
+
+Adapter name — `http` | `openai` | `anthropic`.
+
+***
+
+### match?
+
+```ts
+optional match?: (request) => boolean;
+```
+
+Defined in: [src/model/contracts/types.ts:34](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L34)
+
+Optional request matcher — the contract only fires if this returns true.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `request` | [`MatchableRequest`](MatchableRequest.md) |
+
+#### Returns
+
+`boolean`
+
+***
+
+### method
+
+```ts
+method: string;
+```
+
+Defined in: [src/model/contracts/types.ts:30](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L30)
+
+HTTP method to match. `*` matches any method.
+
+***
+
+### url
+
+```ts
+url: RegExp | string;
+```
+
+Defined in: [src/model/contracts/types.ts:32](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L32)
+
+Absolute URL (string | RegExp) or an any-origin path form (`/articles/{{uuid}}`).
+
+***
+
+### wrap
+
+```ts
+wrap: (data) => ContractResponse;
+```
+
+Defined in: [src/model/contracts/types.ts:36](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L36)
+
+Transform raw data into a provider-specific response envelope.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `data` | `unknown` |
+
+#### Returns
+
+[`ContractResponse`](ContractResponse.md)

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

@@ -0,0 +1,23 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ContractResponder
+
+```ts
+type ContractResponder = (request) => ContractResponse;
+```
+
+Defined in: [src/model/contracts/types.ts:105](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L105)
+
+A dynamic response: computed from the observed request at the moment the
+contract is served, rather than fixed ahead of time. Handed the same
+[MatchableRequest](MatchableRequest.md) the request half matched on, so the reply can echo
+or derive from the body/headers/url.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `request` | [`MatchableRequest`](MatchableRequest.md) |
+
+## Returns
+
+[`ContractResponse`](ContractResponse.md)

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

@@ -0,0 +1,78 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ContractResponse
+
+```ts
+type ContractResponse = object;
+```
+
+Defined in: [src/model/contracts/types.ts:42](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L42)
+
+The response half of a contract: what to reply when the request matches.
+
+## Properties
+
+### body
+
+```ts
+body: unknown;
+```
+
+Defined in: [src/model/contracts/types.ts:50](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L50)
+
+Response body — an object is JSON, a string is text, `null`/`undefined`
+is empty, and a [StreamBody](StreamBody.md) (built by `http.stream()` /
+`http.sse()`) arrives in pieces.
+
+***
+
+### delay?
+
+```ts
+optional delay?: number;
+```
+
+Defined in: [src/model/contracts/types.ts:54](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L54)
+
+Delay in ms before responding (for timeout testing).
+
+***
+
+### headers?
+
+```ts
+optional headers?: Record<string, string>;
+```
+
+Defined in: [src/model/contracts/types.ts:52](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L52)
+
+Response headers.
+
+***
+
+### status?
+
+```ts
+optional status?: number;
+```
+
+Defined in: [src/model/contracts/types.ts:44](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L44)
+
+HTTP status code (default: 200).
+
+***
+
+### transport?
+
+```ts
+optional transport?: "network-error";
+```
+
+Defined in: [src/model/contracts/types.ts:64](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L64)
+
+A transport failure instead of a reply: the request never reached a
+server, so `fetch` rejects. `status`, `body` and `headers` say nothing
+here — there is no response to carry them.
+
+The one thing a status code cannot express. A component's "the server did
+not answer, check that it is running" branch is reached by a rejected
+`fetch`, and a 503 stand-in tests the other branch entirely.

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

@@ -0,0 +1,13 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ContractResponseValue
+
+```ts
+type ContractResponseValue = 
+  | ContractResponder
+  | ContractResponse;
+```
+
+Defined in: [src/model/contracts/types.ts:111](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L111)
+
+What a contract replies with: either a fixed [ContractResponse](ContractResponse.md) or a
+[ContractResponder](ContractResponder.md) evaluated per served request.

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

@@ -0,0 +1,48 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: Contracts
+
+```ts
+type Contracts = object;
+```
+
+Defined in: [src/model/contracts/contract.ts:37](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L37)
+
+A composite of contracts — the unit tests import. Flat, ordered, immutable;
+`.with()` derives a variant without touching the original.
+
+## Properties
+
+### contracts
+
+```ts
+readonly contracts: readonly Contract[];
+```
+
+Defined in: [src/model/contracts/contract.ts:39](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L39)
+
+The flattened contracts, in selection order.
+
+***
+
+### with
+
+```ts
+with: (...overrides) => Contracts;
+```
+
+Defined in: [src/model/contracts/contract.ts:46](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L46)
+
+Derive a new composite: every base contract sharing a route with an
+override is REPLACED, and the overrides are PREPENDED — so a
+more-specific override wins first-match selection over a generic base
+route it does not replace.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| ...`overrides` | ([`Contract`](Contract.md) \| [`Contract`](Contract.md)[] \| `Contracts`)[] |
+
+#### Returns
+
+`Contracts`