@orkestrel/test 0.0.12 → 0.0.14

package/README.md

@@ -1,16 +1,13 @@
 # @orkestrel/test
 
-The test helpers the `@orkestrel` fleet kept rewriting, published once. A call recorder that is a
-real callback rather than a spy. A real host delay. A throw-to-value converter and a presence
-narrower, so `!` and `as` stay banned in tests. Two async collectors and a JSON copier. A frozen
-hostile-value corpus for proving guards are total. A cleanup list that gives every owned resource
-back, newest first. A scratch directory the test owns and destroys, a loopback port for a server the
-test built, and a symlink-refusing source-file walker. And the browser journey layer, which drives
-a real interface by role and accessible name through the installed Vitest provider. A helper ships
-here only when enough packages had already written their own; the guide's
-[Limits](guides/test.md#limits) section states that rule, what it excluded, and the one door the
-journey layer came through instead. Add it as a devDependency; nothing here runs in production
-code. Part of the `@orkestrel` line.
+> The test helpers the `@orkestrel` fleet kept rewriting, published once: families of what a test
+> records, what it waits for, and what it owns, with a pair outside all of them and a browser
+> journey layer beside them.
+
+Add it as a devDependency and import the core from `@orkestrel/test`. A helper ships here only when
+enough packages had already written their own; the guide's [Limits](guides/test.md#limits) section
+states that rule, what it excluded, and the one door the journey layer came through instead. Nothing
+here runs in production code. Part of the `@orkestrel` line.
 
 It has **zero runtime dependencies**, and no exported signature names an `@orkestrel/*` type. Both
 rules exist for one reason: a test helper hands its types straight into the consumer's assertions,
@@ -73,21 +70,27 @@ once, in its own setup, because registering it here would take a runtime depende
 runner. A handler that throws does not stop the run: one failure is rethrown by identity, so the
 test can assert on the value it threw, and several arrive as an `AggregateError` in run order.
 
-The rest of core is `collect` (drains an async iterable), `collectStream` (drains a
-`ReadableStream`), `roundTripJSON` (copies any value `JSONSafe` accepts, including an
-interface-typed one, and throws rather than turning a non-finite number into `null`), `resolveRoot`
-(the directory above the calling module, from `import.meta`), and `createHostileValues` (a frozen
-array of fresh values that each make a naive reader throw). Beside them sits the statechart
-contract the fleet repeats: `StateTransition` and `StateScenario` for one row of a transition table,
-`executeScenario` and `executeScenarios` to walk it, and `STATECHART_ATTRIBUTES` and
-`STATECHART_STATUSES` for the harness a browser workspace renders that table in.
+Core also carries the wait family (`waitForCondition`, `retryUntil`, `waitForEvent`, `waitForAbort`,
+and the leaves they share), the recorder map and the abort-signal instrument, the unchecked
+boundary, the header flattener, and the JSON Lines decoder — the guide's
+[Surface](guides/test.md#surface) section carries every export. Among them are `collect` (drains an
+async iterable), `collectStream` (drains a `ReadableStream`), `roundTripJSON` (copies any value
+`JSONSafe` accepts, including an interface-typed one, and throws rather than turning a non-finite
+number into `null`), `resolveRoot` (the directory above the calling module, from `import.meta`), and
+`createHostileValues` (a frozen array of fresh values that each make a naive read throw or violate a
+naive structural assumption). Beside them sits the statechart contract the fleet repeats:
+`StateTransition` and `StateScenario` for one row of a transition table, `executeScenario` and
+`executeScenarios` to walk it, and `STATECHART_ATTRIBUTES` and `STATECHART_STATUSES` for the harness
+a browser workspace renders that table in.
 
 The server face adds `readInventory`, which reads a checkout into a map of root-relative path to
 file text that a parity suite can assert against, and `createLoopback`, which binds a server the
-test built to an ephemeral loopback port. Behind `readInventory` and `createScratch` sit three pure
-leaves: `resolveContained`, the lexical check both refuse escapes with; `isExcluded`, the exclusion
-rule the walk applies; and `matchesIdentity`, the comparison `destroy()` makes before it removes
-anything.
+test built to an ephemeral loopback port. Behind them sit the pure leaves the server face also
+exports on its own: `readInventory` refuses an escape with `resolveContained` and prunes with
+`isExcluded`, while `createScratch` refuses one with `requireContained`, the throwing form, and
+reads and compares its allocation with `readIdentity` and `matchesIdentity` before `destroy()`
+removes anything. `createLink` and `removeTree` do the writing under it, and both decide on the
+errno `readErrorCode` reads off an unknown throw.
 
 ```ts
 import { resolveRoot } from '@orkestrel/test'
@@ -129,21 +132,22 @@ Object.keys(readInventory(root, ['src'], { extensions: ['.ts'], exclude: ['src/s
 //  'src/core/validators.ts']
 ```
 
-Keys are root-relative and `/`-separated whatever the host separator is, though this package's own
-suite runs on POSIX, where that conversion is an identity, so it proves the key shape and not the
-conversion. Keys are inserted in sorted order, and a plain object reads that order back for every
-key that is not integer-like.
+Keys are root-relative and `/`-separated whatever the host separator is. The suite gates that proof
+on a runtime reading of `node:path` rather than on a platform name, so it runs only where the host
+separator differs from `/`. Keys are inserted in sorted order, and a plain object reads that order
+back for every key that is not integer-like.
 
-Two boundaries are worth stating up front, because the two filesystem helpers promise different
-things. `createScratch` allocates its own directory at POSIX mode `0700` — under the host temporary
+`createScratch` and `readInventory` promise different things, and each boundary is worth stating up
+front. `createScratch` allocates its own directory at POSIX mode `0700` — under the host temporary
 directory, or under a `parent` you name — and refuses a path that lexically escapes it. The suite
-asserts those bits on POSIX and proves nothing about a host that emulates them. The mode keeps
-another uid out, and neither a sibling test worker nor the code under test is another uid. It does
-not walk segments for symbolic links. A link inside its own allocation was created by the test
-process, by the code the test drives, or by this package's own `link` — handing that code
-`scratch.path` is the ordinary use of this helper — and a contained path reaches outside the
-allocation through one. The guide's [traversal](guides/test.md#traversal) section states what each
-member does with a link it meets. Naming a `parent` inside a package tree costs one more thing:
+gates that assertion on `supportsMode`, the shipped probe that reads whether permission bits
+round-trip on this host, so it runs only where they do and claims nothing about a host that emulates
+them. The mode keeps another uid out, and neither a sibling test worker nor the code under test is
+another uid. It does not walk segments for symbolic links. A link inside its own allocation was
+created by the test process, by the code the test drives, or by this package's own `link` — handing
+that code `scratch.path` is the ordinary use of this helper — and a contained path reaches outside
+the allocation through one. The guide's [traversal](guides/test.md#traversal) section states what
+each member does with a link it meets. Naming a `parent` inside a package tree costs one more thing:
 while the allocation exists, everything that walks that tree sees it. `destroy()` is unaffected by
 where the allocation sits, because it matches the allocation's identity rather than its path. One
 field of that identity is the host's to supply: where a host reports no real creation time, libuv
@@ -203,8 +207,8 @@ rule deciding what ships and what stays in the package that owns it — see
 
 ## Package
 
-Published as three typed entry points per the `exports` field in `package.json`: `@orkestrel/test`
-for the host-independent core, `@orkestrel/test/browser` for the journey layer, and
+Published as typed entry points per the `exports` field in `package.json`: `@orkestrel/test` for the
+host-independent core, `@orkestrel/test/browser` for the journey layer, and
 `@orkestrel/test/server` for the Node helpers. Core and server ship ESM and CommonJS; the browser
 face ships ESM only, because `vitest/browser` is an ES-only module.
 

package/dist/src/browser/index.d.ts

@@ -1,3 +1,28 @@
+/**
+ * Loads only inside Vitest Browser Mode, where it drives a real browser through the installed
+ * provider.
+ *
+ * @remarks
+ * This entry imports `vitest/browser` at module scope, so importing it from a Node host throws at
+ * module load. That throw is the contract: it arrives at the import that caused it rather than
+ * inside the first helper call, and no Node host half-loads a surface whose every verb assumes the
+ * Browser Mode runner.
+ *
+ * A module that must load under Node as well reaches this entry through a dynamic import behind a
+ * DOM guard. A setup file that a Node project and a browser project both register is the case that
+ * needs it.
+ *
+ * @example
+ * ```ts
+ * let render: ((markup: string) => HTMLDivElement) | undefined
+ * if (typeof document !== 'undefined') {
+ * 	;({ render } = await import('@orkestrel/test/browser'))
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 /**
  * Names the interactive ARIA roles a bare accessible name is searched across.
  *
@@ -45,7 +70,7 @@ export declare function blendColor(front: Color, back: Color): Color;
 export declare function build<K extends keyof HTMLElementTagNameMap>(tag: K, options?: ElementOptions): HTMLElementTagNameMap[K];
 
 /**
- * Names the color a browser paints an unstyled document with.
+ * Names the color a browser paints an unstyled document with: opaque white.
  *
  * @remarks
  * This is the floor a backdrop walk ends on wherever the caller wants the browser's own canvas
@@ -144,7 +169,7 @@ export declare const CAPTURE_STAGINGS = 4;
  */
 export declare function captureFrame(options: FrameOptions): Promise<string>;
 
-/** Represents one theme-and-viewport pair a capture run renders. */
+/** Represents one theme-and-viewport pair a capture run renders, and the document change it needs first. */
 export declare interface CaptureVariant {
     /** Holds the variant's name, which is the second half of every filename the run writes. */
     readonly name: string;
@@ -496,7 +521,7 @@ export declare function describeFocus(element: Element): string;
 export declare function describeTree(element: Element): string;
 
 /**
- * Configures one built element.
+ * Configures one built element: its class list, its text, and its attributes.
  *
  * @remarks
  * `classes` is written the way a `class` attribute is written — one space-separated string — so a
@@ -668,7 +693,7 @@ export declare function findRule(selector: string): CSSStyleRule | undefined;
  */
 export declare const FOCUSABLE_SELECTOR = "a[href], area[href], button, input, select, summary, textarea, [tabindex]";
 
-/** Configures one captured frame. */
+/** Configures one captured frame: where it is written, the viewport it is shot at, and what it shoots. */
 export declare interface FrameOptions {
     /** Holds the frame's path, relative to the calling test file. */
     readonly path: string;
@@ -681,7 +706,8 @@ export declare interface FrameOptions {
 }
 
 /**
- * Represents one written frame, read back from the file a capture produced.
+ * Represents one written frame read back from the file a capture produced: its size in device
+ * pixels, and the single color its bottom row paints.
  *
  * @remarks
  * The floor is the frame's bottom row, because that row is where coverage shows: a frame shot at a
@@ -747,7 +773,7 @@ export declare const IMPLICIT_ROLES: Readonly<Record<string, string>>;
 export declare function isOutsideViewport(rectangle: DOMRectReadOnly): boolean;
 
 /**
- * Determines whether a person can click one element where it currently sits.
+ * Determines whether a person can click one element where it sits.
  *
  * @param element - The element to judge.
  * @returns True if the element is connected, visible, laid out with a non-zero box, in the
@@ -833,6 +859,8 @@ export declare interface JournalInterface {
      * @param action - What the run did, as one verb.
      * @param trigger - The exact thing it did it to.
      * @param result - What was observed on the surface after the step landed.
+     * @remarks The appended step is frozen. A step taken before `start` or after `stop` is not
+     * recorded at all.
      */
     record(action: string, trigger: string, result: string): void;
 }
@@ -1043,7 +1071,10 @@ export declare interface PortfolioInterface {
     place(state: string, element?: Element): Promise<string | undefined>;
 }
 
-/** Configures a capture portfolio. */
+/**
+ * Configures a capture portfolio: the state registry, the variant matrix, this run's variant, where
+ * it writes, and whether it writes at all.
+ */
 export declare interface PortfolioOptions {
     /**
      * Lists every state name the journeys place, declared once. `place` refuses a name absent from
@@ -1063,19 +1094,6 @@ export declare interface PortfolioOptions {
     readonly enabled?: boolean;
 }
 
-/**
- * Presses a browser-keyboard sequence using Vitest's installed user-event syntax.
- *
- * @param keys - The keys or key descriptors to press.
- * @returns A promise resolving after the sequence completes.
- *
- * @example
- * ```ts
- * await pressKeys('{ArrowRight}{Enter}')
- * ```
- */
-export declare function pressKeys(keys: string): Promise<void>;
-
 /**
  * Resolves the opaque color standing behind one element.
  *
@@ -1194,7 +1212,7 @@ export declare function readClasses(root: ParentNode): ReadonlySet<string>;
 export declare function readContrast(element: Element, floor?: Color): number;
 
 /**
- * Reads the rendered text of the element that currently holds focus.
+ * Reads the rendered text of the element that holds focus.
  *
  * @returns The focused HTML element's trimmed rendered text, including an empty string, or
  * `undefined` when focus rests on a non-HTML element. When nothing holds focus, the browser
@@ -1357,9 +1375,9 @@ export declare function readPixels(element: Element, property: string): number;
  *
  * @remarks
  * This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
- * `pressKeys`, a real click — and this measures what the browser painted once it landed. A control
- * that is not matching `:focus-visible` when the call is made reports nothing, because no
- * measurement taken then would be about focus.
+ * `userEvent.keyboard` from `vitest/browser`, a real click — and this measures what the browser
+ * painted once it landed. A control that is not matching `:focus-visible` when the call is made
+ * reports nothing, because no measurement taken then would be about focus.
  *
  * Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
  * beside the label that carries every pixel of its chrome is the case `worn` exists for, so a
@@ -1632,32 +1650,47 @@ export declare function releasePane(): Promise<void>;
 export declare function removeDatabase(name: string): Promise<void>;
 
 /**
- * Renders one fixture into the document, from trusted markup or from a tag and its classes.
+ * Renders one fixture into the document from trusted markup.
  *
- * @param first - The fixture markup, or the HTML tag name when `second` is present.
- * @param second - The class list when `first` supplies the tag name.
- * @returns The attached container for the markup form, and the attached element itself for the tag
- * form.
+ * @param markup - The fixture markup to parse.
+ * @returns The attached container holding the fixture's own nodes.
  *
  * @remarks
  * The class list is required in the tag form, which is what keeps the two forms apart: a
- * one-argument call is always markup. A tag with no classes is `mount(build(tag))`.
+ * one-argument call is always markup.
  *
- * The markup form parses `first` into a fresh container and returns that container, so the fixture's
- * own nodes are its children. The tag form returns the element itself, typed as exactly that tag.
- * Both attach to `document.body` and neither records anything, so removal is the caller's, exactly
- * as it is for {@link mount}.
+ * This form parses `markup` into a fresh container and returns that container, so the fixture's own
+ * nodes are its children. It attaches to `document.body` and records nothing, so removal is the
+ * caller's, exactly as it is for {@link mount}.
  *
  * @example
  * ```ts
  * const container = render('<button type="button">Save</button>')
- * const panel = render('section', 'surface muted')
  * container.remove()
- * panel.remove()
  * ```
  */
 export declare function render(markup: string): HTMLDivElement;
 
+/**
+ * Renders one fixture into the document from a tag name and its class list.
+ *
+ * @param tag - The HTML tag name to create.
+ * @param classes - The class list to place on the created element.
+ * @returns The attached element itself, typed as exactly that tag.
+ *
+ * @remarks
+ * The class list is required in the tag form, which is what keeps the two forms apart: a
+ * one-argument call is always markup. A tag with no classes is `mount(build(tag))`.
+ *
+ * This form returns the element itself rather than a container. It attaches to `document.body` and
+ * records nothing, so removal is the caller's, exactly as it is for {@link mount}.
+ *
+ * @example
+ * ```ts
+ * const panel = render('section', 'surface muted')
+ * panel.remove()
+ * ```
+ */
 export declare function render<K extends keyof HTMLElementTagNameMap>(tag: K, classes: string): HTMLElementTagNameMap[K];
 
 /**
@@ -1744,7 +1777,7 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
  * therefore unscaled and lifted to the window's own origin for the shot. The `iframe[data-vitest]`
  * selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
  * `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
- * them reddens the size check below rather than writing a wrong frame.
+ * them reddens the size check that follows rather than writing a wrong frame.
  *
  * Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
  * the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
@@ -1797,6 +1830,10 @@ export declare function traverseAccessible(name: string): Promise<HTMLElement>;
  * @param text - The text to type.
  * @returns A promise resolving after every keystroke completes.
  *
+ * @remarks
+ * The text is escaped against the provider's own key syntax, so a literal `{` or `[` is typed
+ * rather than read as the start of a key sequence.
+ *
  * @example
  * ```ts
  * await typeAccessible('Runs', '3')

package/dist/src/browser/index.js

@@ -27,7 +27,7 @@ var ACCESSIBLE_ROLES = Object.freeze([
 	"treeitem"
 ]);
 /**
-* Names the color a browser paints an unstyled document with.
+* Names the color a browser paints an unstyled document with: opaque white.
 *
 * @remarks
 * This is the floor a backdrop walk ends on wherever the caller wants the browser's own canvas
@@ -207,7 +207,7 @@ function isOutsideViewport(rectangle) {
 	return rectangle.bottom <= 0 || rectangle.right <= 0 || rectangle.top >= window.innerHeight || rectangle.left >= window.innerWidth;
 }
 /**
-* Determines whether a person can click one element where it currently sits.
+* Determines whether a person can click one element where it sits.
 *
 * @param element - The element to judge.
 * @returns True if the element is connected, visible, laid out with a non-zero box, in the
@@ -435,6 +435,10 @@ async function clickDisclosure(name) {
 * @param text - The text to type.
 * @returns A promise resolving after every keystroke completes.
 *
+* @remarks
+* The text is escaped against the provider's own key syntax, so a literal `{` or `[` is typed
+* rather than read as the start of a key sequence.
+*
 * @example
 * ```ts
 * await typeAccessible('Runs', '3')
@@ -466,20 +470,6 @@ async function fillAccessible(name, text) {
 	await userEvent.fill(resolveRendered(name), text);
 }
 /**
-* Presses a browser-keyboard sequence using Vitest's installed user-event syntax.
-*
-* @param keys - The keys or key descriptors to press.
-* @returns A promise resolving after the sequence completes.
-*
-* @example
-* ```ts
-* await pressKeys('{ArrowRight}{Enter}')
-* ```
-*/
-async function pressKeys(keys) {
-	await userEvent.keyboard(keys);
-}
-/**
 * Reaches a named control only through natural forward Tab traversal from the current focus.
 *
 * @param name - The target's exact accessible name.
@@ -580,7 +570,7 @@ function readPage() {
 	return document.body.innerText.replaceAll(/\s+/g, " ").trim();
 }
 /**
-* Reads the rendered text of the element that currently holds focus.
+* Reads the rendered text of the element that holds focus.
 *
 * @returns The focused HTML element's trimmed rendered text, including an empty string, or
 * `undefined` when focus rests on a non-HTML element. When nothing holds focus, the browser
@@ -1329,9 +1319,9 @@ function readContrast(element, floor) {
 *
 * @remarks
 * This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
-* `pressKeys`, a real click — and this measures what the browser painted once it landed. A control
-* that is not matching `:focus-visible` when the call is made reports nothing, because no
-* measurement taken then would be about focus.
+* `userEvent.keyboard` from `vitest/browser`, a real click — and this measures what the browser
+* painted once it landed. A control that is not matching `:focus-visible` when the call is made
+* reports nothing, because no measurement taken then would be about focus.
 *
 * Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
 * beside the label that carries every pixel of its chrome is the case `worn` exists for, so a
@@ -1756,7 +1746,7 @@ function measureContent() {
 * therefore unscaled and lifted to the window's own origin for the shot. The `iframe[data-vitest]`
 * selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
 * `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
-* them reddens the size check below rather than writing a wrong frame.
+* them reddens the size check that follows rather than writing a wrong frame.
 *
 * Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
 * the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
@@ -2256,6 +2246,6 @@ function createJournal() {
 	};
 }
 //#endregion
-export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, blendColor, build, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, createChannel, createDragEvent, createJournal, createPointerEvent, createPortfolio, describeFocus, describeTree, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, pressKeys, readBackdrop, readCascade, readClasses, readContrast, readFocus, readFrame, readLayers, readName, readPage, readPerception, readPixels, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releasePane, removeDatabase, render, resolveAccessible, resolveRendered, stagePane, traverseAccessible, typeAccessible, typeInput, waitForFrame };
+export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, blendColor, build, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, createChannel, createDragEvent, createJournal, createPointerEvent, createPortfolio, describeFocus, describeTree, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, readBackdrop, readCascade, readClasses, readContrast, readFocus, readFrame, readLayers, readName, readPage, readPerception, readPixels, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releasePane, removeDatabase, render, resolveAccessible, resolveRendered, stagePane, traverseAccessible, typeAccessible, typeInput, waitForFrame };
 
 //# sourceMappingURL=index.js.map