@jterrazz/test 16.0.0 → 16.1.0

package/docs/reference/classes/ProcessHandle.md

@@ -0,0 +1,368 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Class: ProcessHandle
+
+Defined in: [src/model/chain/process.ts:21](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L21)
+
+An external process, declared like any other service.
+
+One shape for every one of them: a site's dev server, an API behind the
+site, the bundler a simulator loads from. Without it each is declared
+somewhere else — a facet option, a document's `serve:` entry, a `beforeAll`
+spawning a child and an `afterAll` that sometimes forgets to kill it — and
+the lifetime belongs to whoever remembered. Here it is the framework's.
+
+It sits in a `services` record beside `postgres()`, `redis()` and
+`sqlite()`, so it starts after them and can be handed their connection
+strings through `env`, and it is stopped with the specification.
+
+## Implements
+
+- [`ServiceHandle`](../type-aliases/ServiceHandle.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new ProcessHandle(options): ProcessHandle;
+```
+
+Defined in: [src/model/chain/process.ts:35](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L35)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | [`ProcessOptions`](../type-aliases/ProcessOptions.md) |
+
+#### Returns
+
+`ProcessHandle`
+
+## Properties
+
+### connectionString
+
+```ts
+connectionString: string = '';
+```
+
+Defined in: [src/model/chain/process.ts:29](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L29)
+
+Connection string — populated after start.
+
+#### Implementation of
+
+```ts
+ServiceHandle.connectionString
+```
+
+***
+
+### defaultImage
+
+```ts
+readonly defaultImage: "" = '';
+```
+
+Defined in: [src/model/chain/process.ts:23](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L23)
+
+Embedded: nothing to pull, nothing to run in a container.
+
+#### Implementation of
+
+```ts
+ServiceHandle.defaultImage
+```
+
+***
+
+### defaultPort
+
+```ts
+readonly defaultPort: 0 = 0;
+```
+
+Defined in: [src/model/chain/process.ts:24](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L24)
+
+Default container port for this service type.
+
+#### Implementation of
+
+```ts
+ServiceHandle.defaultPort
+```
+
+***
+
+### environment
+
+```ts
+readonly environment: Record<string, string> = {};
+```
+
+Defined in: [src/model/chain/process.ts:25](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L25)
+
+Environment variables to pass to the container.
+
+#### Implementation of
+
+```ts
+ServiceHandle.environment
+```
+
+***
+
+### serviceName
+
+```ts
+serviceName: string | null = null;
+```
+
+Defined in: [src/model/chain/process.ts:28](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L28)
+
+The name this handle is known by. Left `null` until the orchestrator
+assigns it at start time: it is the kebab-case form of the RECORD KEY,
+so `{ analyticsDb: postgres() }` reports as `analytics-db` and reads its
+init script from `docker/analytics-db/`. The key is the only name a
+specification writes; a handle carries no second one of its own.
+
+#### Implementation of
+
+```ts
+ServiceHandle.serviceName
+```
+
+***
+
+### started
+
+```ts
+started: boolean = false;
+```
+
+Defined in: [src/model/chain/process.ts:30](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L30)
+
+Whether this service has been started.
+
+#### Implementation of
+
+```ts
+ServiceHandle.started
+```
+
+***
+
+### type
+
+```ts
+readonly type: "process" = 'process';
+```
+
+Defined in: [src/model/chain/process.ts:26](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L26)
+
+Service type identifier.
+
+#### Implementation of
+
+```ts
+ServiceHandle.type
+```
+
+## Accessors
+
+### spec
+
+#### Get Signature
+
+```ts
+get spec(): ProcessOptions;
+```
+
+Defined in: [src/model/chain/process.ts:122](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L122)
+
+What it was declared as — what a facet reads to start it in a slot of its own.
+
+##### Returns
+
+[`ProcessOptions`](../type-aliases/ProcessOptions.md)
+
+***
+
+### url
+
+#### Get Signature
+
+```ts
+get url(): string;
+```
+
+Defined in: [src/model/chain/process.ts:127](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L127)
+
+The base URL it came up on — known only once it is started.
+
+##### Returns
+
+`string`
+
+## Methods
+
+### buildConnectionString()
+
+```ts
+buildConnectionString(host, port): string;
+```
+
+Defined in: [src/model/chain/process.ts:39](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L39)
+
+Build the connection string from host and port.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `host` | `string` |
+| `port` | `number` |
+
+#### Returns
+
+`string`
+
+#### Implementation of
+
+```ts
+ServiceHandle.buildConnectionString
+```
+
+***
+
+### createDatabaseAdapter()
+
+```ts
+createDatabaseAdapter(): DatabasePort | null;
+```
+
+Defined in: [src/model/chain/process.ts:43](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L43)
+
+Create a DatabasePort adapter (if this is a database). Returns null otherwise.
+
+#### Returns
+
+[`DatabasePort`](../type-aliases/DatabasePort.md) \| `null`
+
+#### Implementation of
+
+```ts
+ServiceHandle.createDatabaseAdapter
+```
+
+***
+
+### healthcheck()
+
+```ts
+healthcheck(): Promise<void>;
+```
+
+Defined in: [src/model/chain/process.ts:47](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L47)
+
+Verify the service is ready and accepting connections. Throws with context if not.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+```ts
+ServiceHandle.healthcheck
+```
+
+***
+
+### initialize()
+
+```ts
+initialize(): Promise<void>;
+```
+
+Defined in: [src/model/chain/process.ts:58](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L58)
+
+A process is not a container, so the orchestrator never starts it: the
+facet does, once its siblings are up and their connection strings are
+readable (startProcessServices).
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+```ts
+ServiceHandle.initialize
+```
+
+***
+
+### isolation()
+
+```ts
+isolation(): IsolationStrategy;
+```
+
+Defined in: [src/model/chain/process.ts:70](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L70)
+
+Isolation is the RUN's, not the worker's — and a run here is one
+EVALUATION of the specification module. Under vitest's default
+isolation that is once per test file, so two files that import the same
+specification get a child each, with the id the facet minted for it.
+Nothing is acquired or reset between tests: the id is what tells two
+runs apart, never a label a spec samples.
+
+#### Returns
+
+[`IsolationStrategy`](../type-aliases/IsolationStrategy.md)
+
+#### Implementation of
+
+```ts
+ServiceHandle.isolation
+```
+
+***
+
+### reset()
+
+```ts
+reset(): Promise<void>;
+```
+
+Defined in: [src/model/chain/process.ts:84](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L84)
+
+Reset state between tests (truncate tables, flush cache, etc.)
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+```ts
+ServiceHandle.reset
+```
+
+***
+
+### shutdown()
+
+```ts
+shutdown(): Promise<void>;
+```
+
+Defined in: [src/model/chain/process.ts:115](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L115)
+
+Terminate the process group. Idempotent.
+
+#### Returns
+
+`Promise`\<`void`\>

package/docs/reference/functions/defineContract.md

@@ -0,0 +1,39 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Function: defineContract()
+
+```ts
+function defineContract(contract): Contract;
+```
+
+Defined in: [src/model/contracts/contract.ts:71](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L71)
+
+Declare one contract. Identity function — its value is the enforced shape
+and the naming convention:
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `contract` | [`Contract`](../type-aliases/Contract.md) |
+
+## Returns
+
+[`Contract`](../type-aliases/Contract.md)
+
+## Example
+
+```ts
+// specs/api/reports/contracts/openai/classify-article.ts
+  import { defineContract, openai } from '@jterrazz/test';
+
+  export default defineContract({
+      request: openai.responses({ user: PROMPT, tools: ['classify'] }),
+      response: openai.reply({ categories: ['TECH'] }),
+  });
+
+  // Dynamic — the response is computed from the observed request:
+  export default defineContract({
+      request: http.post('https://api.example.com/echo'),
+      response: (request) => http.json({ received: request.body }),
+  });
+```

package/docs/reference/functions/defineContracts.md

@@ -0,0 +1,36 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Function: defineContracts()
+
+```ts
+function defineContracts(...items): Contracts;
+```
+
+Defined in: [src/model/contracts/contract.ts:137](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L137)
+
+Compose contracts into the artifact a test imports — it's contracts all the
+way down: a composite may extend contracts, lists, and other composites,
+recursively, order preserved.
+
+`.with(...)` derives a scenario: contracts whose route the overrides claim
+are removed from the base, and the overrides are prepended. Under
+first-match selection a more specific override (`/articles/gone-1`) also
+wins over a generic base route (`/articles/{{uuid}}`) it does not replace.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| ...`items` | [`ContractInput`](../type-aliases/ContractInput.md)[] |
+
+## Returns
+
+[`Contracts`](../type-aliases/Contracts.md)
+
+## Example
+
+```ts
+// contracts/newsroom.contracts.ts
+  export default defineContracts(events, articleById);
+  export const withArticleGone = (id: string) =>
+      newsroom.with(articleGone(id));
+```

package/docs/reference/functions/disabled.md

@@ -0,0 +1,28 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Function: disabled()
+
+```ts
+function disabled(element): ElementRef;
+```
+
+Defined in: [src/model/elements/elements.ts:175](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L175)
+
+Whether the element accepts input: `see(disabled(button('Delete')))` asserts
+it refuses, `see(enabled(button('Delete')))` that it takes it.
+
+Modifiers rather than descriptors, for the same reason as `focused`: being
+disabled is a state of an element the vocabulary already names. Unlike focus,
+the ARIA tree carries it, so a golden pins a whole outline's enablement and
+these name the ONE control a test is about. They also buy the direction a
+behavioural substitute cannot reach — clicking a disabled control is a
+timeout, never an assertion.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`ElementRef`](../type-aliases/ElementRef.md) |
+
+## Returns
+
+[`ElementRef`](../type-aliases/ElementRef.md)

package/docs/reference/functions/enabled.md

@@ -0,0 +1,20 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Function: enabled()
+
+```ts
+function enabled(element): ElementRef;
+```
+
+Defined in: [src/model/elements/elements.ts:178](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L178)
+
+The other direction of [disabled](disabled.md) — the element takes input.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`ElementRef`](../type-aliases/ElementRef.md) |
+
+## Returns
+
+[`ElementRef`](../type-aliases/ElementRef.md)

package/docs/reference/functions/focused.md

@@ -0,0 +1,26 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Function: focused()
+
+```ts
+function focused(element): ElementRef;
+```
+
+Defined in: [src/model/elements/elements.ts:162](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L162)
+
+Where the keyboard is: `see(focused(button('Open')))` asserts the element has
+focus, `gone(focused(x))` that it does not.
+
+A modifier rather than a descriptor of its own, because focus is a STATE of
+an element the vocabulary can already name. It is a verb's business and never
+a golden's: the accessibility tree carries no focus, so a tree snapshot of a
+dialog that took the keyboard and one that did not are byte-identical.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `element` | [`ElementRef`](../type-aliases/ElementRef.md) |
+
+## Returns
+
+[`ElementRef`](../type-aliases/ElementRef.md)

package/docs/reference/functions/mockOf.md

@@ -0,0 +1,79 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Function: mockOf()
+
+## Call Signature
+
+```ts
+function mockOf<T>(options): MockProxy<T>;
+```
+
+Defined in: [src/model/doubles/mock-of.ts:28](https://github.com/jterrazz/package-test/blob/main/src/model/doubles/mock-of.ts#L28)
+
+A typed double for an injected port — the fourth rung of the doubles ladder
+(docs/18-conventions.md), and the only one a module test may build itself.
+
+The type argument is the port: `T` is constrained to `object` and has no
+default, so a double is always asked for something. A call with no argument
+answers for `object`, which satisfies no port and fails where it is used.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` *extends* `object` |
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | \{ `deep`: `false`; \} |
+| `options.deep` | `false` |
+
+### Returns
+
+`MockProxy`\<`T`\>
+
+### Example
+
+```ts
+const gateway = mockOf<PaymentGateway>();                // deep
+  const clock = mockOf<ClockPort>({ deep: false });        // flat
+```
+
+## Call Signature
+
+```ts
+function mockOf<T>(options?): DeepMockProxy<T>;
+```
+
+Defined in: [src/model/doubles/mock-of.ts:29](https://github.com/jterrazz/package-test/blob/main/src/model/doubles/mock-of.ts#L29)
+
+A typed double for an injected port — the fourth rung of the doubles ladder
+(docs/18-conventions.md), and the only one a module test may build itself.
+
+The type argument is the port: `T` is constrained to `object` and has no
+default, so a double is always asked for something. A call with no argument
+answers for `object`, which satisfies no port and fails where it is used.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` *extends* `object` |
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options?` | [`MockOfOptions`](../type-aliases/MockOfOptions.md) |
+
+### Returns
+
+`DeepMockProxy`\<`T`\>
+
+### Example
+
+```ts
+const gateway = mockOf<PaymentGateway>();                // deep
+  const clock = mockOf<ClockPort>({ deep: false });        // flat
+```

package/docs/reference/functions/postgres.md

@@ -0,0 +1,31 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Function: postgres()
+
+```ts
+function postgres(options?): PostgresHandle;
+```
+
+Defined in: [src/seams/postgres/postgres.ts:216](https://github.com/jterrazz/package-test/blob/main/src/seams/postgres/postgres.ts#L216)
+
+Create a PostgreSQL service handle.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | [`PostgresOptions`](../type-aliases/PostgresOptions.md) |
+
+## Returns
+
+`PostgresHandle`
+
+## Example
+
+```ts
+// The record key is the name: it is the spec's `database` vocabulary, and
+// Kebab-cased it is the folder the init script is read from.
+//   { db: postgres() }          → docker/db/init.sql, then docker/postgres/init.sql
+//   { analyticsDb: postgres() } → docker/analytics-db/init.sql
+const events = postgres();
+// After start: events.connectionString is populated
+```

package/docs/reference/functions/process.md

@@ -0,0 +1,33 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Function: process()
+
+```ts
+function process(options): ProcessHandle;
+```
+
+Defined in: [src/model/chain/process.ts:151](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L151)
+
+Declare an external process the framework owns for the life of the
+specification.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | [`ProcessOptions`](../type-aliases/ProcessOptions.md) |
+
+## Returns
+
+[`ProcessHandle`](../classes/ProcessHandle.md)
+
+## Example
+
+```ts
+const { website, cleanup } = await specification.website({
+      services: { api: process({ command: 'bin/server web', ready: '/health' }) },
+      server: ({ api }) => process({
+          command: 'next dev',
+          env: { NEXT_PUBLIC_API_URL: api.connectionString },
+      }),
+  });
+```

package/docs/reference/functions/redis.md

@@ -0,0 +1,28 @@
+<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
+# Function: redis()
+
+```ts
+function redis(options?): RedisHandle;
+```
+
+Defined in: [src/seams/redis/redis.ts:107](https://github.com/jterrazz/package-test/blob/main/src/seams/redis/redis.ts#L107)
+
+Create a Redis service handle.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | [`RedisOptions`](../type-aliases/RedisOptions.md) |
+
+## Returns
+
+`RedisHandle`
+
+## Example
+
+```ts
+// The record key is the name it reports under: { cache: redis() } → "cache".
+const cache = redis();
+// After start: cache.connectionString is populated
+```