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