Skip to main content

Class: StorybookInteractor

Defined in: storybook/src/StorybookInteractor.ts:45

Interactor for driving component drivers inside a real-browser Storybook — play functions in the Storybook UI and stories run under @storybook/addon-vitest.

Framework-agnostic by design: in a real browser every renderer commits to real DOM asynchronously on its own schedule, so unlike ReactInteractor / VueInteractor there is no act() / nextTick() wrapping (React's act() is not supported outside a configured test environment and only emits warnings in the preview iframe). Instead, every mutating interaction is followed by StorybookInteractor.settle, and read-after-write races are further covered by the escalating waitUntil cadence.

Interactions dispatch through Storybook's instrumented userEvent (from storybook/test), so they are recorded in the Interactions panel.

Extends​

  • DOMInteractor

Constructors​

Constructor​

new StorybookInteractor(canvasElement): StorybookInteractor

Defined in: storybook/src/StorybookInteractor.ts:50

Parameters​

canvasElement​

HTMLElement

The story's canvas element (from the play context); every locator resolves within it.

Returns​

StorybookInteractor

Overrides​

DOMInteractor.constructor

Methods​

activate()​

activate(locator): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:153

Activate the element matched by the locator without pointer geometry.

Uses userEvent.click, which ignores layout and coordinates, so it reaches a visually-hidden or covered input that a positional click would miss (e.g. MUI Rating's hidden <input type="radio">).

Parameters​

locator​

PartLocator

Locator used to find the target element

Returns​

Promise<void>

Promise resolved once the element has been activated

Throws​

If the element is not found

Overrides​

DOMInteractor.activate

blur()​

blur(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:138

Remove focus from the element found by the locator.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<BlurOption>

Returns​

Promise<void>

Promise resolved when blur has been applied

Throws​

If the element is not found

Overrides​

DOMInteractor.blur

click()​

click(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:88

Dispatch a click event on the element that matches the locator.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<ClickOption>

Optional click configuration such as the click position

Returns​

Promise<void>

A promise that resolves after the event is triggered

Throws​

If the element is not found

Overrides​

DOMInteractor.click

contextMenu()​

contextMenu(locator): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:148

Dispatch a contextmenu (right-click) event on the element matched by the locator.

The element is focused first if focusable, mirroring pressKey, so the event originates from the active element as a real right-click would. A context menu has no aria-expanded/controlled-open path, so this dispatched event is the only way to exercise the menu-opening behavior.

Parameters​

locator​

PartLocator

Locator used to find the target element

Returns​

Promise<void>

Promise resolved once the event has been dispatched

Throws​

If the element is not found

Overrides​

DOMInteractor.contextMenu

drag()​

drag(locator, delta): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:183

Drag the located element by the given pixel delta from its center.

The sequence (mousedown at center → mousemove at center + delta → mouseup at center + delta) is synthesized with the shared dispatchMouse + calculateMousePosition pattern, using the caller-supplied delta for the move/up coordinates. jsdom has no layout, so the center resolves to zeros and only the event wiring is exercised — the behavioral outcome of the drag is E2E-only.

Only raw mouse events are fired; native HTML5 drag-and-drop is NOT synthesized — see #922.

Parameters​

locator​

PartLocator

Locator used to find the element to drag

delta​

Point

Pixel offset to drag by

Returns​

Promise<void>

Throws​

If the element is not found

Overrides​

DOMInteractor.drag

dragTo()​

dragTo(source, target): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:178

Drag the source element and drop it onto the target element.

The pointer sequence (mousedown on source → mousemove on target → mouseup on target) is synthesized with the shared dispatchMouse + calculateMousePosition pattern. jsdom has no layout, so those coordinates are all zeros — the event wiring (and any drop handler the sequence triggers) is exercised, but the positional outcome is E2E-only.

Only raw mouse events are fired; native HTML5 drag-and-drop (dragstart/dragover/drop + dataTransfer) is NOT synthesized, so components built on the HTML5 DnD API are not driven by this — see #922.

Parameters​

source​

PartLocator

Locator used to find the element to drag

target​

PartLocator

Locator used to find the drop target

Returns​

Promise<void>

Throws​

If either element is not found

Overrides​

DOMInteractor.dragTo

enterText()​

enterText(locator, text, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:73

Type text into the element matched by the locator.

Parameters​

locator​

PartLocator

Locator used to find the target element

text​

string

The string to type

option?​

Partial<EnterTextOption>

Options such as appending or replacing existing value

Returns​

Promise<void>

Promise resolved when typing has completed

Throws​

If the element is not found

Overrides​

DOMInteractor.enterText

focus()​

focus(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:133

Move focus to the element found by the locator.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<FocusOption>

Returns​

Promise<void>

Promise resolved when focus has been applied

Throws​

If the element is not found

Overrides​

DOMInteractor.focus

hover()​

hover(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:93

Move the mouse over the element.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<HoverOption>

Returns​

Promise<void>

A promise that resolves after the hover event

Throws​

If the element is not found

Overrides​

DOMInteractor.hover

mouseDown()​

mouseDown(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:103

Dispatch a mousedown event on the target element.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<MouseDownOption>

Allows specifying the mouse position relative to the element

Returns​

Promise<void>

Promise resolved when the event is dispatched

Throws​

If the element is not found

Overrides​

DOMInteractor.mouseDown

mouseEnter()​

mouseEnter(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:123

Dispatch a mouseenter event on the target element.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<MouseEnterOption>

Returns​

Promise<void>

Promise resolved after the event dispatches

Throws​

If the element is not found

Overrides​

DOMInteractor.mouseEnter

mouseLeave()​

mouseLeave(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:128

Dispatch a mouseleave event on the target element.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<MouseLeaveOption>

Returns​

Promise<void>

Promise resolved once the event is dispatched

Throws​

If the element is not found

Overrides​

DOMInteractor.mouseLeave

mouseMove()​

mouseMove(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:98

Dispatch a mousemove event on the target element.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<MouseMoveOption>

Allows specifying the mouse position relative to the element

Returns​

Promise<void>

A promise that resolves once the event has been dispatched

Throws​

If the element is not found

Overrides​

DOMInteractor.mouseMove

mouseOut()​

mouseOut(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:118

Dispatch a mouseout event on the target element.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<MouseOutOption>

Returns​

Promise<void>

Promise resolved once the event is dispatched

Throws​

If the element is not found

Overrides​

DOMInteractor.mouseOut

mouseOver()​

mouseOver(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:113

Dispatch a mouseover event on the target element.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<HoverOption>

Optional mouse position relative to the element

Returns​

Promise<void>

Promise resolved once the event is dispatched

Throws​

If the element is not found

Overrides​

DOMInteractor.mouseOver

mouseUp()​

mouseUp(locator, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:108

Dispatch a mouseup event on the target element.

Parameters​

locator​

PartLocator

Locator used to find the target element

option?​

Partial<MouseUpOption>

Allows specifying the mouse position relative to the element

Returns​

Promise<void>

Promise resolved when the event is dispatched

Throws​

If the element is not found

Overrides​

DOMInteractor.mouseUp

pressKey()​

pressKey(locator, key, option?): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:143

Dispatch a key press (keydown + keyup) on the element matched by the locator.

The element is focused first so the key originates from the active element, matching a real key press. fireEvent is used over userEvent.keyboard for determinism and because MUI handlers read event.key directly. The physical code is derived from key (see deriveKeyCode) so handlers that switch on event.code — e.g. PrimeVue's Slider — behave as they do under a real browser event, where code is always populated.

Parameters​

locator​

PartLocator

Locator used to find the target element

key​

string

A KeyboardEvent.key value, e.g. 'Escape', 'Backspace'

option?​

Partial<PressKeyOption>

Modifier flags folded into the event init as ctrlKey/shiftKey/altKey/metaKey, so a handler reading event.ctrlKey (etc.) sees the chord — see PressKeyOption

Returns​

Promise<void>

Promise resolved once the events have been dispatched

Throws​

If the element is not found

Overrides​

DOMInteractor.pressKey

scrollBy()​

scrollBy(locator, delta): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:173

Scroll the located element by the given pixel delta.

jsdom has no layout engine, so the scroll offset never changes — this is a no-op behaviorally. As with scrollIntoView, jsdom may not implement Element.prototype.scrollBy as a function, so the typeof guard prevents a TypeError and keeps the call a safe no-op that resolves; real scroll behavior is E2E-only.

Parameters​

locator​

PartLocator

Locator used to find the scrollable element

delta​

Point

Pixel offset to scroll by

Returns​

Promise<void>

Throws​

If the element is not found

Overrides​

DOMInteractor.scrollBy

scrollIntoView()​

scrollIntoView(locator): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:168

Scroll the located element into view.

jsdom has no layout engine, so this never produces an observable scroll — geometry stays zeroed and nothing becomes "visible". Worse, jsdom does not implement Element.prototype.scrollIntoView as a function in every version, so calling it unguarded would throw a TypeError. The typeof guard keeps this a safe no-op that resolves; real scrolling behavior is E2E-only.

Parameters​

locator​

PartLocator

Locator used to find the element

Returns​

Promise<void>

Throws​

If the element is not found

Overrides​

DOMInteractor.scrollIntoView

selectOptionValue()​

selectOptionValue(locator, values): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:158

Select one or more option values in a <select> element.

Parameters​

locator​

PartLocator

Locator used to find the select element

values​

string[]

Values of the options to select

Returns​

Promise<void>

Promise resolved when the options have been selected

Throws​

If the element is not found

Overrides​

DOMInteractor.selectOptionValue

setInputFiles()​

setInputFiles(locator, files): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:163

Set the selected files on an <input type="file"> element.

The interactor contract passes filesystem paths, but a file input's value cannot be assigned programmatically — the browser blocks it — so the FileList must be populated through userEvent.upload, which also fires the change event. jsdom has no filesystem and never reads file bytes; only File.name is observable, so each path is wrapped in an empty File named by its basename. The real bytes matter only to the Playwright layer, which reads the paths natively — keeping dom-core free of any node dependency.

Parameters​

locator​

PartLocator

Locator used to find the file input element

files​

string | string[]

One or more filesystem paths to upload

Returns​

Promise<void>

Promise resolved once the upload change event has fired

Throws​

If the element is not found

Overrides​

DOMInteractor.setInputFiles

setRangeValue()​

setRangeValue(locator, value): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:83

Set the value of a range input and fire its change event.

fireEvent.change assigns the value through the element's native value setter (which both sanitizes it to the input's step and lets React's value tracker observe the change) and dispatches the event so a controlled component re-renders. Typing (enterText) does not apply to a range input.

Parameters​

locator​

PartLocator

Locator used to find the range input element

value​

number

The numeric value to set

Returns​

Promise<void>

Promise resolved once the change event has fired

Throws​

If the element is not found

Overrides​

DOMInteractor.setRangeValue

typeText()​

typeText(locator, text): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:78

Type text into the element as real per-character keystrokes.

Focuses the element, then dispatches the characters through userEvent.keyboard, which fires the full key event sequence (keydown → beforeinput → input → keyup) against the active element — matching PlaywrightInteractor's pressSequentially (focus + keys, no pointer event, no clearing). {/[ are doubled so user-event's descriptor syntax never engages and the text is typed literally.

Parameters​

locator​

PartLocator

Locator used to find the target element

text​

string

The literal text to type, one keystroke per character

Returns​

Promise<void>

Promise resolved once every keystroke has been dispatched

Throws​

If the element is not found

Overrides​

DOMInteractor.typeText

waitUntil()​

waitUntil<T>(option): Promise<T>

Defined in: storybook/src/StorybookInteractor.ts:188

Type Parameters​

T​

T

Parameters​

option​

WaitUntilOption<T>

Returns​

Promise<T>

Overrides​

DOMInteractor.waitUntil

Inherited members (20)

Methods​

exists()​

exists(locator): Promise<boolean>

Defined in: dom-core/dist/index.d.mts:351

Parameters​
locator​

PartLocator

Returns​

Promise<boolean>

Inherited from​

DOMInteractor.exists

getAttribute()​

Call Signature​

getAttribute(locator, name, isMultiple): Promise<readonly string[]>

Defined in: dom-core/dist/index.d.mts:56

Parameters​
locator​

PartLocator

name​

string

isMultiple​

true

Returns​

Promise<readonly string[]>

Inherited from​

DOMInteractor.getAttribute

Call Signature​

getAttribute(locator, name, isMultiple): Promise<Optional<string>>

Defined in: dom-core/dist/index.d.mts:57

Parameters​
locator​

PartLocator

name​

string

isMultiple​

false

Returns​

Promise<Optional<string>>

Inherited from​

DOMInteractor.getAttribute

Call Signature​

getAttribute(locator, name): Promise<Optional<string>>

Defined in: dom-core/dist/index.d.mts:58

Parameters​
locator​

PartLocator

name​

string

Returns​

Promise<Optional<string>>

Inherited from​

DOMInteractor.getAttribute

getBoundingRect()​

getBoundingRect(locator): Promise<BoundingRect>

Defined in: dom-core/dist/index.d.mts:387

Get the located element's bounding rectangle.

jsdom has no layout engine, so getBoundingClientRect returns all zeros: the rect is structurally valid but behaviorally meaningless. Real geometry is E2E-only.

Parameters​
locator​

PartLocator

Locator used to find the element to measure

Returns​

Promise<BoundingRect>

The element's bounding rectangle (a zero-rect under jsdom)

Throws​

If the element is not found

Inherited from​

DOMInteractor.getBoundingRect

getElement()​

Call Signature​

getElement<T>(locator, isMultiple): Promise<readonly T[]>

Defined in: dom-core/dist/index.d.mts:359

Type Parameters​
T​

T extends Element = Element

Parameters​
locator​

PartLocator

isMultiple​

true

Returns​

Promise<readonly T[]>

Inherited from​

DOMInteractor.getElement

Call Signature​

getElement<T>(locator, isMultiple): Promise<Optional<T>>

Defined in: dom-core/dist/index.d.mts:360

Type Parameters​
T​

T extends Element = Element

Parameters​
locator​

PartLocator

isMultiple​

false

Returns​

Promise<Optional<T>>

Inherited from​

DOMInteractor.getElement

Call Signature​

getElement<T>(locator): Promise<Optional<T>>

Defined in: dom-core/dist/index.d.mts:361

Type Parameters​
T​

T extends Element = Element

Parameters​
locator​

PartLocator

Returns​

Promise<Optional<T>>

Inherited from​

DOMInteractor.getElement

getElementCount()​

getElementCount(locator): Promise<number>

Defined in: dom-core/dist/index.d.mts:358

Count every element matching the locator — the length of the multi-match query. Reuses the getElement multiple-overload rather than a second querySelectorAll path, so the document-root (:root) escape is honored in exactly one place. A read: it does NOT route through runInteraction.

Parameters​
locator​

PartLocator

Returns​

Promise<number>

Inherited from​

DOMInteractor.getElementCount

getInputValue()​

getInputValue(locator): Promise<Optional<string>>

Defined in: dom-core/dist/index.d.mts:372

Parameters​
locator​

PartLocator

Returns​

Promise<Optional<string>>

Inherited from​

DOMInteractor.getInputValue

getSelectLabels()​

getSelectLabels(locator): Promise<Optional<readonly string[]>>

Defined in: dom-core/dist/index.d.mts:374

Get the select element's selected options' labels

Parameters​
locator​

PartLocator

Returns​

Promise<Optional<readonly string[]>>

Inherited from​

DOMInteractor.getSelectLabels

getSelectValues()​

getSelectValues(locator): Promise<Optional<readonly string[]>>

Defined in: dom-core/dist/index.d.mts:373

Get the select element's selected options' values

Parameters​
locator​

PartLocator

Returns​

Promise<Optional<readonly string[]>>

Inherited from​

DOMInteractor.getSelectValues

getStyleValue()​

getStyleValue(locator, propertyName): Promise<Optional<string>>

Defined in: dom-core/dist/index.d.mts:59

Get the value of a style property

Parameters​
locator​

PartLocator

propertyName​

CssProperty

Returns​

Promise<Optional<string>>

Inherited from​

DOMInteractor.getStyleValue

getText()​

getText(locator): Promise<Optional<string>>

Defined in: dom-core/dist/index.d.mts:375

Parameters​
locator​

PartLocator

Returns​

Promise<Optional<string>>

Inherited from​

DOMInteractor.getText

hasAttribute()​

hasAttribute(locator, name): Promise<boolean>

Defined in: dom-core/dist/index.d.mts:395

Parameters​
locator​

PartLocator

name​

string

Returns​

Promise<boolean>

Inherited from​

DOMInteractor.hasAttribute

hasCssClass()​

hasCssClass(locator, className): Promise<boolean>

Defined in: dom-core/dist/index.d.mts:394

Parameters​
locator​

PartLocator

className​

string

Returns​

Promise<boolean>

Inherited from​

DOMInteractor.hasCssClass

innerHTML()​

innerHTML(locator): Promise<string>

Defined in: dom-core/dist/index.d.mts:396

Get the HTML of an element

Parameters​
locator​

PartLocator

Returns​

Promise<string>

Inherited from​

DOMInteractor.innerHTML

isChecked()​

isChecked(locator): Promise<boolean>

Defined in: dom-core/dist/index.d.mts:388

Parameters​
locator​

PartLocator

Returns​

Promise<boolean>

Inherited from​

DOMInteractor.isChecked

isDisabled()​

isDisabled(locator): Promise<boolean>

Defined in: dom-core/dist/index.d.mts:389

Parameters​
locator​

PartLocator

Returns​

Promise<boolean>

Inherited from​

DOMInteractor.isDisabled

isError()​

isError(locator): Promise<boolean>

Defined in: dom-core/dist/index.d.mts:392

Whether the element is in an invalid/error state, signalled by aria-invalid="true" (the cross-widget convention; native validity state is not consulted).

Parameters​
locator​

PartLocator

Returns​

Promise<boolean>

Inherited from​

DOMInteractor.isError

isReadonly()​

isReadonly(locator): Promise<boolean>

Defined in: dom-core/dist/index.d.mts:390

Parameters​
locator​

PartLocator

Returns​

Promise<boolean>

Inherited from​

DOMInteractor.isReadonly

isRequired()​

isRequired(locator): Promise<boolean>

Defined in: dom-core/dist/index.d.mts:391

Whether the element is marked required, via the native required property or an aria-required="true" attribute.

Parameters​
locator​

PartLocator

Returns​

Promise<boolean>

Inherited from​

DOMInteractor.isRequired

isVisible()​

isVisible(locator): Promise<boolean>

Defined in: dom-core/dist/index.d.mts:393

Parameters​
locator​

PartLocator

Returns​

Promise<boolean>

Inherited from​

DOMInteractor.isVisible

waitUntilComponentState()​

waitUntilComponentState(locator, option?): Promise<void>

Defined in: dom-core/dist/index.d.mts:349

Wait until the component is in the expected state such as the component's visibility or existence. If the component has not reached the expected state within the timeout, it will throw an error.

By default it waits until the component is attached to the DOM within 30 seconds.

Parameters​
locator​

PartLocator

The locator of the component to wait for

option?​

Partial<Readonly<WaitForOption>>

The option to configure the wait behavior

Returns​

Promise<void>

Inherited from​

DOMInteractor.waitUntilComponentState

Protected members (5)

Properties​

rootEl​

protected readonly rootEl: HTMLElement

Defined in: dom-core/dist/index.d.mts:37

Inherited from​

DOMInteractor.rootEl

userEvent​

protected readonly userEvent: UserEventDispatcher

Defined in: dom-core/dist/index.d.mts:38

Inherited from​

DOMInteractor.userEvent

Methods​

calculateMousePosition()​

protected calculateMousePosition(el, preferredPoint?): Point

Defined in: dom-core/dist/index.d.mts:60

Parameters​
el​

Element

preferredPoint?​

Point

Returns​

Point

Inherited from​

DOMInteractor.calculateMousePosition

runInteraction()​

protected runInteraction<T>(fn): Promise<T>

Defined in: dom-core/dist/index.d.mts:55

Template-method seam every mutating primitive (and both wait conditions) routes through. The base runs the interaction verbatim; framework adapters override it to flush their reactivity around the whole interaction — ReactInteractor wraps it in act(...), VueInteractor awaits nextTick(). Because every mutation funnels through this one method, a new mutating primitive added to this base is flushed by every adapter automatically — closing the silent gap that the previous per-method overrides left open, where an un-mirrored primitive was inherited unwrapped (#1052).

Reads (getText, getAttribute, exists, …) deliberately do NOT route through here: they observe state without mutating it, so there is nothing to flush.

Type Parameters​
T​

T

Parameters​
fn​

() => Promise<T>

Returns​

Promise<T>

Inherited from​

DOMInteractor.runInteraction

settle()​

protected settle(): Promise<void>

Defined in: storybook/src/StorybookInteractor.ts:61

Give the active renderer one chance to commit before the caller reads: a macrotask turn (drains Vue's microtask nextTick queue and zone.js microtasks first) followed by two animation frames (framework commit + browser paint). Not a guarantee for arbitrarily-async updates — those are what the waitUntil cadence is for.

Returns​

Promise<void>