@jterrazz/test 16.1.0 → 17.0.0

package/docs/reference/functions/defineContracts.md

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

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

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

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

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

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

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

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

package/docs/reference/functions/required.md

@@ -1,41 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Function: required()
-
-```ts
-function required<T>(value, why): T;
-```
-
-Defined in: [src/model/assertions/required.ts:15](https://github.com/jterrazz/package-test/blob/main/src/model/assertions/required.ts#L15)
-
-The value, or a failure that says what was missing and why it mattered.
-
-A test reaching into a captured structure — a row, a header, the third
-element of a list — meets `T | undefined` and has to do something about it.
-The two things it usually does are both wrong: `!` erases the question, and
-an `if (!x) throw new Error('missing')` re-states the same three lines in
-every repository (the estate had two hand-written copies of exactly this).
-`required` is that gesture with the reason attached, so the failure reads as
-a sentence rather than as a `TypeError` two frames further down.
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `value` | `T` \| `null` \| `undefined` |
-| `why` | `string` |
-
-## Returns
-
-`T`
-
-## Example
-
-```ts
-const id = required(result.response.body.id, 'the creation reply carries the new id');
-```

package/docs/reference/functions/selected.md

@@ -1,26 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Function: selected()
-
-```ts
-function selected(element): ElementRef;
-```
-
-Defined in: [src/model/elements/elements.ts:189](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L189)
-
-Which option the field is on: `see(selected(option('LinkedIn')))`, and
-`gone(selected(option('X')))` for the one it left.
-
-A modifier for the same reason as [disabled](disabled.md): being chosen is a state
-of an element the vocabulary already names. No matcher answers for it — a
-`<option>` is not a checkbox — so both adapters read the `:checked` the CSS
-spec gives a selected option.
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `element` | [`ElementRef`](../type-aliases/ElementRef.md) |
-
-## Returns
-
-[`ElementRef`](../type-aliases/ElementRef.md)

package/docs/reference/functions/sqlite.md

@@ -1,33 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Function: sqlite()
-
-```ts
-function sqlite(options?): SqliteHandle;
-```
-
-Defined in: [src/seams/sqlite/sqlite.ts:502](https://github.com/jterrazz/package-test/blob/main/src/seams/sqlite/sqlite.ts#L502)
-
-Create a SQLite service handle. Uses file-copy isolation for parallel tests.
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `options` | [`SqliteOptions`](../type-aliases/SqliteOptions.md) |
-
-## Returns
-
-`SqliteHandle`
-
-## Example
-
-```ts
-// With Prisma schema
-  const db = sqlite({ prismaSchema: './prisma/schema' });
-
-  // With raw SQL init
-  const db = sqlite({ init: './schema.sql' });
-
-  // Empty database
-  const db = sqlite();
-```

package/docs/reference/functions/testId.md

@@ -1,20 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Function: testId()
-
-```ts
-function testId(id): ElementRef;
-```
-
-Defined in: [src/model/elements/elements.ts:60](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L60)
-
-The escape hatch: an element by `data-testid`. Prefer user-facing elements.
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `id` | `string` |
-
-## Returns
-
-[`ElementRef`](../type-aliases/ElementRef.md)

package/docs/reference/functions/text.md

@@ -1,40 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Function: text()
-
-```ts
-function text(value): TextAccessor;
-```
-
-Defined in: [src/model/result/text-subject.ts:27](https://github.com/jterrazz/package-test/blob/main/src/model/result/text-subject.ts#L27)
-
-Wrap an arbitrary string into a [TextAccessor](../interfaces/TextAccessor.md) anchored on the calling
-test's directory — the same caller-detection the builders use.
-
-The product surface of a test framework is its own error messages, checker
-output, and reports; those deserve the same goldening as any other output.
-`text()` makes an ad-hoc string a first-class snapshot subject:
-
-```typescript
-const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
-expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to _expected/
-```
-
-ANSI is stripped before every comparison (the raw form stays on `.text`),
-the `{{token}}` grammar applies to the fixture, and `.grep()` composition
-works exactly as on any stream accessor.
-
-The ANCHOR is why this sits apart from the accessor it builds: reading the
-caller's frame means reading a stack and a real path, which is node's alone.
-[TextAccessor](../interfaces/TextAccessor.md) itself is a pure projection over a captured string, so
-it loads in a page — and the browser entry builds its own `text()`, where
-the golden commands resolve `_expected/` from the test's path server-side.
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `value` | `string` |
-
-## Returns
-
-[`TextAccessor`](../interfaces/TextAccessor.md)

package/docs/reference/functions/valued.md

@@ -1,28 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Function: valued()
-
-```ts
-function valued(element, value): ElementRef;
-```
-
-Defined in: [src/model/elements/elements.ts:201](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L201)
-
-What the field holds: `see(valued(field('Title'), 'Launch teaser'))`, and
-`gone(valued(field('Title'), '…'))` for a value it no longer holds.
-
-A modifier for the same reason as [disabled](disabled.md): what a field holds is a
-state of an element the vocabulary already names, and this is how the ONE
-field a test is about is waited for — a golden pins a whole outline instead.
-Read from the node's live value, never from the `value` ATTRIBUTE, which a
-controlled input never moves.
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `element` | [`ElementRef`](../type-aliases/ElementRef.md) |
-| `value` | `string` |
-
-## Returns
-
-[`ElementRef`](../type-aliases/ElementRef.md)

package/docs/reference/functions/waitUntil.md

@@ -1,46 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Function: waitUntil()
-
-```ts
-function waitUntil(predicate, options?): Promise<void>;
-```
-
-Defined in: [src/model/assertions/wait-until.ts:41](https://github.com/jterrazz/package-test/blob/main/src/model/assertions/wait-until.ts#L41)
-
-Wait until a condition holds — the sanctioned answer to "the thing I am
-specifying is not ready yet".
-
-A spec that sleeps for a guessed duration is a spec that is slow on a fast
-machine and flaky on a slow one, which is why J2 refuses `setTimeout` under
-`specs/`. Every facet that drives something already waits on a CONDITION —
-a served page, a banner on stdout, an element the visitor can see — and this
-is that primitive where no facet owns the waiting: a background write to
-land, a queue to drain, a file to appear.
-
-The failure names the condition and how long it was given, so a timeout is a
-sentence rather than "expected true, got false".
-
-The budget is measured on `performance.now()`, not on `Date` — `clock.at()`
-freezes the calendar, and a deadline read off a frozen calendar never
-arrives: the poll would run until vitest killed the test with a sentence
-about the file rather than about the condition.
-
-Not for a subject under `clock.run()`: there the scheduler is the test's, and
-`clock.advance(ms)` is what makes time pass.
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `predicate` | () => `boolean` \| `Promise`\<`boolean`\> |
-| `options` | [`WaitUntilOptions`](../type-aliases/WaitUntilOptions.md) |
-
-## Returns
-
-`Promise`\<`void`\>
-
-## Example
-
-```ts
-await waitUntil(() => outbox.length === 1, { why: 'the job wrote its one message' });
-```

package/docs/reference/functions/within.md

@@ -1,29 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Function: within()
-
-```ts
-function within(scope, target): ElementRef;
-```
-
-Defined in: [src/model/elements/elements.ts:114](https://github.com/jterrazz/package-test/blob/main/src/model/elements/elements.ts#L114)
-
-Restrict a descriptor to the inside of another — the answer to ambiguity,
-and the one the framework prefers over a test id.
-
-    click(within(navigation(), link('Articles')))
-
-Composes outside-in: the scope may itself be scoped, so a deeply nested
-target reads `within(main(), within(region('Series'), link('Part 2')))`.
-Any descriptor works as a scope, including `testId()` when a container has
-no landmark role to stand on.
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `scope` | [`ElementRef`](../type-aliases/ElementRef.md) |
-| `target` | [`ElementRef`](../type-aliases/ElementRef.md) |
-
-## Returns
-
-[`ElementRef`](../type-aliases/ElementRef.md)