Documentation navigation

Published API · 0.1.0-rc.1

foldkit · scene

Published foldkit API declarations for scene.

./scene

@wsagency/wseffect-foldkit · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit/scene'

Exported declarations

all

Multi-match Locator factories. Each returns a `LocatorAll` that resolves to every matching VNode. Convert to a single `Locator` via `first`, `last`, or `nth(n)`, or narrow via `filter`.

all: {
    readonly role: typeof allRole;
    readonly text: typeof allText;
    readonly label: typeof allLabel;
    readonly placeholder: typeof allPlaceholder;
    readonly altText: typeof allAltText;
    readonly title: typeof allTitle;
    readonly testId: typeof allTestId;
    readonly displayValue: typeof allDisplayValue;
    readonly selector: typeof allSelector;
}

altText

Creates a Locator that finds an element by its `alt` attribute.

altText: (altValue: string) => Locator

AnyCommand

A Command in a test simulation. Carries `name` and optionally the `args` the runtime captured at construction. Instance matchers (Command values produced by calling a Definition) are matched against this shape; the `effect` field on a real Command is irrelevant for matching, so we only retain `name + args`. `messageMappers` is the Command's message-mapping chain (from `Command.mapMessage`/`mapMessages`). It rides along on pending Commands so `resolve` can apply the parent's wrapping to a substitute result Message without the test restating it. Absent on synthetic matchers built for formatting; treated as empty then. `key` is present on Commands built with an interruptible `Command.define`: such Commands may stay pending across Messages (they model long-running work). `interruptsKey` is present on Interrupt Commands: resolving one drops every pending Command holding that key, mirroring the runtime guarantee that an interrupted Command's result Message never dispatches.

export type AnyCommand = Readonly<{
    name: string;
    args?: Record<string, unknown>;
    key?: string;
    interruptsKey?: string;
    messageMappers?: ReadonlyArray<(message: unknown) => unknown>;
}>;

AnyMount

A Mount lifecycle event in a test simulation. Carries `name` and optionally the `args` used to construct the MountAction. Mirrors `AnyCommand` for Mount matchers.

export type AnyMount = Readonly<{
    name: string;
    args?: Record<string, unknown>;
}>;

attr

Reads an attribute or prop value from a VNode.

attr: {
    (vnode: VNode, name: string): Option.Option<string>;
    (name: string): (vnode: VNode) => Option.Option<string>;
}

beforeInput

Simulates a `beforeinput` event on the element matching the target. Drives `OnBeforeInput` and `OnBeforeInputPreventDefault`. Pass the edit's `inputType` (e.g. `'insertText'`, `'deleteContentBackward'`) and its `data` as an `Option` (the inserted text, or `None` for edits that carry none). Dual: `beforeInput(target, inputType, data)` or `beforeInput(inputType, data)` for data-last piping.

beforeInput: {
    (target: string | Locator, inputType: string, data: Option.Option<string>): <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    (inputType: string, data: Option.Option<string>): (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
}

blur

Simulates a blur event on the element matching the target.

blur: (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

change

Simulates a change event on the element matching the target. Dual: `change(target, value)` or `change(value)` for data-last piping.

change: {
    (target: string | Locator, value: string): <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    (value: string): (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
}

changeFiles

Simulates a file input change event on the element matching the target. For use with `OnFileChange` attributes. The handler receives a synthetic event with `target.files` set to the provided files array. Dual: `changeFiles(target, files)` or `changeFiles(files)` for data-last piping.

changeFiles: {
    (target: string | Locator, files: ReadonlyArray<File>): <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    (files: ReadonlyArray<File>): (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
}

click

Simulates a click on the element matching the target. Runs click handlers from the target through its ancestors until one stops propagation, mirroring browser event propagation. When the target activates a submit button and no click handler prevents the default, the click falls through to the `submit` handler of its form owner. Scene honors an explicit `form` attribute before looking for the nearest ancestor `<form>`.

click: (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

Command

Steps that operate on the pending Commands of a scene simulation. Destructure as `const { Command } = Scene` for concise call sites.

Command: {
    /** Resolves a specific pending Command with the given result Message. */
    readonly resolve: {
        <Name extends string, ResultMessage>(definition: ResolvableCommandDefinition<Name, ResultMessage>, resultMessage: ResultMessage): <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        <ResultMessage>(instance: AnyCommandInstance<ResultMessage>, resultMessage: ResultMessage): <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    };
    /** Resolves listed Commands with their result Messages, cascading through any
     *  Commands the result produces. Each entry resolves exactly one matching
     *  dispatch in declaration order; compose with `Array.makeBy` for N
     *  identical responses. Resolvers carry across calls; a new entry replaces
     *  any leftovers sharing its Definition or Instance shape (latest wins). */
    readonly resolveAll: typeof resolveAllCommands;
    /** Resolves listed Commands and throws unless every resolver matches one
     *  dispatch and no actual Commands remain unresolved. Entries apply only to
     *  this call and never carry forward. */
    readonly resolveAllExact: typeof resolveAllExactCommands;
    /** Asserts that every given Command is among the pending Commands. */
    readonly expectHas: typeof expectHasCommandsStep;
    /** Asserts that the pending Commands match the given definitions exactly (order-independent). */
    readonly expectExact: typeof expectExactCommandsStep;
    /** Asserts that there are no pending Commands. */
    readonly expectNone: typeof expectNoCommandsStep;
}

contextMenu

Simulates a contextmenu event on the element matching the target. When the element has no contextmenu handler, the event bubbles up to the nearest ancestor with one, mirroring browser event propagation.

contextMenu: (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

CustomElement

Steps that model CustomEvents arriving from a rendered custom element. Destructure as `const { CustomElement } = Scene` for concise call sites.

CustomElement: {
    /** Dispatches a declared CustomEvent through the element's event mapping.
     *  The event name and detail are typed by the spec's event Schemas. */
    readonly emit: typeof emitCustomElementEvent;
}

displayValue

Creates a Locator that finds a form control by its current `value`.

displayValue: (valueString: string) => Locator

doubleClick

Simulates a double-click on the element matching the target. When the element has no dblclick handler, the event bubbles up to the nearest ancestor with one, mirroring browser event propagation.

doubleClick: (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

dropFiles

Simulates a drop event with files on the element matching the target. For use with `OnDropFiles` attributes. The handler receives a synthetic event with `dataTransfer.files` set to the provided files array and a no-op `preventDefault`. Dual: `dropFiles(target, files)` or `dropFiles(files)` for data-last piping.

dropFiles: {
    (target: string | Locator, files: ReadonlyArray<File>): <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    (files: ReadonlyArray<File>): (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
}

expect

expect_: (locator: Locator) => {
    toExist: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toBeAbsent: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toHaveText: (expected: string | RegExp) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toContainText: (expected: string | RegExp) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toHaveAttr: (name: string, value?: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toHaveClass: (expected: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toHaveStyle: (name: string, value?: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toHaveHook: (name: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toHaveHandler: (name: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toHaveValue: (expected: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toBeDisabled: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toBeEnabled: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toBeEmpty: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toBeVisible: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toHaveId: (expected: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toHaveAccessibleName: (expected: string | RegExp) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toHaveAccessibleDescription: (expected: string | RegExp) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toBeChecked: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    not: {
        toExist: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toBeAbsent: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toHaveText: (expected: string | RegExp) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toContainText: (expected: string | RegExp) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toHaveAttr: (name: string, value?: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toHaveClass: (expected: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toHaveStyle: (name: string, value?: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toHaveHook: (name: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toHaveHandler: (name: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toHaveValue: (expected: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toBeDisabled: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toBeEnabled: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toBeEmpty: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toBeVisible: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toHaveId: (expected: string) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toHaveAccessibleName: (expected: string | RegExp) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toHaveAccessibleDescription: (expected: string | RegExp) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toBeChecked: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    };
}

expectAll

Creates an inline multi-match assertion step. Use for count-based assertions like `toHaveCount(n)` or `toBeEmpty()`.

expectAll: (locatorAll: LocatorAll) => {
    toHaveCount: (expected: number) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    toBeEmpty: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    not: {
        toHaveCount: (expected: number) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
        toBeEmpty: () => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    };
}

expectHandled

expectHandled: () => <Model, Message, OutMessage>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

expectIgnored

expectIgnored: () => <Model, Message, OutMessage>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

expectNoOutMessage

Asserts that the latest update-producing Scene step emitted no OutMessages.

expectNoOutMessage: () => <Model, Message, OutMessage>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

expectOutMessage

Asserts by structural equality that the latest update-producing Scene step emitted exactly the expected OutMessage.

expectOutMessage: <OutMessage>(expected: OutMessage) => OutMessageStep<OutMessage>

expectOutMessages

Asserts by structural equality that the latest update-producing Scene step emitted two or more expected OutMessages in runtime order.

expectOutMessages: <Expected extends readonly [unknown, unknown, ...ReadonlyArray<unknown>]>(...expected: Expected) => OutMessagesStep<Expected[number]>

filter

Filters a LocatorAll's matches. Supports `has`/`hasNot` to keep entries that do/don't contain a matching descendant, and `hasText`/`hasNotText` to keep entries whose text content does/doesn't include a substring.

filter: {
    (locatorAll: LocatorAll, options: FilterOptions): LocatorAll;
    (options: FilterOptions): (locatorAll: LocatorAll) => LocatorAll;
}

find

Finds the first VNode matching the CSS selector.

find: {
    (html: VNode, selectorString: string): Option.Option<VNode>;
    (selectorString: string): (html: VNode) => Option.Option<VNode>;
}

findAll

Finds all VNodes matching the CSS selector.

findAll: {
    (html: VNode, selectorString: string): ReadonlyArray<VNode>;
    (selectorString: string): (html: VNode) => ReadonlyArray<VNode>;
}

first

Picks the first match from a LocatorAll, producing a single-match Locator.

first: (locatorAll: LocatorAll) => Locator

focus

Simulates a focus event on the element matching the target.

focus: (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

focusEnter

Simulates focus entering the subtree of the element matching the target.

focusEnter: (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

focusLeave

Simulates focus leaving the subtree of the element matching the target.

focusLeave: (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

getAllByAltText

Finds all elements with the given `alt` attribute.

getAllByAltText: (altValue: string) => (html: VNode) => ReadonlyArray<VNode>

getAllByDisplayValue

Finds all form controls whose current value matches.

getAllByDisplayValue: (displayValueString: string) => (html: VNode) => ReadonlyArray<VNode>

getAllByLabel

Finds every element with the given label text. Applies the same four resolution strategies as `getByLabel` (`aria-label`, `<label for="id">`, `<label>` nesting, `aria-labelledby`) and returns deduplicated matches.

getAllByLabel: (labelValue: string) => (html: VNode) => ReadonlyArray<VNode>

getAllByPlaceholder

Finds all elements with the given placeholder attribute.

getAllByPlaceholder: (placeholderValue: string) => (html: VNode) => ReadonlyArray<VNode>

getAllByRole

Finds all elements with the given ARIA role and optional matching options.

getAllByRole: (role: string, options?: RoleOptions) => (html: VNode) => ReadonlyArray<VNode>

getAllByTestId

Finds all elements with the given `data-testid` attribute.

getAllByTestId: (testIdValue: string) => (html: VNode) => ReadonlyArray<VNode>

getAllByText

Finds every element whose text matches `target`. Uses the same string and `RegExp` rules as `getByText`, but returns matching ancestors and descendants in traversal order. Never returns text VNodes.

getAllByText: (target: string | RegExp, options?: Readonly<{
    exact?: boolean;
}>) => (html: VNode) => ReadonlyArray<VNode>

getAllByTitle

Finds all elements with the given `title` attribute.

getAllByTitle: (titleValue: string) => (html: VNode) => ReadonlyArray<VNode>

getByAltText

Finds the first element with the given `alt` attribute.

getByAltText: (altValue: string) => (html: VNode) => Option.Option<VNode>

getByDisplayValue

Finds the first form control whose current value matches. Checks the `value` attribute on inputs, textareas, and selects.

getByDisplayValue: (displayValue: string) => (html: VNode) => Option.Option<VNode>

getByLabel

Finds the first element with the given label text. Checks `aria-label` first, then `<label for="id">` association, then `<label>` nesting, then `aria-labelledby` reverse lookup.

getByLabel: (labelValue: string) => (html: VNode) => Option.Option<VNode>

getByPlaceholder

Finds the first element with the given placeholder attribute.

getByPlaceholder: (placeholderValue: string) => (html: VNode) => Option.Option<VNode>

getByRole

Finds the first element with the given ARIA role and optional matching options. Supports `name` (accessible name), `level` (heading level), `checked`, `selected`, `pressed`, `expanded`, `disabled`, and `current` state filters.

getByRole: (role: string, options?: RoleOptions) => (html: VNode) => Option.Option<VNode>

getByTestId

Finds the first element with the given `data-testid` attribute.

getByTestId: (testIdValue: string) => (html: VNode) => Option.Option<VNode>

getByText

Finds the first element whose text matches `target`. A string matches the element's full text or one direct text node. When `exact` is false, it instead matches a substring of the full text. A `RegExp` tests the full text from index zero without changing its `lastIndex`, and `exact` has no effect. When an ancestor and descendant both match, the query returns the descendant. Never returns text VNodes.

getByText: (target: string | RegExp, options?: Readonly<{
    exact?: boolean;
}>) => (html: VNode) => Option.Option<VNode>

getByTitle

Finds the first element with the given `title` attribute.

getByTitle: (titleValue: string) => (html: VNode) => Option.Option<VNode>

given

Sets the initial Model for a scene test.

given: <Model>(model: Model) => GivenStep<Model>

hover

Simulates a hover (mouseenter) on the element matching the target. Dispatches the `mouseenter` handler, falling back to `mouseover`.

hover: (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

inside

Scopes a sequence of steps to a parent element. Every Locator referenced by child steps (assertions, interactions) resolves within the parent's subtree. Use this when several steps share the same scope. For a single scoped query, prefer `within(parent, child)` directly. Nested `inside` calls compose scopes via `within(outer, inner)`.

inside: <Model, Message, OutMessage = undefined>(parent: Locator, ...steps: ReadonlyArray<NoInfer<SceneStep<Model, Message, OutMessage>>>) => (simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

keydown

Simulates a keydown event on the element matching the target. The event is self-targeted (`target === currentTarget`), so `OnKeyDownSelf` and `OnKeyDownSelfPreventDefault` handlers fire. Dual: `keydown(target, key, modifiers?)` or `keydown(key, modifiers?)` for data-last piping.

keydown: {
    (target: string | Locator, key: string): <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    (target: string | Locator, key: string, modifiers: Partial<KeyboardModifiers>): <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    (key: string): (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    (key: string, modifiers: Partial<KeyboardModifiers>): (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
}

label

Creates a Locator that finds an element by aria-label.

label: (labelValue: string) => Locator

last

Picks the last match from a LocatorAll, producing a single-match Locator.

last: (locatorAll: LocatorAll) => Locator

Locator

A deferred element query that resolves against a VNode tree. Callable as a function (`locator(html)`) so it composes directly in `flow` and `pipe` chains. Used by interaction steps (`click`, `type`, `submit`, `keydown`) to target elements by accessible attributes instead of CSS selectors.

export type Locator = ((html: VNode) => Option.Option<VNode>) & Readonly<{
    description: string;
}>;

LocatorAll

A deferred multi-element query that resolves to all matching VNodes. Produced by `all*` locator factories and by `filter(...)`. Convert to a single-match `Locator` via `first`, `last`, or `nth(n)`.

export type LocatorAll = ((html: VNode) => ReadonlyArray<VNode>) & Readonly<{
    description: string;
}>;

ManagedResource

Steps that model the lifecycle Messages of a ManagedResource. The test declares the lifecycle outcome the way `Scene.Command.resolve` declares a Command result, and each step checks the current Model against the entry's `modelToMaybeRequirements` gate first, mirroring the runtime's None to Some and Some to None transitions. The Some to Some re-acquire transition has no step yet. Destructure as `const { ManagedResource } = Scene` for concise call sites.

ManagedResource: {
    /** Declares a successful acquire, feeding the entry's `onAcquired` Message
     *  through update. Takes exactly the arguments `onAcquired` declares. The
     *  current Model must request the resource. */
    readonly acquire: typeof acquireManagedResource;
    /** Declares a failed acquire, feeding `onAcquireError(error)` through
     *  update. The current Model must request the resource. */
    readonly failAcquire: typeof failAcquireManagedResource;
    /** Declares a release, feeding `onReleased()` through update. The current
     *  Model must no longer request the resource. */
    readonly release: typeof releaseManagedResource;
}

Mount

Steps that operate on the pending Mounts of a scene simulation. Destructure as `const { Mount } = Scene` for concise call sites.

Mount: {
    /** Resolves a specific pending Mount with the given result Message. */
    readonly resolve: <Name extends string, ResultMessage>(matcher: MountDefinition<Name, ResultMessage> | AnyMount, resultMessage: ResultMessage) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    /** Resolves all listed Mounts with their result Messages. */
    readonly resolveAll: typeof resolveAllMounts;
    /** Asserts that every given Mount is among the pending Mounts. */
    readonly expectHas: typeof expectHasMountsStep;
    /** Asserts that the pending Mounts match the given definitions exactly (order-independent, by name). */
    readonly expectExact: typeof expectExactMountsStep;
    /** Asserts that there are no pending Mounts. */
    readonly expectNone: typeof expectNoMountsStep;
    /** Acknowledges Mounts that disappeared from the rendered tree. Required for
     *  every Mount that fires and then unmounts during a scene. */
    readonly expectEnded: typeof expectEndedMountsStep;
}

MountMatcher

Pattern for matching a pending Mount in test assertions. A Definition matches by name only ("a Mount with this identity is in the rendered tree"); an Instance matches by name AND structural-equal args ("a Mount with this identity AND these args"). Choose the form per assertion based on whether the test cares about the args value. Two modes only: name-only or name + full args. Partial-args matching is intentionally unsupported, mirroring `CommandMatcher`.

export type MountMatcher = MountDefinition<string, unknown> | AnyMount;

MountResolver

A Mount matcher (Definition or Instance) paired with the raw result Message to resolve it with. Mirrors `Resolver` for Commands. When the mount lives inside a Submodel, the boundary's own `toParentMessage` chain (snapshotted at render time) is applied to the result, so pass the child's raw result Message, not a parent-wrapped one.

export type MountResolver<ResultMessage = unknown> = readonly [
    MountMatcher,
    ResultMessage
];

nth

Picks the nth match (0-indexed) from a LocatorAll, producing a Locator.

nth: {
    (locatorAll: LocatorAll, index: number): Locator;
    (index: number): (locatorAll: LocatorAll) => Locator;
}

OutMessagesStep

A typed OutMessage sequence assertion step.

export type OutMessagesStep<OutMessage> = Readonly<{
    _tag: 'OutMessagesStep';
    expected: readonly [OutMessage, OutMessage, ...ReadonlyArray<OutMessage>];
}>;

OutMessageStep

A typed OutMessage assertion step.

export type OutMessageStep<OutMessage> = Readonly<{
    _tag: 'OutMessageStep';
    expected: OutMessage;
}>;

PendingMount

A pending Mount in a Scene simulation. Identified by `name` and an `occurrence` index that disambiguates same-named mounts in the rendered tree (e.g. two open popovers each contributing an `AnchorPopover`). The occurrence is the 0-based position among same-named markers in tree-traversal order. `args` carries the runtime values used to construct the MountAction when its definition declared an args record.

export type PendingMount = Readonly<{
    name: string;
    args?: Record<string, unknown>;
    occurrence: number;
    messageMappers?: ReadonlyArray<(message: unknown) => unknown>;
}>;

placeholder

Creates a Locator that finds an element by placeholder attribute.

placeholder: (placeholderValue: string) => Locator

pointerDown

Simulates a pointerdown event on the element matching the target. When the element has no pointerdown handler, the event bubbles up to the nearest ancestor with one, mirroring browser event propagation. The `OnPointerDown` callback receives a detached element representing the target and its ancestors, so `closest()` checks work in Scene tests. Defaults to `pointerType: 'mouse'`, `button: 0`, `screenX/screenY: 0`, `clientX/clientY: 0`, and `pointerId: 0`.

pointerDown: (target: string | Locator, options?: PointerDownOptions) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

pointerUp

Simulates a pointerup event on the element matching the target. When the element has no pointerup handler, the event bubbles up to the nearest ancestor with one, mirroring browser event propagation. Defaults to `pointerType: 'mouse'` and `screenX/screenY: 0`.

pointerUp: (target: string | Locator, options?: PointerUpOptions) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

Resolver

A Command matcher (Definition or Instance) paired with the raw result Message to resolve a pending Command with. Definition matchers resolve by name; an Instance matcher resolves only the pending Command whose name AND args match. The matched Command's own message-mapping chain is applied to the result, so pass the child's raw result Message, not a parent-wrapped one. The result Message must belong to the matched Command.

export type Resolver<Matcher extends ResolvableCommandMatcher = ResolvableCommandMatcher> = readonly [Matcher, ResultMessageForMatcher<Matcher>];

role

Creates a Locator that finds an element by ARIA role. Supports matching on `name`, `level`, `checked`, `selected`, `pressed`, `expanded`, `disabled`, and `current`. For `current`, `true` matches `aria-current="true"` only, `false` matches a missing attribute or `aria-current="false"`, and a token such as `'page'` matches itself.

role: (roleValue: string, options?: RoleOptions) => Locator

scene

Executes a scene test. Throws if any Commands or Mounts remain unresolved, any unmount is unacknowledged, or any interaction fell through unacknowledged.

scene: {
    <Model, Message, OutMessage = never>(config: Readonly<{
        update: (model: Model, message: Message) => Readonly<{
            model: Model;
            commands?: ReadonlyArray<AnyCommand>;
            outMessage?: OutMessage;
        }>;
        view: (model: Model, h: HtmlBuilder<Message>) => Html | Document;
    }>, ...steps: ReadonlyArray<SceneStep<NoInfer<Model>, NoInfer<Message>, NoInfer<OutMessage>>>): void;
    <Model, Message>(config: Readonly<{
        update: (model: Model, message: Message) => Readonly<{
            model: Model;
            commands?: ReadonlyArray<AnyCommand>;
            outMessage?: never;
        }>;
        view: (model: Model, h: HtmlBuilder<Message>) => Html | Document;
    }>, ...steps: ReadonlyArray<SceneStep<NoInfer<Model>, NoInfer<Message>, undefined>>): void;
}

sceneMatchers

Custom Vitest matchers for scene testing. Register with `expect.extend(Scene.sceneMatchers)`.

sceneMatchers: {
    toHaveText(received: Option.Option<VNode>, expected: string | RegExp): {
        pass: boolean;
        message: () => string;
    } | {
        pass: boolean;
        message: () => string;
    };
    toContainText(received: Option.Option<VNode>, expected: string | RegExp): {
        pass: boolean;
        message: () => string;
    } | {
        pass: boolean;
        message: () => string;
    };
    toHaveClass(received: Option.Option<VNode>, expected: string): {
        pass: boolean;
        message: () => string;
    } | {
        pass: boolean;
        message: () => string;
    };
    toHaveAttr(received: Option.Option<VNode>, name: string, expectedValue?: string): {
        pass: boolean;
        message: () => string;
    } | {
        pass: boolean;
        message: () => string;
    };
    toExist(received: Option.Option<VNode>): {
        pass: boolean;
        message: () => "Expected element not to exist but it does." | "Expected element to exist but it does not.";
    };
    toBeAbsent(received: Option.Option<VNode>): {
        pass: boolean;
        message: () => "Expected element not to be absent but it is." | "Expected element to be absent but it exists.";
    };
    toHaveStyle(received: Option.Option<VNode>, name: string, expectedValue?: string): {
        pass: boolean;
        message: () => string;
    } | {
        pass: boolean;
        message: () => string;
    };
    toHaveHook(received: Option.Option<VNode>, name: string): {
        pass: boolean;
        message: () => string;
    } | {
        pass: boolean;
        message: () => string;
    };
    toHaveHandler(received: Option.Option<VNode>, name: string): {
        pass: boolean;
        message: () => string;
    } | {
        pass: boolean;
        message: () => string;
    };
    toHaveValue(received: Option.Option<VNode>, expected: string): {
        pass: boolean;
        message: () => string;
    } | {
        pass: false;
        message: () => string;
    } | {
        pass: boolean;
        message: () => string;
    };
    toBeDisabled(received: Option.Option<VNode>): {
        pass: boolean;
        message: () => "Expected element to be disabled but the element does not exist.";
    } | {
        pass: boolean;
        message: () => "Expected element not to be disabled but it is." | "Expected element to be disabled but it is not.";
    };
    toBeEnabled(received: Option.Option<VNode>): {
        pass: boolean;
        message: () => "Expected element to be enabled but the element does not exist.";
    } | {
        pass: boolean;
        message: () => "Expected element not to be enabled but it is." | "Expected element to be enabled but it is disabled.";
    };
    toBeEmpty(received: Option.Option<VNode>): {
        pass: boolean;
        message: () => "Expected element to be empty but the element does not exist.";
    } | {
        pass: boolean;
        message: () => string;
    };
    toBeVisible(received: Option.Option<VNode>): {
        pass: boolean;
        message: () => "Expected element to be visible but the element does not exist.";
    } | {
        pass: boolean;
        message: () => "Expected element not to be visible but it is." | "Expected element to be visible but it is hidden.";
    };
    toHaveId(received: Option.Option<VNode>, expected: string): {
        pass: boolean;
        message: () => string;
    } | {
        pass: false;
        message: () => string;
    } | {
        pass: boolean;
        message: () => string;
    };
    toBeChecked(received: Option.Option<VNode>): {
        pass: boolean;
        message: () => "Expected element to be checked but the element does not exist.";
    } | {
        pass: boolean;
        message: () => "Expected element not to be checked but it is." | "Expected element to be checked but it is not.";
    };
}

SceneSimulation

An immutable test simulation that includes the rendered VNode tree. The Model and Message are intentionally opaque. Scene tests assert through the view, not the model. Use Story for model-level assertions.

export type SceneSimulation<Model, Message, OutMessage = undefined> = Readonly<{
    /** @internal Phantom type that preserves Model and Message for step chain inference. */
    _phantom: [Model, Message];
    commands: ReadonlyArray<AnyCommand>;
    mounts: ReadonlyArray<PendingMount>;
    /** The sole OutMessage from the latest update-producing Scene step.
     *  Undefined when that step emitted none or more than one. */
    outMessage: OutMessage | undefined;
    html: VNode;
}>;

SceneStep

A single step in a scene: a `given` step, typed Message or OutMessage step, or scene simulation transform.

export type SceneStep<Model, Message, OutMessage> = GivenStep<NoInfer<Model>> | Readonly<{
    _tag: 'SubscriptionMessageStep';
    message: NoInfer<Message>;
}> | Readonly<{
    _tag: 'OutMessageStep';
    expected: NoInfer<OutMessage>;
}> | Readonly<{
    _tag: 'OutMessagesStep';
    expected: readonly [
        NoInfer<OutMessage>,
        NoInfer<OutMessage>,
        ...ReadonlyArray<NoInfer<OutMessage>>
    ];
}> | ((simulation: SceneSimulation<any, any, any>) => SceneSimulation<any, any, any>);

selector

Creates a Locator from the supported CSS selector subset. Use this escape hatch when no accessible Locator is available. Supports tag names, `#id`, `.class`, `[attr]`, `[attr="value"]`, `[attr^="prefix"]`, `:not(<compound selector>)`, and descendant combinators. Attribute values may use double or single quotes and may contain whitespace. Any other syntax throws.

selector: (css: string) => Locator

submit

Simulates form submission on the element matching the target.

submit: (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

Subscription

Steps that model Messages arriving from a Subscription. Destructure as `const { Subscription } = Scene` for concise call sites.

Subscription: {
    /** Feeds a Message through update as if a Subscription had emitted it,
     *  then re-renders. Only for Messages whose real cause is a Subscription;
     *  if the Message has a DOM affordance, click it instead. */
    readonly emit: typeof emitSubscriptionMessage;
}

SubscriptionMessageStep

A typed Subscription Message step.

export type SubscriptionMessageStep<Message> = Readonly<{
    _tag: 'SubscriptionMessageStep';
    message: Message;
}>;

tap

Runs a function for side effects (e.g. assertions) without breaking the step chain.

tap: <Model, Message, OutMessage = undefined>(f: (simulation: SceneSimulation<Model, Message, OutMessage>) => void) => (simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>

testId

Creates a Locator that finds an element by its `data-testid` attribute.

testId: (testIdValue: string) => Locator

text

Creates a Locator that finds the same element as `getByText`.

text: (target: string | RegExp, options?: Readonly<{
    exact?: boolean;
}>) => Locator

textContent

Extracts all text content from a VNode tree, depth-first.

textContent: (vnode: VNode) => string

title

Creates a Locator that finds an element by its `title` attribute.

title: (titleValue: string) => Locator

type

type_: {
    (target: string | Locator, value: string): <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    (value: string): (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
}

typeContentEditable

Simulates typing into a contenteditable host matching the target. A contenteditable element has no `value`, so the `input` event reports the host's rendered text. Use this to drive `OnInput` on a `Contenteditable` element. Dual: `typeContentEditable(target, text)` or `typeContentEditable(text)` for data-last piping.

typeContentEditable: {
    (target: string | Locator, text: string): <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
    (text: string): (target: string | Locator) => <Model, Message, OutMessage = undefined>(simulation: SceneSimulation<Model, Message, OutMessage>) => SceneSimulation<Model, Message, OutMessage>;
}

within

Creates a scoped Locator that finds the child within the parent. Composes via `Option.flatMap` — the parent is resolved first, then the child is searched within the parent's subtree.

within: {
    (parent: Locator, child: Locator): Locator;
    (child: Locator): (parent: Locator) => Locator;
}

withViewInputs

Adapts a Submodel view that declares `ViewInputs` to the `(model, h)` shape `Scene.scene` takes. `defaults` supplies the full `ViewInputs` once; the returned factory accepts per-test overrides for everything except `toView`, so tests vary value inputs while the renderer stays pinned: ```ts const sceneView = Scene.withViewInputs(view, { value: 5, toView: testToView, }) Scene.scene({ update, view: sceneView() }, ...) Scene.scene({ update, view: sceneView({ isDisabled: true }) }, ...) ```

withViewInputs: <Model, Message, ViewInputs extends object>(view: (model: Model, viewInputs: ViewInputs, h: HtmlBuilder<Message>) => Html, defaults: NoInfer<ViewInputs>) => (overrides?: Omit<Partial<NoInfer<ViewInputs>>, 'toView'>) => (model: Model, h: HtmlBuilder<Message>) => Html