@jterrazz/test 15.3.0 → 16.1.0

package/docs/reference/interfaces/CallResult.md

@@ -0,0 +1,160 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Interface: CallResult\<Returned\>
+
+Defined in: [src/facets/integration/integration.result.ts:60](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.result.ts#L60)
+
+The result of an in-process call — the integration facet's whole surface.
+
+Two readings, never both: `value` is what the call RETURNED, `error` is
+what it THREW. A module that refuses is specified the same way a module
+that answers is, and neither needs a `try`/`catch` in the test — a shape
+that costs a refusal spec three times the size of the happy one, and that
+quietly passes when nothing throws at all.
+
+Both are the package's ordinary accessors, so the golden mechanism reaches
+them, and `Returned` is what `.call<T>()` returned — `result.value.value` is
+that type, not `unknown`, so a one-field reading needs no golden file: `toMatch('<name>.json'|'<name>.txt')`, the `{{token}}` grammar,
+`{ frozen }` and `TEST_UPDATE=1` all work here exactly as on an HTTP
+response or a command's stdout.
+
+## Extends
+
+- [`BaseResult`](BaseResult.md)
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Returned` | `unknown` |
+
+## Accessors
+
+### error
+
+#### Get Signature
+
+```ts
+get error(): TextAccessor;
+```
+
+Defined in: [src/facets/integration/integration.result.ts:78](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.result.ts#L78)
+
+What the call THREW, as text — the message of an `Error`, the value
+itself when something else was thrown, and empty when it returned.
+
+Empty rather than absent on purpose: `await expect(result.error).toBeEmpty()`
+is how a spec says "and it did not refuse" — awaited, because the
+matcher answers a promise on every subject it takes, and a dropped one
+passes the test while the failure surfaces as an unhandled rejection
+(D2 refuses the bare form).
+
+##### Returns
+
+[`TextAccessor`](TextAccessor.md)
+
+***
+
+### value
+
+#### Get Signature
+
+```ts
+get value(): CallValue<Returned>;
+```
+
+Defined in: [src/facets/integration/integration.result.ts:96](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.result.ts#L96)
+
+What the call RETURNED. A string reads as a stream (`<name>.txt`),
+anything else as JSON (`<name>.json`) — the same two subjects every
+other facet's results are built from, chosen on the value in hand and
+typed by CallValue, which answers for the three ways a type can
+relate to `string`.
+
+A call that threw has no value to choose an accessor on, so `value` is
+the JSON reading of `null` whatever the declared type promises: what a
+refusal produced is [CallResult.error](#error), and that is where a spec
+reads it.
+
+##### Returns
+
+`CallValue`\<`Returned`\>
+
+## Methods
+
+### directory()
+
+```ts
+directory(path?): DirectoryAccessor;
+```
+
+Defined in: [src/model/result/result.ts:55](https://github.com/jterrazz/package-test/blob/main/src/model/result/result.ts#L55)
+
+Access a directory (relative to the working directory) for snapshot assertions.
+
+#### Parameters
+
+| Parameter | Type | Default value |
+| ------ | ------ | ------ |
+| `path` | `string` | `'.'` |
+
+#### Returns
+
+[`DirectoryAccessor`](DirectoryAccessor.md)
+
+#### Inherited from
+
+[`BaseResult`](BaseResult.md).[`directory`](BaseResult.md#directory)
+
+***
+
+### file()
+
+```ts
+file(path): FileAccessor;
+```
+
+Defined in: [src/model/result/result.ts:61](https://github.com/jterrazz/package-test/blob/main/src/model/result/result.ts#L61)
+
+Access a single file (relative to the working directory) for content assertions.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+#### Returns
+
+[`FileAccessor`](../type-aliases/FileAccessor.md)
+
+#### Inherited from
+
+[`BaseResult`](BaseResult.md).[`file`](BaseResult.md#file)
+
+***
+
+### table()
+
+```ts
+table(tableName, options?): TableAccessor;
+```
+
+Defined in: [src/model/result/result.ts:86](https://github.com/jterrazz/package-test/blob/main/src/model/result/result.ts#L86)
+
+Access a database table for row-level assertions via expect() matchers.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `tableName` | `string` |
+| `options?` | \{ `database?`: `string`; \} |
+| `options.database?` | `string` |
+
+#### Returns
+
+[`TableAccessor`](TableAccessor.md)
+
+#### Inherited from
+
+[`BaseResult`](BaseResult.md).[`table`](BaseResult.md#table)

package/docs/reference/interfaces/CaptureScope.md

@@ -0,0 +1,82 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Interface: CaptureScope
+
+Defined in: [src/model/matching/match.ts:221](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L221)
+
+Named captures recorded by `match.ref()` / `{{type#ref}}` placeholders.
+One scope lives on each spec result — every assertion chained off the same
+result shares it, and a new chain starts fresh.
+
+## Properties
+
+### workdir?
+
+```ts
+optional workdir?: string;
+```
+
+Defined in: [src/model/matching/match.ts:227](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L227)
+
+The exact working directory of the current spec, when the framework
+knows it (cli mode). Drives the `{{workdir}}` token / `match.workdir()`.
+
+## Methods
+
+### get()
+
+```ts
+get(name): unknown;
+```
+
+Defined in: [src/model/matching/match.ts:233](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L233)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `name` | `string` |
+
+#### Returns
+
+`unknown`
+
+***
+
+### has()
+
+```ts
+has(name): boolean;
+```
+
+Defined in: [src/model/matching/match.ts:237](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L237)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `name` | `string` |
+
+#### Returns
+
+`boolean`
+
+***
+
+### set()
+
+```ts
+set(name, value): void;
+```
+
+Defined in: [src/model/matching/match.ts:241](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L241)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `name` | `string` |
+| `value` | `unknown` |
+
+#### Returns
+
+`void`

package/docs/reference/interfaces/CliResult.md

@@ -0,0 +1,253 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Interface: CliResult
+
+Defined in: [src/facets/cli/cli.result.ts:33](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.result.ts#L33)
+
+Result from a command action (`.exec()`).
+
+When the runner was configured with a `docker` option, the result also
+exposes container accessors and participates in `Symbol.asyncDispose`
+cleanup. The Docker shell-outs are **lazy**: a test that never calls
+`.container(...)` never queries the Docker daemon, so command-only tests
+pay zero Docker cost even when the runner is Docker-aware.
+
+Dispose always runs one final label-filtered `docker ps` to catch
+containers that were spawned during `.exec` but never asserted on —
+tests still get leak-free cleanup even if they forget to reach into
+a container.
+
+## Extends
+
+- [`BaseResult`](BaseResult.md)
+
+## Accessors
+
+### containerIds
+
+#### Get Signature
+
+```ts
+get containerIds(): string[];
+```
+
+Defined in: [src/facets/cli/cli.result.ts:117](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.result.ts#L117)
+
+All captured container IDs. Triggers the same lazy query as `container()`.
+
+##### Returns
+
+`string`[]
+
+***
+
+### exitCode
+
+#### Get Signature
+
+```ts
+get exitCode(): number;
+```
+
+Defined in: [src/facets/cli/cli.result.ts:57](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.result.ts#L57)
+
+The process exit code.
+
+##### Returns
+
+`number`
+
+***
+
+### filesystem
+
+#### Get Signature
+
+```ts
+get filesystem(): FilesystemAccessor;
+```
+
+Defined in: [src/facets/cli/cli.result.ts:88](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.result.ts#L88)
+
+Accessor for the temporary working directory the command ran in.
+
+##### Returns
+
+[`FilesystemAccessor`](FilesystemAccessor.md)
+
+***
+
+### json
+
+#### Get Signature
+
+```ts
+get json(): JsonAccessor;
+```
+
+Defined in: [src/facets/cli/cli.result.ts:78](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.result.ts#L78)
+
+Accessor for parsing stdout as JSON and asserting against JSON fixtures.
+
+##### Returns
+
+[`JsonAccessor`](JsonAccessor.md)
+
+***
+
+### stderr
+
+#### Get Signature
+
+```ts
+get stderr(): TextAccessor;
+```
+
+Defined in: [src/facets/cli/cli.result.ts:70](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.result.ts#L70)
+
+Accessor for the captured standard error with file-based assertions.
+
+##### Returns
+
+[`TextAccessor`](TextAccessor.md)
+
+***
+
+### stdout
+
+#### Get Signature
+
+```ts
+get stdout(): TextAccessor;
+```
+
+Defined in: [src/facets/cli/cli.result.ts:62](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.result.ts#L62)
+
+Accessor for the captured standard output with file-based assertions.
+
+##### Returns
+
+[`TextAccessor`](TextAccessor.md)
+
+## Methods
+
+### \[asyncDispose\]()
+
+```ts
+asyncDispose: Promise<void>;
+```
+
+Defined in: [src/facets/cli/cli.result.ts:123](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.result.ts#L123)
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### container()
+
+```ts
+container(name): ContainerAccessor;
+```
+
+Defined in: [src/facets/cli/cli.result.ts:106](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/cli.result.ts#L106)
+
+Look up a container the command spawned during this run by the value of
+its name-label (as declared in the `docker.nameLabel` of the
+`specification.cli()` options).
+First access triggers a one-shot `docker ps` + `docker inspect`
+query and caches the result for the rest of the result's lifetime.
+Tests that don't call this never touch Docker.
+
+Returns an accessor with `.exists === false` when no container
+carries that name — callers can still assert absence without a try.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `name` | `string` |
+
+#### Returns
+
+[`ContainerAccessor`](ContainerAccessor.md)
+
+***
+
+### directory()
+
+```ts
+directory(path?): DirectoryAccessor;
+```
+
+Defined in: [src/model/result/result.ts:55](https://github.com/jterrazz/package-test/blob/main/src/model/result/result.ts#L55)
+
+Access a directory (relative to the working directory) for snapshot assertions.
+
+#### Parameters
+
+| Parameter | Type | Default value |
+| ------ | ------ | ------ |
+| `path` | `string` | `'.'` |
+
+#### Returns
+
+[`DirectoryAccessor`](DirectoryAccessor.md)
+
+#### Inherited from
+
+[`BaseResult`](BaseResult.md).[`directory`](BaseResult.md#directory)
+
+***
+
+### file()
+
+```ts
+file(path): FileAccessor;
+```
+
+Defined in: [src/model/result/result.ts:61](https://github.com/jterrazz/package-test/blob/main/src/model/result/result.ts#L61)
+
+Access a single file (relative to the working directory) for content assertions.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+#### Returns
+
+[`FileAccessor`](../type-aliases/FileAccessor.md)
+
+#### Inherited from
+
+[`BaseResult`](BaseResult.md).[`file`](BaseResult.md#file)
+
+***
+
+### table()
+
+```ts
+table(tableName, options?): TableAccessor;
+```
+
+Defined in: [src/model/result/result.ts:86](https://github.com/jterrazz/package-test/blob/main/src/model/result/result.ts#L86)
+
+Access a database table for row-level assertions via expect() matchers.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `tableName` | `string` |
+| `options?` | \{ `database?`: `string`; \} |
+| `options.database?` | `string` |
+
+#### Returns
+
+[`TableAccessor`](TableAccessor.md)
+
+#### Inherited from
+
+[`BaseResult`](BaseResult.md).[`table`](BaseResult.md#table)

package/docs/reference/interfaces/ContainerAccessor.md

@@ -0,0 +1,166 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Interface: ContainerAccessor
+
+Defined in: [src/seams/docker/container-accessor.ts:32](https://github.com/jterrazz/package-test/blob/main/src/seams/docker/container-accessor.ts#L32)
+
+Assertion accessor for a single Docker container captured by the docker()
+spec mode. Mirrors the shape of [CliResult](CliResult.md) so tests use the same
+vocabulary (`stdout.toContain`, `file(...).content`, etc.) regardless
+of where output came from.
+
+Sync state (`exists`, `running`, `status`) is derived from the `docker
+inspect` payload captured at result-construction time. Logs are fetched
+lazily on first access to `stdout`/`stderr`.
+
+## Properties
+
+### exists
+
+```ts
+readonly exists: boolean;
+```
+
+Defined in: [src/seams/docker/container-accessor.ts:35](https://github.com/jterrazz/package-test/blob/main/src/seams/docker/container-accessor.ts#L35)
+
+***
+
+### running
+
+```ts
+readonly running: boolean;
+```
+
+Defined in: [src/seams/docker/container-accessor.ts:37](https://github.com/jterrazz/package-test/blob/main/src/seams/docker/container-accessor.ts#L37)
+
+***
+
+### status
+
+```ts
+readonly status: string;
+```
+
+Defined in: [src/seams/docker/container-accessor.ts:38](https://github.com/jterrazz/package-test/blob/main/src/seams/docker/container-accessor.ts#L38)
+
+## Accessors
+
+### id
+
+#### Get Signature
+
+```ts
+get id(): string | null;
+```
+
+Defined in: [src/seams/docker/container-accessor.ts:48](https://github.com/jterrazz/package-test/blob/main/src/seams/docker/container-accessor.ts#L48)
+
+Underlying Docker container ID, or `null` if no container was captured
+for this name. Useful when a follow-up CLI command needs to reference
+the container by id (e.g. `spwn world inspect <id>`). Prefer the other
+accessors for common reads — pulling the raw id is the escape hatch.
+
+##### Returns
+
+`string` \| `null`
+
+***
+
+### inspect
+
+#### Get Signature
+
+```ts
+get inspect(): JsonAccessor;
+```
+
+Defined in: [src/seams/docker/container-accessor.ts:77](https://github.com/jterrazz/package-test/blob/main/src/seams/docker/container-accessor.ts#L77)
+
+Raw `docker inspect` object for this container. Throws if the container
+was not captured (i.e. `.exists === false`).
+
+##### Returns
+
+[`JsonAccessor`](JsonAccessor.md)
+
+***
+
+### stderr
+
+#### Get Signature
+
+```ts
+get stderr(): TextAccessor;
+```
+
+Defined in: [src/seams/docker/container-accessor.ts:91](https://github.com/jterrazz/package-test/blob/main/src/seams/docker/container-accessor.ts#L91)
+
+Captured logs (stdout+stderr combined for v1).
+
+##### Returns
+
+[`TextAccessor`](TextAccessor.md)
+
+***
+
+### stdout
+
+#### Get Signature
+
+```ts
+get stdout(): TextAccessor;
+```
+
+Defined in: [src/seams/docker/container-accessor.ts:83](https://github.com/jterrazz/package-test/blob/main/src/seams/docker/container-accessor.ts#L83)
+
+Captured logs (stdout+stderr combined for v1).
+
+##### Returns
+
+[`TextAccessor`](TextAccessor.md)
+
+## Methods
+
+### exec()
+
+```ts
+exec(cmd): Promise<CliResult>;
+```
+
+Defined in: [src/seams/docker/container-accessor.ts:132](https://github.com/jterrazz/package-test/blob/main/src/seams/docker/container-accessor.ts#L132)
+
+Run a shell command inside the container and get back the same
+[CliResult](CliResult.md) used for host-side executions.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `cmd` | `string` |
+
+#### Returns
+
+`Promise`\<[`CliResult`](CliResult.md)\>
+
+***
+
+### file()
+
+```ts
+file(path): FileAccessor;
+```
+
+Defined in: [src/seams/docker/container-accessor.ts:103](https://github.com/jterrazz/package-test/blob/main/src/seams/docker/container-accessor.ts#L103)
+
+Read a file from inside the container via `docker exec cat`. The
+returned object satisfies the same [FileAccessor](../type-aliases/FileAccessor.md) shape used by
+the host filesystem accessor, so tests do not need to learn a new API.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+#### Returns
+
+[`FileAccessor`](../type-aliases/FileAccessor.md)

package/docs/reference/interfaces/DirectoryAccessor.md

@@ -0,0 +1,33 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Interface: DirectoryAccessor
+
+Defined in: [src/model/result/directory.ts:97](https://github.com/jterrazz/package-test/blob/main/src/model/result/directory.ts#L97)
+
+Read-only accessor for a directory produced by a spec action.
+
+Assertions go through `expect()` (async — they walk the disk):
+`await expect(result.directory('out')).toMatch('scaffold/out')`
+compares the tree against the fixture directory `_expected/<name>/`.
+
+## Methods
+
+### files()
+
+```ts
+files(options?): Promise<string[]>;
+```
+
+Defined in: [src/model/result/directory.ts:112](https://github.com/jterrazz/package-test/blob/main/src/model/result/directory.ts#L112)
+
+List all files (recursively) under the directory, sorted.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | \{ `ignore?`: `string`[]; \} |
+| `options.ignore?` | `string`[] |
+
+#### Returns
+
+`Promise`\<`string`[]\>