@jterrazz/test 15.3.0 → 16.1.0

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

@@ -0,0 +1,126 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MobileSpecificationOptions\<Services\>
+
+```ts
+type MobileSpecificationOptions<Services> = object;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:33](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L33)
+
+Options for startMobile \| specification.mobile.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Services` *extends* [`ServiceRecord`](ServiceRecord.md) | [`ServiceRecord`](ServiceRecord.md) |
+
+## Properties
+
+### app
+
+```ts
+app: object;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:35](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L35)
+
+The app under test — terminated and relaunched by every `.open()`.
+
+#### bundleId
+
+```ts
+bundleId: string;
+```
+
+Bundle id of the installed app (`com.example.app`).
+
+***
+
+### backend?
+
+```ts
+optional backend?: MobileBackendOptions;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:44](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L44)
+
+Declared stub backend: started with the runner, serving the contracts
+each chain declares via `.intercept(...)`. The handle gains
+`backendUrl` — inject it into your bundler env yourself.
+
+***
+
+### device
+
+```ts
+device: object;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:46](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L46)
+
+The simulator to run on — resolved through `xcrun simctl`.
+
+#### name
+
+```ts
+name: string;
+```
+
+Simulator name, matched exactly (`iPhone 17`).
+
+#### os?
+
+```ts
+optional os?: string;
+```
+
+OS narrowing when the name exists on several runtimes — `'26.5'` or `'iOS 26.5'`.
+
+#### udid?
+
+```ts
+optional udid?: string;
+```
+
+Explicit UDID — skips name/os resolution entirely.
+
+***
+
+### root?
+
+```ts
+optional root?: string;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:59](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L59)
+
+Project-root override (CONVENTIONS A9): where the appium binary is
+resolved from (`node_modules/.bin`). Auto-discovered from the calling
+file when absent.
+
+***
+
+### services?
+
+```ts
+optional services?: Services;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:73](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L73)
+
+Named services started with the runner and stopped with it — a
+`process()` for the bundler the app loads from, a database a dev build
+reads. Metro stops being a `beforeAll` the repository maintains: it is
+`process({ command: 'expo start', ready: /Metro waiting on .*:(\\d+)/ })`
+like every other external process the framework owns.
+
+***
+
+### timeouts?
+
+```ts
+optional timeouts?: DeviceTimeouts;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:74](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L74)

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

@@ -0,0 +1,81 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MobileVisitor
+
+```ts
+type MobileVisitor = object;
+```
+
+Defined in: [src/model/ports/device.port.ts:50](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L50)
+
+The visitor — the interaction vocabulary handed to a mobile scenario.
+Every verb auto-waits by polling until a visible match exists; acting
+verbs then enforce exactly-one (W3), while `see()` — the single
+synchronization primitive — is satisfied by any visible match. There is
+no sleep and no conditional helper.
+
+## Properties
+
+### fill
+
+```ts
+fill: (element, value) => Promise<void>;
+```
+
+Defined in: [src/model/ports/device.port.ts:52](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L52)
+
+Fill a text field with a value.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`MobileElementRef`](MobileElementRef.md) |
+| `value` | `string` |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### see
+
+```ts
+see: (element) => Promise<void>;
+```
+
+Defined in: [src/model/ports/device.port.ts:54](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L54)
+
+Wait until the element is visible — the only synchronization primitive.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`MobileElementRef`](MobileElementRef.md) |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### tap
+
+```ts
+tap: (element) => Promise<void>;
+```
+
+Defined in: [src/model/ports/device.port.ts:56](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L56)
+
+Tap the element.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`MobileElementRef`](MobileElementRef.md) |
+
+#### Returns
+
+`Promise`\<`void`\>

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

@@ -0,0 +1,26 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MockOfOptions
+
+```ts
+type MockOfOptions = object;
+```
+
+Defined in: [src/model/doubles/mock-of.ts:5](https://github.com/jterrazz/package-test/blob/main/src/model/doubles/mock-of.ts#L5)
+
+How much of the port the double answers for.
+
+## Properties
+
+### deep?
+
+```ts
+optional deep?: boolean;
+```
+
+Defined in: [src/model/doubles/mock-of.ts:13](https://github.com/jterrazz/package-test/blob/main/src/model/doubles/mock-of.ts#L13)
+
+Deep (the default): reading a member that was never stubbed hands back
+another double, however far down the port nests. `false` gives the flat
+proxy — every member of `T` and nothing beneath them, which is what a
+port with a nested namespace wants when the test only ever touches the
+first level.

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

@@ -0,0 +1,10 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MockPort
+
+```ts
+type MockPort = typeof mockOf;
+```
+
+Defined in: [src/model/doubles/mock-of.ts:35](https://github.com/jterrazz/package-test/blob/main/src/model/doubles/mock-of.ts#L35)
+
+The factory's own shape — kept as a name so a consumer can annotate with it.

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

@@ -0,0 +1,10 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: PinnedClock
+
+```ts
+type PinnedClock = Disposable;
+```
+
+Defined in: [src/model/clock/clock.ts:23](https://github.com/jterrazz/package-test/blob/main/src/model/clock/clock.ts#L23)
+
+A pinned clock — released when the `using` scope that declared it ends.

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

@@ -0,0 +1,32 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: PostgresOptions
+
+```ts
+type PostgresOptions = object;
+```
+
+Defined in: [src/seams/postgres/postgres.ts:23](https://github.com/jterrazz/package-test/blob/main/src/seams/postgres/postgres.ts#L23)
+
+## Properties
+
+### env?
+
+```ts
+optional env?: Record<string, string>;
+```
+
+Defined in: [src/seams/postgres/postgres.ts:27](https://github.com/jterrazz/package-test/blob/main/src/seams/postgres/postgres.ts#L27)
+
+Override environment variables.
+
+***
+
+### image?
+
+```ts
+optional image?: string;
+```
+
+Defined in: [src/seams/postgres/postgres.ts:25](https://github.com/jterrazz/package-test/blob/main/src/seams/postgres/postgres.ts#L25)
+
+Override image.

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

@@ -0,0 +1,112 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ProcessOptions
+
+```ts
+type ProcessOptions = object;
+```
+
+Defined in: [src/seams/process/serve.adapter.ts:18](https://github.com/jterrazz/package-test/blob/main/src/seams/process/serve.adapter.ts#L18)
+
+The ONE shape an external process takes — the site under test, a backend a
+page talks to, a bundler a simulator loads from. Built by `process()`
+(chapter 17) and accepted wherever a facet starts something outside this
+process: `website({ server })`, `services: { api: process(…) }`, and the
+literate `serve:` registry.
+
+## Properties
+
+### before?
+
+```ts
+optional before?: string;
+```
+
+Defined in: [src/seams/process/serve.adapter.ts:24](https://github.com/jterrazz/package-test/blob/main/src/seams/process/serve.adapter.ts#L24)
+
+A one-shot command run ONCE per specification, before the process is
+spawned, which must exit 0 — a build, a migration, a fixture load. Its
+failure is the specification's, and it says so.
+
+***
+
+### command
+
+```ts
+command: string;
+```
+
+Defined in: [src/seams/process/serve.adapter.ts:26](https://github.com/jterrazz/package-test/blob/main/src/seams/process/serve.adapter.ts#L26)
+
+Shell command that starts the process. Receives the chosen port as `PORT`.
+
+***
+
+### cwd?
+
+```ts
+optional cwd?: string;
+```
+
+Defined in: [src/seams/process/serve.adapter.ts:28](https://github.com/jterrazz/package-test/blob/main/src/seams/process/serve.adapter.ts#L28)
+
+Working directory, relative to the project root. Default: the root itself.
+
+***
+
+### env?
+
+```ts
+optional env?: 
+  | ((services) => Record<string, string>)
+| Record<string, string>;
+```
+
+Defined in: [src/seams/process/serve.adapter.ts:34](https://github.com/jterrazz/package-test/blob/main/src/seams/process/serve.adapter.ts#L34)
+
+Environment for the child, on top of the runner's own. A function
+receives the services already started beside this one, so a process can
+be handed a sibling's connection string.
+
+***
+
+### port?
+
+```ts
+optional port?: number;
+```
+
+Defined in: [src/seams/process/serve.adapter.ts:38](https://github.com/jterrazz/package-test/blob/main/src/seams/process/serve.adapter.ts#L38)
+
+Fixed port. Default: an OS-assigned free port, injected as `PORT`.
+
+***
+
+### ready?
+
+```ts
+optional ready?: RegExp | string;
+```
+
+Defined in: [src/seams/process/serve.adapter.ts:50](https://github.com/jterrazz/package-test/blob/main/src/seams/process/serve.adapter.ts#L50)
+
+How readiness is observed. Two forms:
+
+- a **path** (or nothing) — the framework picks the port, injects it as
+  `PORT`, and polls `<baseUrl><path>` until it answers any HTTP status
+  (default `/`). This is `specification.website()`'s form.
+- a **regex over the child's output** with ONE capture group holding the
+  port the server chose itself. Nothing is injected as `PORT`: the server
+  announces its port and the framework reads it from the banner. This is
+  the form a literate `serve:` registration uses.
+
+***
+
+### timeout?
+
+```ts
+optional timeout?: number;
+```
+
+Defined in: [src/seams/process/serve.adapter.ts:52](https://github.com/jterrazz/package-test/blob/main/src/seams/process/serve.adapter.ts#L52)
+
+Readiness budget in milliseconds. Default 30 000.

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

@@ -0,0 +1,20 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: RedisOptions
+
+```ts
+type RedisOptions = object;
+```
+
+Defined in: [src/seams/redis/redis.ts:6](https://github.com/jterrazz/package-test/blob/main/src/seams/redis/redis.ts#L6)
+
+## Properties
+
+### image?
+
+```ts
+optional image?: string;
+```
+
+Defined in: [src/seams/redis/redis.ts:8](https://github.com/jterrazz/package-test/blob/main/src/seams/redis/redis.ts#L8)
+
+Override image.

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

@@ -0,0 +1,12 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: RenderSubject
+
+```ts
+type RenderSubject = ComponentUi | DomMount;
+```
+
+Defined in: [src/facets/component/component.types.ts:31](https://github.com/jterrazz/package-test/blob/main/src/facets/component/component.types.ts#L31)
+
+What `.render()` mounts. A React tree is an element (`<PostTable />`); a
+vanilla DOM subject is the FUNCTION that fills a container, which is how a
+DOM-only module is called in production too.

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

@@ -0,0 +1,67 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ScreenNode
+
+```ts
+type ScreenNode = object;
+```
+
+Defined in: [src/model/ports/device.port.ts:68](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L68)
+
+One node of the projected accessibility tree — the XCUITest page source
+with its noise collapsed: unlabeled, identifier-less, valueless wrapper
+nodes are dropped and their children hoisted, so the projection stays
+stable and golden-friendly. Type names lose the `XCUIElementType` prefix.
+
+## Properties
+
+### children?
+
+```ts
+optional children?: ScreenNode[];
+```
+
+Defined in: [src/model/ports/device.port.ts:69](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L69)
+
+***
+
+### identifier?
+
+```ts
+optional identifier?: string;
+```
+
+Defined in: [src/model/ports/device.port.ts:71](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L71)
+
+The accessibility identifier, only when it differs from the label.
+
+***
+
+### label?
+
+```ts
+optional label?: string;
+```
+
+Defined in: [src/model/ports/device.port.ts:72](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L72)
+
+***
+
+### type
+
+```ts
+type: string;
+```
+
+Defined in: [src/model/ports/device.port.ts:74](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L74)
+
+Element type without the `XCUIElementType` prefix — `Button`, `StaticText`.
+
+***
+
+### value?
+
+```ts
+optional value?: string;
+```
+
+Defined in: [src/model/ports/device.port.ts:75](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L75)

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

@@ -0,0 +1,36 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ServerPort
+
+```ts
+type ServerPort = object;
+```
+
+Defined in: [src/model/ports/server.port.ts:17](https://github.com/jterrazz/package-test/blob/main/src/model/ports/server.port.ts#L17)
+
+Abstract server interface for specification runners.
+Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
+
+## Properties
+
+### request
+
+```ts
+request: (method, path, body?, headers?) => Promise<ServerResponse>;
+```
+
+Defined in: [src/model/ports/server.port.ts:19](https://github.com/jterrazz/package-test/blob/main/src/model/ports/server.port.ts#L19)
+
+Send an HTTP request and return the parsed response.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `method` | `string` |
+| `path` | `string` |
+| `body?` | `unknown` |
+| `headers?` | `Record`\<`string`, `string`\> |
+
+#### Returns
+
+`Promise`\<[`ServerResponse`](ServerResponse.md)\>

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

@@ -0,0 +1,46 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ServerResponse
+
+```ts
+type ServerResponse = object;
+```
+
+Defined in: [src/model/ports/server.port.ts:4](https://github.com/jterrazz/package-test/blob/main/src/model/ports/server.port.ts#L4)
+
+HTTP response returned by a server port, with parsed JSON body.
+
+## Properties
+
+### body
+
+```ts
+body: unknown;
+```
+
+Defined in: [src/model/ports/server.port.ts:8](https://github.com/jterrazz/package-test/blob/main/src/model/ports/server.port.ts#L8)
+
+Parsed JSON response body, or null if parsing failed.
+
+***
+
+### headers
+
+```ts
+headers: Record<string, string>;
+```
+
+Defined in: [src/model/ports/server.port.ts:10](https://github.com/jterrazz/package-test/blob/main/src/model/ports/server.port.ts#L10)
+
+Response headers as a flat key-value map.
+
+***
+
+### status
+
+```ts
+status: number;
+```
+
+Defined in: [src/model/ports/server.port.ts:6](https://github.com/jterrazz/package-test/blob/main/src/model/ports/server.port.ts#L6)
+
+HTTP status code.

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

@@ -0,0 +1,21 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: ServerSpec\<Services\>
+
+```ts
+type ServerSpec<Services> = 
+  | ((services) => 
+  | ProcessHandle
+  | ProcessOptions)
+  | ProcessHandle
+  | ProcessOptions;
+```
+
+Defined in: [src/facets/website/website.specification.ts:32](https://github.com/jterrazz/package-test/blob/main/src/facets/website/website.specification.ts#L32)
+
+What `server` may be handed as, and what it resolves to.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `Services` *extends* [`ServiceRecord`](ServiceRecord.md) |