@orkestrel/test 0.0.4 → 0.0.6

package/README.md

@@ -3,11 +3,14 @@
 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 scratch directory the test owns and destroys,
-and a symlink-refusing source-file walker. 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 and what it excluded. Add it as a
-devDependency; nothing here runs in production code. Part of the `@orkestrel` line.
+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.
 
 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,
@@ -26,15 +29,25 @@ npm install -D @orkestrel/test
 
 ## Usage
 
-`@orkestrel/test` is the host-independent core. `@orkestrel/test/server` is the Node face. Core
-touches neither `node:*` nor the DOM, so a browser test project imports it unchanged.
+`@orkestrel/test` is the host-independent core. `@orkestrel/test/server` is the Node face.
+`@orkestrel/test/browser` is the journey layer, which drives a real browser through the installed
+Vitest provider. Core touches neither `node:*` nor the DOM, so a browser test project imports it
+unchanged.
 
 ```ts
-import { captureError, createRecorder, requireValue, waitForDelay } from '@orkestrel/test'
+import {
+	captureError,
+	createRecorder,
+	createTeardown,
+	requireValue,
+	waitForDelay,
+} from '@orkestrel/test'
 import { createScratch } from '@orkestrel/test/server'
 
-// A temporary directory the test owns, seeded with the input under test.
+// A cleanup list the test adds to as it goes, and a temporary directory seeded with the input.
+const teardown = createTeardown()
 const scratch = createScratch({ prefix: 'loader-', files: { 'input.txt': 'hello' } })
+teardown.add(() => scratch.destroy()) // idempotent, and it removes only the directory it allocated
 
 // A real callback, not a spy: hand `handler` to the code under test.
 const recorder = createRecorder<[path: string]>()
@@ -52,19 +65,26 @@ captureError(() => loader.read('missing.txt')) // the thrown value, or undefined
 requireValue(scratch.read('input.txt')) // 'hello' — narrows `string | undefined` without `!`
 
 scratch.remove('input.txt') // one contained entry, subtree and all; a missing target is a no-op
-scratch.destroy() // idempotent, and it removes only the directory it allocated
+await teardown.destroy() // newest registration first, and every handler runs even after one throws
 ```
 
+The list registers no hook of its own. The consumer writes `afterEach(() => teardown.destroy())`
+once, in its own setup, because registering it here would take a runtime dependency on the test
+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`), and
-`resolveRoot` (the directory above the calling module, from `import.meta`).
+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).
 
 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, plus the three pure leaves behind it and
-`createScratch`: `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.
+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.
 
 ```ts
 import { resolveRoot } from '@orkestrel/test'
@@ -125,6 +145,44 @@ leaves the root through a link in the middle, and skips a symlink met while walk
 sandbox against hostile filesystem content: those refusals stop accidental escape, not an adversary
 who can create hard links where the test process already writes.
 
+The browser face is the journey layer: an accessible-name resolver with exact failure voices,
+region and disclosure targeting, input and traversal verbs, perception readers, a WCAG contrast
+instrument that composites translucent layers, and the capture portfolio. Every acting verb
+resolves its own target from a role and an accessible name — none takes an element, a component
+instance, or a selector — and the whole environment imports `vitest/browser` and DOM globals and
+nothing else, with `vitest` declared as a peer dependency. The guide's
+[Browser](guides/test.md#browser) section carries every export and every voice.
+
+`createLoopback` binds a server the test built. The caller constructs it and keeps every route,
+header, and status on it; this package supplies the bind and the release and nothing else.
+
+```ts
+import { createServer } from 'node:http'
+import { createLoopback } from '@orkestrel/test/server'
+
+const server = createServer((_request, response) => {
+	response.end('ok')
+})
+
+const loopback = await createLoopback(server)
+
+loopback.port // the number the host assigned; this package neither picks a port nor reserves one
+loopback.url // `http://127.0.0.1:${loopback.port}` — IPv4 loopback, no trailing slash
+
+const response = await fetch(loopback.url) // a real request, answered by the caller's own server
+await response.text() // 'ok'
+
+await loopback.destroy() // drops every live connection, then closes; idempotent
+```
+
+It listens on port `0` at `127.0.0.1`, so the host assigns the number and the address is IPv4
+loopback rather than `::1`, which a host resolving `localhost` can hand back instead. The scheme in
+`url` is spelled `http` unconditionally, so a TLS server's origin is `port` plus a scheme the caller
+writes. `destroy()` drops live connections on a server that carries `closeAllConnections` — both
+`node:http`'s and `node:https`'s do — so a keep-alive client cannot hold the port past the test that
+opened it. A plain `node:net` server has no such method, so `destroy()` waits for its open sockets
+to end.
+
 ## Guide
 
 For the full surface — every export, the behavioral contract each one holds to, and the measured
@@ -133,9 +191,10 @@ rule deciding what ships and what stays in the package that owns it — see
 
 ## Package
 
-Published as two typed entry points per the `exports` field in `package.json`: `@orkestrel/test` for
-the host-independent core, `@orkestrel/test/server` for the Node helpers. Both ship ESM and
-CommonJS.
+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
+`@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.
 
 ## License
 

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

@@ -0,0 +1,478 @@
+/**
+ * The interactive ARIA roles a bare accessible name is searched across.
+ *
+ * @remarks
+ * A person names a control, not a role, so the one-argument resolver searches every role a control
+ * can compute. The two-argument form searches exactly the role it is given, which is how a name
+ * shared by a tab and its panel is disambiguated.
+ */
+export declare const ACCESSIBLE_ROLES: readonly string[];
+
+/** One theme-and-viewport pair a capture run renders. */
+export declare interface CaptureVariant {
+    /** The variant's name, which is the second half of every filename the run writes. */
+    readonly name: string;
+    /** The viewport width in pixels. */
+    readonly width: number;
+    /** The viewport height in pixels. */
+    readonly height: number;
+    /**
+     * The document change this variant needs before the viewport is resized — a theme attribute, a
+     * density class, a language direction. Omit it when the variant is a viewport alone.
+     */
+    readonly apply?: () => void;
+}
+
+/**
+ * Clicks one visible, focus-reachable control by its accessible name through the browser provider.
+ *
+ * @param name - The target's exact accessible name.
+ * @returns A promise resolving after trusted activation completes.
+ *
+ * @example
+ * ```ts
+ * await clickAccessible('Apply')
+ * ```
+ */
+export declare function clickAccessible(name: string): Promise<void>;
+
+/**
+ * Clicks one visible, focus-reachable control by its exact ARIA role and accessible name,
+ * disambiguating a bare name that answers for more than one rendered element.
+ *
+ * @param role - The control's exact ARIA role.
+ * @param name - The target's exact accessible name.
+ * @returns A promise resolving after trusted activation completes.
+ *
+ * @example
+ * ```ts
+ * await clickAccessible('tab', 'Drafts')
+ * ```
+ */
+export declare function clickAccessible(role: string, name: string): Promise<void>;
+
+/**
+ * Clicks one human-reachable control by role and accessible-name text inside a named region.
+ *
+ * @param region - The containing region's exact accessible name.
+ * @param role - The control's exact ARIA role.
+ * @param name - The rendered accessible-name text that identifies the control in that region.
+ * @returns A promise resolving after trusted activation completes.
+ * @throws When the named control is absent, unreachable, or ambiguous inside the region.
+ *
+ * @remarks
+ * Use this form when repeated short verbs such as `Add`, or a line whose status completes its
+ * accessible name, need the same region context a person uses to disambiguate them.
+ *
+ * @example
+ * ```ts
+ * await clickAccessibleWithin('Ledger', 'button', 'Monthly income')
+ * ```
+ */
+export declare function clickAccessibleWithin(region: string, role: string, name: string): Promise<void>;
+
+/**
+ * Opens or closes one native details disclosure by its rendered summary.
+ *
+ * @param name - The summary text a person reads.
+ * @returns A promise resolving after trusted activation completes.
+ * @throws When no visible, focus-reachable native summary has that rendered name, or several do.
+ *
+ * @remarks
+ * Chromium exposes `<summary>` as a native disclosure rather than through an ARIA role accepted by
+ * `getByRole`, so this resolver names the platform element and its rendered text directly.
+ *
+ * @example
+ * ```ts
+ * await clickDisclosure('Advanced')
+ * ```
+ */
+export declare function clickDisclosure(name: string): Promise<void>;
+
+/**
+ * Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.
+ *
+ * @param element - The element whose rendered text contrast to measure.
+ * @returns The relative-luminance contrast ratio.
+ * @throws When the browser does not expose parseable computed colors.
+ *
+ * @remarks
+ * A transparent or translucent background resolves through the element's ancestors: every painted
+ * layer from the element up to the first opaque one composites top-over-bottom onto that opaque
+ * base, so a 3% surface tint reads as a tint over what shows through it rather than as a
+ * full-strength paint. A translucent foreground then resolves against that effective background
+ * before luminance is measured.
+ *
+ * Every element from the target upwards must be reachable, and at least one of them must paint:
+ * the measurement throws rather than assuming a white canvas when nothing in the chain declares a
+ * background color. The element itself must expose a computed foreground color — a detached
+ * element exposes none, and the measurement throws rather than guessing one.
+ *
+ * @example
+ * ```ts
+ * const container = render('<p style="background: #000; color: #fff">Ready</p>')
+ * contrast(requireValue(container.firstElementChild)) // 21
+ * ```
+ */
+export declare function contrast(element: Element): number;
+
+/**
+ * Creates the capture portfolio one run places its screenshots through.
+ *
+ * @param options - The state registry, the variant matrix, the variant this run renders, the
+ * directory it writes into, and whether it writes at all.
+ * @returns The portfolio: its registry expansion, what it has placed, and `place`.
+ * @throws When no registered variant carries the name `variant` names.
+ *
+ * @remarks
+ * A disabled portfolio is the ordinary run. `place` then resizes nothing, writes nothing, and
+ * records nothing, so a journey calls it unconditionally and a suite with the flag unset pays for
+ * none of it. The portfolio refuses an unregistered variant at creation. An enabled run refuses an
+ * unregistered state name and a second placement of one state.
+ *
+ * @example
+ * ```ts
+ * const portfolio = createPortfolio({
+ * 	states: ['start-empty'],
+ * 	variants: [{ name: 'dark-390', width: 390, height: 844 }],
+ * 	variant: 'dark-390',
+ * 	directory: '../../tmp/capture/states',
+ * })
+ * await portfolio.place('start-empty')
+ * ```
+ */
+export declare function createPortfolio(options: PortfolioOptions): PortfolioInterface;
+
+/**
+ * Expands a capture registry across every variant into the filenames a complete portfolio holds.
+ *
+ * @param states - The registered state names.
+ * @param variants - The variants the portfolio is rendered in.
+ * @returns One `<state>--<variant>.png` name per pair, each state's variants together, in registry
+ * order.
+ *
+ * @remarks
+ * The expansion is the portfolio's own definition of complete, so a duplicate in it is a registry
+ * defect a proof reads directly rather than a collision discovered on disk.
+ *
+ * @example
+ * ```ts
+ * expandCaptures(['start'], [{ name: 'dark-390', width: 390, height: 844 }])
+ * // ['start--dark-390.png']
+ * ```
+ */
+export declare function expandCaptures(states: readonly string[], variants: readonly CaptureVariant[]): readonly string[];
+
+/**
+ * Replaces a named field's value in one operation, for text too long to type key by key.
+ *
+ * @param name - The field's exact accessible name.
+ * @param text - The text to place in the field.
+ * @returns A promise resolving after the browser commits the value.
+ *
+ * @remarks
+ * The provider drives the real element, so the field publishes the same input event a person's
+ * typing publishes. Use {@link typeAccessible} wherever the keystrokes themselves are the subject.
+ *
+ * @example
+ * ```ts
+ * await fillAccessible('Payload', '{"status":"ready"}')
+ * ```
+ */
+export declare function fillAccessible(name: string, text: string): Promise<void>;
+
+/**
+ * Determines whether a rectangle lies wholly outside the browser viewport.
+ *
+ * @param rectangle - The measured client rectangle to inspect.
+ * @returns `true` when no part of the rectangle intersects the viewport.
+ *
+ * @example
+ * ```ts
+ * isOutsideViewport(element.getBoundingClientRect())
+ * ```
+ */
+export declare function isOutsideViewport(rectangle: DOMRectReadOnly): boolean;
+
+/** The registry of capture states one run places, and the files it wrote placing them. */
+export declare interface PortfolioInterface {
+    /** The name of the variant this run renders. */
+    readonly variant: string;
+    /** Every state placed so far, in placement order. */
+    readonly states: readonly string[];
+    /** Every path written so far, in write order. */
+    readonly paths: readonly string[];
+    /** The registry expanded across every variant: the filenames a complete portfolio holds. */
+    readonly files: readonly string[];
+    /**
+     * Places one registered state: applies the variant, resizes the viewport, and writes the
+     * screenshot.
+     *
+     * @param state - The state name from the registry.
+     * @returns The written path, or `undefined` when the portfolio is not enabled.
+     * @throws When the state is not registered or has already been placed.
+     */
+    place(state: string): Promise<string | undefined>;
+}
+
+/** Options for a capture portfolio. */
+export declare interface PortfolioOptions {
+    /**
+     * Every state name the journeys place, declared once. `place` refuses a name absent from this
+     * list, so the registry and the disk cannot drift apart.
+     */
+    readonly states: readonly string[];
+    /** Every variant the portfolio can be rendered in. One run renders exactly one of them. */
+    readonly variants: readonly CaptureVariant[];
+    /** The name of the variant this run renders. Creation throws when no variant carries it. */
+    readonly variant: string;
+    /** The directory each written file is placed in, relative to the calling test file. */
+    readonly directory: string;
+    /**
+     * Whether this run writes files. An ordinary run leaves it unset, so `place` resizes nothing,
+     * writes nothing, and records nothing.
+     */
+    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>;
+
+/**
+ * Collects every class token the stylesheets loaded into this document actually define.
+ *
+ * @returns The set of class names reachable in the shipped cascade.
+ *
+ * @remarks
+ * The set is what an authored-class conformance check measures against, so a class no loaded
+ * stylesheet defines — an invented utility, a misspelled framework name — is absent from it.
+ *
+ * @example
+ * ```ts
+ * readCascade().has('card')
+ * ```
+ */
+export declare function readCascade(): ReadonlySet<string>;
+
+/**
+ * Reads the rendered text of the element that currently 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
+ * reports the document body as active, so the whole page's rendered text returns.
+ *
+ * @example
+ * ```ts
+ * await traverseAccessible('Evaluate')
+ * readFocus() // 'Evaluate'
+ * ```
+ */
+export declare function readFocus(): string | undefined;
+
+/**
+ * Reads the normalized visible text of the whole page.
+ *
+ * @returns Every rendered word in the document body, its whitespace runs collapsed and trimmed.
+ *
+ * @remarks
+ * This is the reader for a sentence that spans two regions and for a vocabulary sweep over the
+ * words an interface uses. Reach for {@link readPerception} wherever one named region is the
+ * subject, because that one throws when the region is missing and this one returns whatever is
+ * there.
+ *
+ * @example
+ * ```ts
+ * readPage().includes('No cases yet')
+ * ```
+ */
+export declare function readPage(): string;
+
+/**
+ * Reads the normalized visible text of one named region, dialog, table, tab panel, or alert.
+ *
+ * @param name - The region's exact accessible name.
+ * @returns The text a screen reader can perceive in the visible region, including descendant
+ * visually-hidden content.
+ * @throws When the named region is absent, hidden, or ambiguous.
+ *
+ * @example
+ * ```ts
+ * readPerception('Run')
+ * ```
+ */
+export declare function readPerception(name: string): string;
+
+/**
+ * Reads the normalized visible text of every element a selector matches, in document order.
+ *
+ * @param root - The subtree to search.
+ * @param selector - The CSS selector naming the rows.
+ * @returns One line per matched element, its text runs collapsed and single-space joined.
+ *
+ * @remarks
+ * The line is built from the row's text nodes rather than from `textContent`, because adjacent
+ * inline elements carry no whitespace between them in compiled template output and would otherwise
+ * read as one run-together word.
+ *
+ * @example
+ * ```ts
+ * readRows(container, 'li')
+ * ```
+ */
+export declare function readRows(root: ParentNode, selector: string): readonly string[];
+
+/**
+ * Reads the value a resolved control renders.
+ *
+ * @param role - The control's exact ARIA role.
+ * @param name - The control's exact accessible name.
+ * @returns The control's current value.
+ * @throws When the target does not resolve, or resolves to an element that carries no value.
+ *
+ * @remarks
+ * A control's value is a rendered fact a person can read, not internal state, so it is read from
+ * the resolved element rather than from the component that produced it.
+ *
+ * @example
+ * ```ts
+ * readValue('spinbutton', 'Runs') // '3'
+ * ```
+ */
+export declare function readValue(role: string, name: string): string;
+
+/**
+ * Renders trusted fixture markup into a container attached to the document.
+ *
+ * @param markup - The fixture markup to render.
+ * @returns The attached container.
+ *
+ * @example
+ * ```ts
+ * const container = render('<button type="button">Save</button>')
+ * container.remove()
+ * ```
+ */
+export declare function render(markup: string): HTMLDivElement;
+
+/**
+ * Resolves one visible, focus-reachable interactive element by its exact accessible name. A
+ * wholly-off-viewport target is scrolled into view before reachability is measured.
+ *
+ * @param name - The accessible name rendered for the target.
+ * @returns The one reachable element carrying that name.
+ * @throws When no matching element exists; every match is disconnected, hidden, zero-sized, still
+ * outside the viewport after being scrolled into view, removed from sequential focus, disabled, or
+ * inside an inert subtree; or several reachable matches make the name ambiguous.
+ *
+ * @example
+ * ```ts
+ * resolveAccessible('Save changes')
+ * ```
+ */
+export declare function resolveAccessible(name: string): HTMLElement;
+
+/**
+ * Resolves one visible, focus-reachable interactive element by its exact ARIA role and accessible
+ * name, disambiguating a bare name that answers for more than one rendered element. A
+ * wholly-off-viewport target is scrolled into view before reachability is measured.
+ *
+ * @param role - The element's exact ARIA role.
+ * @param name - The accessible name rendered for the target.
+ * @returns The one reachable element carrying that role and name.
+ * @throws When no matching element exists; every match is disconnected, hidden, zero-sized, still
+ * outside the viewport after being scrolled into view, removed from sequential focus, disabled, or
+ * inside an inert subtree; or several reachable matches make the role/name pair ambiguous.
+ *
+ * @example
+ * ```ts
+ * resolveAccessible('tab', 'Drafts')
+ * ```
+ */
+export declare function resolveAccessible(role: string, name: string): HTMLElement;
+
+/**
+ * Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
+ * viewport yet.
+ *
+ * @param first - The accessible name, or the exact ARIA role when `second` is present.
+ * @param second - The accessible name when `first` supplies the role.
+ * @returns The one rendered element carrying that name and optional role.
+ * @throws When no matching element exists, every match is hidden or unreachable, or several
+ * rendered matches make the name ambiguous.
+ *
+ * @remarks
+ * This is the resolver the acting verbs use, so a click does not fail on a target the act itself
+ * scrolls into view. Use {@link resolveAccessible} wherever the target must already be on screen.
+ *
+ * @example
+ * ```ts
+ * resolveRendered('tab', 'Drafts')
+ * ```
+ */
+export declare function resolveRendered(first: string, second?: string): HTMLElement;
+
+/**
+ * Reads one resolved CSS property from a real browser element.
+ *
+ * @param element - The element whose resolved style to inspect.
+ * @param property - The CSS property name.
+ * @returns The browser's resolved property value.
+ *
+ * @example
+ * ```ts
+ * style(button, 'padding-left')
+ * ```
+ */
+export declare function style(element: Element, property: string): string;
+
+/**
+ * Reaches a named control only through natural forward Tab traversal from the current focus.
+ *
+ * @param name - The target's exact accessible name.
+ * @returns The target after the browser moves focus to it.
+ * @throws When one complete traversal cannot reach the target.
+ *
+ * @example
+ * ```ts
+ * await traverseAccessible('Evaluate')
+ * ```
+ */
+export declare function traverseAccessible(name: string): Promise<HTMLElement>;
+
+/**
+ * Replaces a named field's value through focus, select-all, deletion, and real keystrokes.
+ *
+ * @param name - The field's exact accessible name.
+ * @param text - The text to type.
+ * @returns A promise resolving after every keystroke completes.
+ *
+ * @example
+ * ```ts
+ * await typeAccessible('Runs', '3')
+ * ```
+ */
+export declare function typeAccessible(name: string, text: string): Promise<void>;
+
+/**
+ * Waits for one animation frame to settle pending browser paint work.
+ *
+ * @returns A promise resolving after one `requestAnimationFrame`.
+ *
+ * @example
+ * ```ts
+ * await waitForFrame()
+ * ```
+ */
+export declare function waitForFrame(): Promise<void>;
+
+export { }