@jterrazz/test 16.0.0 → 16.1.0

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

@@ -0,0 +1,94 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: JobsSpecification\<DatabaseKey\>
+
+```ts
+type JobsSpecification<DatabaseKey> = object;
+```
+
+Defined in: [src/model/chain/builder.ts:216](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L216)
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `DatabaseKey` *extends* `string` | `string` |
+
+## Properties
+
+### clock
+
+```ts
+clock: (iso) => JobsSpecification<DatabaseKey>;
+```
+
+Defined in: [src/model/chain/builder.ts:218](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L218)
+
+Pin the job's `Date` at `iso` for this chain — the calendar the job reads.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `iso` | `string` |
+
+#### Returns
+
+`JobsSpecification`\<`DatabaseKey`\>
+
+***
+
+### intercept
+
+```ts
+intercept: InterceptMethod<JobsSpecification<DatabaseKey>>;
+```
+
+Defined in: [src/model/chain/builder.ts:220](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L220)
+
+Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair.
+
+***
+
+### seed
+
+```ts
+seed: (file, options?) => JobsSpecification<DatabaseKey>;
+```
+
+Defined in: [src/model/chain/builder.ts:222](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L222)
+
+Queue a SQL seed file from `_seeds/` to run before the action.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `file` | `string` |
+| `options?` | \{ `database?`: `DatabaseKey`; \} |
+| `options.database?` | `DatabaseKey` |
+
+#### Returns
+
+`JobsSpecification`\<`DatabaseKey`\>
+
+***
+
+### trigger
+
+```ts
+trigger: (name) => Promise<JobsResult>;
+```
+
+Defined in: [src/model/chain/builder.ts:225](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L225)
+
+Execute the named job registered via the `jobs` option and resolve with the result.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `name` | `string` |
+
+#### Returns
+
+`Promise`\<[`JobsResult`](JobsResult.md)\>

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

@@ -0,0 +1,56 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: JobsSpecificationOptions\<Services\>
+
+```ts
+type JobsSpecificationOptions<Services> = object;
+```
+
+Defined in: [src/facets/jobs/jobs.specification.ts:18](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L18)
+
+Options for startJobs \| specification.jobs.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Services` *extends* [`ServiceRecord`](ServiceRecord.md) | [`ServiceRecord`](ServiceRecord.md) |
+
+## Properties
+
+### jobs
+
+```ts
+jobs: 
+  | ((services) => JobHandle[])
+  | JobHandle[];
+```
+
+Defined in: [src/facets/jobs/jobs.specification.ts:24](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L24)
+
+Named jobs triggerable via `jobs.trigger(name)` — a factory receiving
+the started services record, or a static array. Jobs run in-process by
+definition (CONVENTIONS A8).
+
+***
+
+### root?
+
+```ts
+optional root?: string;
+```
+
+Defined in: [src/facets/jobs/jobs.specification.ts:26](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L26)
+
+Project root override — see the `root` option of `specification.api()`.
+
+***
+
+### services?
+
+```ts
+optional services?: Services;
+```
+
+Defined in: [src/facets/jobs/jobs.specification.ts:28](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L28)
+
+Named infrastructure record started via testcontainers.

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

@@ -0,0 +1,20 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: LandmarkKind
+
+```ts
+type LandmarkKind = 
+  | "banner"
+  | "complementary"
+  | "contentinfo"
+  | "form"
+  | "main"
+  | "navigation"
+  | "region"
+  | "search";
+```
+
+Defined in: [src/model/ports/browser.port.ts:6](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L6)
+
+The landmark roles — the standard set of page regions, and the only
+containers a scope can name. Closed on purpose: ARIA defines exactly these,
+so `within()` never becomes a second selector language.

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

@@ -0,0 +1,27 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: LiterateRunFlags
+
+```ts
+type LiterateRunFlags = object;
+```
+
+Defined in: [src/facets/cli/literate.ts:66](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L66)
+
+Per-call options for runSpecDocument / `cli.run()`.
+
+## Properties
+
+### frozen?
+
+```ts
+optional frozen?: boolean;
+```
+
+Defined in: [src/facets/cli/literate.ts:75](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L75)
+
+Opt this document OUT of the update-mode rewrite. A frozen document is
+NEVER written under `TEST_UPDATE=1`: its mismatch still throws its diff.
+That is what makes a DELIBERATELY-WRONG `.spec.yaml` — one whose failure
+rendering is the subject of a negative test — survive an update run
+instead of being silently corrected into a passing file. The document's
+mirror of `toMatch(name, { frozen: true })`.

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

@@ -0,0 +1,70 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: LiterateServeRegistration
+
+```ts
+type LiterateServeRegistration = object;
+```
+
+Defined in: [src/facets/cli/literate.ts:51](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L51)
+
+A server a document may start by name (`serve: mcp`), registered once per app
+in the `serve` option of `specification.cli()`.
+
+## Properties
+
+### command
+
+```ts
+command: string;
+```
+
+Defined in: [src/facets/cli/literate.ts:53](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L53)
+
+Shell command that starts the server, run from the project root.
+
+***
+
+### env
+
+```ts
+env: string;
+```
+
+Defined in: [src/facets/cli/literate.ts:55](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L55)
+
+The variable the resolved URL is bound to in every run's child env.
+
+***
+
+### ready
+
+```ts
+ready: RegExp;
+```
+
+Defined in: [src/facets/cli/literate.ts:60](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L60)
+
+Matched against the server's output; the FIRST capture group is the port
+it chose — named (`(?<port>\d+)`) or not, it is group 1 either way.
+
+***
+
+### url
+
+```ts
+url: (port) => string;
+```
+
+Defined in: [src/facets/cli/literate.ts:62](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L62)
+
+Builds the URL bound to [env](#env) from the announced port.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `port` | `number` |
+
+#### Returns
+
+`string`

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

@@ -0,0 +1,27 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MatchFixtureOptions
+
+```ts
+type MatchFixtureOptions = object;
+```
+
+Defined in: [src/model/result/match-options.ts:21](https://github.com/jterrazz/package-test/blob/main/src/model/result/match-options.ts#L21)
+
+Per-call options for the fixture-file `toMatch` subjects. `frozen` opts a
+single fixture OUT of update-mode rewriting: a frozen fixture is NEVER
+written under `TEST_UPDATE=1` (or vitest `-u`) — in update mode a frozen
+mismatch still throws its diff, and a frozen missing fixture still throws its
+"does not exist" error. This is what makes a DELIBERATELY-WRONG fixture (the
+subject of a negative test that asserts the mismatch/error rendering)
+survivable across update runs instead of being silently overwritten with the
+actual output.
+
+## Properties
+
+### frozen?
+
+```ts
+optional frozen?: boolean;
+```
+
+Defined in: [src/model/result/match-options.ts:22](https://github.com/jterrazz/package-test/blob/main/src/model/result/match-options.ts#L22)

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

@@ -0,0 +1,61 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MatchableRequest
+
+```ts
+type MatchableRequest = object;
+```
+
+Defined in: [src/model/contracts/types.ts:7](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L7)
+
+The observed outgoing request, reduced to what contract matchers inspect.
+Built once per request by the engine (MSW on api/jobs, the stub backend on
+website/mobile) and handed to [ContractRequest.match](ContractRequest.md#match) and to a
+[ContractResponder](ContractResponder.md).
+
+## Properties
+
+### body
+
+```ts
+body: unknown;
+```
+
+Defined in: [src/model/contracts/types.ts:9](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L9)
+
+Parsed JSON body when the payload is JSON, the raw text otherwise, or `null` when absent.
+
+***
+
+### headers
+
+```ts
+headers: Record<string, string>;
+```
+
+Defined in: [src/model/contracts/types.ts:11](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L11)
+
+Request headers, keyed by lowercased header name.
+
+***
+
+### method
+
+```ts
+method: string;
+```
+
+Defined in: [src/model/contracts/types.ts:13](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L13)
+
+Uppercased HTTP method of the observed request.
+
+***
+
+### url
+
+```ts
+url: string;
+```
+
+Defined in: [src/model/contracts/types.ts:15](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L15)
+
+The request URL — fully-qualified, or origin-relative for the stub backend.

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

@@ -0,0 +1,34 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MatcherKind
+
+```ts
+type MatcherKind = 
+  | "any"
+  | "base64"
+  | "date"
+  | "duration"
+  | "email"
+  | "float"
+  | "hex"
+  | "includes"
+  | "int"
+  | "ip"
+  | "iso8601"
+  | "number"
+  | "path"
+  | "port"
+  | "ref"
+  | "regex"
+  | "semver"
+  | "sha"
+  | "string"
+  | "time"
+  | "ulid"
+  | "url"
+  | "uuid"
+  | "workdir";
+```
+
+Defined in: [src/model/matching/match.ts:12](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L12)
+
+The frozen token vocabulary (CONVENTIONS D4) plus the code-only kinds.

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

@@ -0,0 +1,28 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MobileBackendOptions
+
+```ts
+type MobileBackendOptions = object;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:23](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L23)
+
+The declared stub backend behind the app under test. The framework owns
+the simulator and appium but NOT the JS bundler (Metro belongs to the
+caller's repo, like `next build` belongs to a website's) — so nothing is
+injected: the handle exposes `backendUrl` and the CALLER wires it into its
+own bundler env.
+
+## Properties
+
+### port?
+
+```ts
+optional port?: number;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:29](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L29)
+
+Fixed port — pins a stable stub URL across runs. Metro inlines
+`EXPO_PUBLIC_*` values at bundle-serve time; a stable port lets a warm
+Metro survive between runs. Default: a free OS-assigned port.

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

@@ -0,0 +1,14 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MobileElementKind
+
+```ts
+type MobileElementKind = "button" | "field" | "testId" | "text";
+```
+
+Defined in: [src/model/ports/device.port.ts:10](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L10)
+
+The element kinds a mobile screen can designate — the structural subset of
+[ElementRef](ElementRef.md) kinds that map onto the XCUITest accessibility tree.
+There is ONE element vocabulary across facets: `button('Bookmark')` works
+in a visit scenario and a mobile scenario alike. Landmarks have no iOS
+analog — passing one to a mobile verb refuses at runtime.

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

@@ -0,0 +1,60 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MobileElementMatch
+
+```ts
+type MobileElementMatch = object;
+```
+
+Defined in: [src/model/ports/device.port.ts:32](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L32)
+
+One candidate captured when a descriptor matched more than one element —
+the evidence the ambiguity error enumerates so the author can disambiguate
+without opening the simulator.
+
+## Properties
+
+### identifier?
+
+```ts
+optional identifier?: string;
+```
+
+Defined in: [src/model/ports/device.port.ts:34](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L34)
+
+The accessibility identifier (`testId()` target), when one is set.
+
+***
+
+### label?
+
+```ts
+optional label?: string;
+```
+
+Defined in: [src/model/ports/device.port.ts:36](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L36)
+
+The accessible label, whitespace-collapsed and truncated.
+
+***
+
+### type
+
+```ts
+type: string;
+```
+
+Defined in: [src/model/ports/device.port.ts:38](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L38)
+
+Element type without the `XCUIElementType` prefix — `Button`, `StaticText`.
+
+***
+
+### value?
+
+```ts
+optional value?: string;
+```
+
+Defined in: [src/model/ports/device.port.ts:40](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L40)
+
+The element value (text-field content, adjustable value), when present.

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

@@ -0,0 +1,20 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MobileElementRef
+
+```ts
+type MobileElementRef = ElementRef;
+```
+
+Defined in: [src/model/ports/device.port.ts:25](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L25)
+
+A user-facing element descriptor for mobile scenarios — pure data, built by
+the shared element vocabulary (`button()`, `field()`, `content()`,
+`testId()`, `within()`) and translated into iOS predicate strings by the
+device integration. Structurally the same ref type as the browser's, so the
+vocabulary stays single; kinds outside [MobileElementKind](MobileElementKind.md) (the ARIA
+landmarks) are refused at runtime with a message naming the boundary.
+
+A descriptor must designate exactly ONE element when a verb ACTS on it
+(`tap`, `fill`) — see [MobileElementMatch](MobileElementMatch.md) and CONVENTIONS W3.
+`see()` acts on nothing, so any visible match satisfies it: XCUITest trees
+legitimately duplicate a label across container and child.

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

@@ -0,0 +1,65 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MobileHandle
+
+```ts
+type MobileHandle = object;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:83](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L83)
+
+The record returned by startMobile \| specification.mobile.
+Destructure with the canonical names (CONVENTIONS A3):
+
+    const { mobile, cleanup, udid } = await specification.mobile(…);
+
+## Properties
+
+### backendUrl?
+
+```ts
+optional backendUrl?: string;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:89](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L89)
+
+Base URL of the declared stub backend — present only with the
+`backend` option. The caller injects it into its own bundler env
+(e.g. `EXPO_PUBLIC_API_URL`); the framework never touches the bundler.
+
+***
+
+### cleanup
+
+```ts
+cleanup: () => Promise<void>;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:91](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L91)
+
+End the driver session, stop the appium server and the stub backend.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### mobile
+
+```ts
+mobile: MobileSpecification;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:92](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L92)
+
+***
+
+### udid
+
+```ts
+udid: string;
+```
+
+Defined in: [src/facets/mobile/mobile.specification.ts:94](https://github.com/jterrazz/package-test/blob/main/src/facets/mobile/mobile.specification.ts#L94)
+
+The resolved simulator UDID the specs run against.

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

@@ -0,0 +1,20 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MobileScenario
+
+```ts
+type MobileScenario = (visitor) => Promise<void>;
+```
+
+Defined in: [src/model/ports/device.port.ts:60](https://github.com/jterrazz/package-test/blob/main/src/model/ports/device.port.ts#L60)
+
+The behavior of an open — the When of the spec; assertions stay in the Then.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `visitor` | [`MobileVisitor`](MobileVisitor.md) |
+
+## Returns
+
+`Promise`\<`void`\>

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

@@ -0,0 +1,51 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Type Alias: MobileSpecification
+
+```ts
+type MobileSpecification = object;
+```
+
+Defined in: [src/model/chain/builder.ts:332](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L332)
+
+The `mobile` facet — screen chain entry handed out by
+`specification.mobile()`. `.open()` is the single, terminal action: it
+terminates and relaunches the app (deterministic fresh state), applies the
+deep link, runs the scenario, and captures the final screen.
+
+## Properties
+
+### intercept
+
+```ts
+intercept: InterceptMethod<MobileSpecification>;
+```
+
+Defined in: [src/model/chain/builder.ts:337](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L337)
+
+Declare the chain's backend contracts — served by the declared stub
+backend (requires the runner's `backend` option). Multiple calls append.
+
+***
+
+### open
+
+```ts
+open: (deepLink?, scenario?) => Promise<ScreenResult>;
+```
+
+Defined in: [src/model/chain/builder.ts:344](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L344)
+
+Relaunch the app and resolve with the captured screen. With a deep
+link, the app opens on it; with a scenario, the visitor interacts
+first (the When) and the capture reflects the FINAL screen state.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `deepLink?` | `string` |
+| `scenario?` | [`MobileScenario`](MobileScenario.md) |
+
+#### Returns
+
+`Promise`\<[`ScreenResult`](../interfaces/ScreenResult.md)\>