Interface: Interactor
Defined in: packages/core/src/interactor/Interactor.ts:446
Environment specific implementation that performs low level actions on the UI.
Component drivers delegate every interaction to an instance of this interface so tests can run in different environments by simply providing a different interactor implementation.
Capability facets. Interactor is composed from narrower facets —
PointerActions, KeyboardActions, FocusActions,
FormActions, ScrollActions, ElementQueries, and
Waiter — so a driver can depend on just the surface it uses and a
future partial-capability environment can declare exactly the facets it
supports (ADR-007). TypeScript is structurally typed, so any value that
satisfied Interactor before the split still does; recomposing from facets is
purely additive and changes no member.
1.0 boundary — DOM and CSS only. Every method resolves its target by
reducing a PartLocator to a single CSS selector
(locatorUtil.toCssSelector) and running it against a DOM — jsdom via
@testing-library in DOMInteractor, or a real browser via Playwright. The
1.0 contract is therefore deliberately scoped to DOM environments addressed
by CSS: there is no seam for a non-DOM target, and a computed ARIA accessible
name (aria-labelledby / <label> / text — not CSS-expressible) is out of
scope. See ADR-008;
the deferred name-aware resolution is tracked in #923. Post-1.0 the interface
grows additively per ADR-007.
Extends​
Inherited members (43)
Methods​
activate()​
activate(
locator):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:87
Activate the desired element without relying on pointer geometry — a coordinate-free, dispatch-based click.
This reaches elements an ordinary click cannot:
a visually-hidden or zero-size input covered by another element (e.g. MUI
Rating's hidden <input type="radio">, where a positional click hit-tests to
the covering star label instead). Prefer click
for ordinary, visible targets.
Parameters​
locator​
Returns​
Promise<void>
Inherited from​
blur()​
blur(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:183
Remove focus from the desired element
Parameters​
locator​
option?​
Partial<BlurOption>
Returns​
Promise<void>
Inherited from​
click()​
click(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:39
Click on the desired element
Parameters​
locator​
option?​
Partial<ClickOption>
Returns​
Promise<void>
Inherited from​
contextMenu()​
contextMenu(
locator):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:73
Dispatch a right-click / contextmenu event on the desired element.
A contextmenu event is the only way to open a context menu: such menus have
no aria-expanded toggle or controlled-open prop to flip, so the menu is
reachable only by the event a right-click produces. This is analogous to
pressKey for keyboard-only behaviors — a
dedicated primitive for an outcome no ordinary click
can express. The element is focused first if focusable, mirroring pressKey,
so the event originates from the active element as in a real right-click.
Parameters​
locator​
Returns​
Promise<void>
Inherited from​
drag()​
drag(
locator,delta):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:123
Drag the desired element by the given pixel delta from its center.
jsdom has no layout engine, so the drag has no positional outcome there: the pointer sequence is synthesized from the caller-supplied delta and only the event wiring is exercised. Behavioral assertions about the resulting position are therefore E2E-only; the jsdom path only guarantees the events fire once the element is found.
Mouse/pointer-based only: native HTML5 drag-and-drop is not synthesized — see #922.
Parameters​
locator​
Locator of the element to drag
delta​
Pixel offset to drag by, where x is horizontal and y is vertical
Returns​
Promise<void>
Inherited from​
dragTo()​
dragTo(
source,target):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:106
Drag the source element and drop it onto the target element.
jsdom has no layout engine, so the drag has no positional outcome there: the pointer sequence is synthesized at zeroed coordinates and only the event wiring (mousedown/mousemove/mouseup, and any drop handler they trigger) is exercised. Behavioral assertions about the final position are therefore E2E-only; the jsdom path only guarantees the events fire once both elements are found.
Mouse/pointer-based only: native HTML5 drag-and-drop
(dragstart/dragover/drop + dataTransfer) is not synthesized, so
components built on the HTML5 DnD API are out of scope here — see #922.
Parameters​
source​
Locator of the element to drag
target​
Locator of the element to drop onto
Returns​
Promise<void>
Inherited from​
enterText()​
enterText(
locator,text,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:197
Type text into the desired element
Parameters​
locator​
text​
string
option?​
Partial<EnterTextOption>
Returns​
Promise<void>
Inherited from​
exists()​
exists(
locator):Promise<boolean>
Defined in: packages/core/src/interactor/Interactor.ts:375
Parameters​
locator​
Returns​
Promise<boolean>
Inherited from​
focus()​
focus(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:176
Parameters​
locator​
option?​
Partial<FocusOption>
Returns​
Promise<void>
Inherited from​
getAttribute()​
Call Signature​
getAttribute(
locator,name,isMultiple):Promise<readonlystring[]>
Defined in: packages/core/src/interactor/Interactor.ts:350
Parameters​
locator​
name​
string
isMultiple​
true
Returns​
Promise<readonly string[]>
Inherited from​
Call Signature​
getAttribute(
locator,name,isMultiple):Promise<Optional<string>>
Defined in: packages/core/src/interactor/Interactor.ts:351
Parameters​
locator​
name​
string
isMultiple​
false
Returns​
Promise<Optional<string>>
Inherited from​
Call Signature​
getAttribute(
locator,name):Promise<Optional<string>>
Defined in: packages/core/src/interactor/Interactor.ts:352
Parameters​
locator​
name​
string
Returns​
Promise<Optional<string>>
Inherited from​
getBoundingRect()​
getBoundingRect(
locator):Promise<BoundingRect>
Defined in: packages/core/src/interactor/Interactor.ts:373
Get the element's bounding rectangle in CSS pixels.
jsdom has no layout engine, so every coordinate and dimension is 0 there:
the returned rect is structurally valid but behaviorally meaningless.
Assertions about real geometry are therefore E2E-only; under jsdom this
returns a zero-rect.
Parameters​
locator​
Locator of the element to measure
Returns​
Promise<BoundingRect>
Inherited from​
ElementQueries.getBoundingRect
getElementCount()​
getElementCount(
locator):Promise<number>
Defined in: packages/core/src/interactor/Interactor.ts:392
Count every element matching the locator.
Where exists is a presence check that stops at
the first match, this resolves the locator to its full match set and returns
the cardinality — the multi-match counterpart the list helpers use to size a
collection in one round-trip instead of probing index by index. A locator
matching nothing yields 0.
Homogeneous-match semantics: the count is by locator match, not by tag
position. A sibling that shares an item's tag but does not satisfy the
locator is not counted — the opposite of :nth-of-type, which counts by tag
among all siblings. This is what lets the count side of a list stay correct
when the items are interleaved with a same-tag non-item (a header/divider).
Parameters​
locator​
Returns​
Promise<number>
Inherited from​
ElementQueries.getElementCount
getInputValue()​
getInputValue(
locator):Promise<Optional<string>>
Defined in: packages/core/src/interactor/Interactor.ts:338
Parameters​
locator​
Returns​
Promise<Optional<string>>
Inherited from​
getSelectLabels()​
getSelectLabels(
locator):Promise<Optional<readonlystring[]>>
Defined in: packages/core/src/interactor/Interactor.ts:348
Get the select element's selected options' labels
Parameters​
locator​
Returns​
Promise<Optional<readonly string[]>>
Inherited from​
ElementQueries.getSelectLabels
getSelectValues()​
getSelectValues(
locator):Promise<Optional<readonlystring[]>>
Defined in: packages/core/src/interactor/Interactor.ts:343
Get the select element's selected options' values
Parameters​
locator​
Returns​
Promise<Optional<readonly string[]>>
Inherited from​
ElementQueries.getSelectValues
getStyleValue()​
getStyleValue(
locator,propertyName):Promise<Optional<string>>
Defined in: packages/core/src/interactor/Interactor.ts:359
Get the value of a style property
Parameters​
locator​
propertyName​
Returns​
Promise<Optional<string>>
Inherited from​
getText()​
getText(
locator):Promise<Optional<string>>
Defined in: packages/core/src/interactor/Interactor.ts:361
Parameters​
locator​
Returns​
Promise<Optional<string>>
Inherited from​
hasAttribute()​
hasAttribute(
locator,name):Promise<boolean>
Defined in: packages/core/src/interactor/Interactor.ts:410
Parameters​
locator​
name​
string
Returns​
Promise<boolean>
Inherited from​
hasCssClass()​
hasCssClass(
locator,className):Promise<boolean>
Defined in: packages/core/src/interactor/Interactor.ts:409
Parameters​
locator​
className​
string
Returns​
Promise<boolean>
Inherited from​
hover()​
hover(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:129
Perform a mouse hover on the desired element
Parameters​
locator​
option?​
Returns​
Promise<void>
Inherited from​
innerHTML()​
innerHTML(
locator):Promise<string>
Defined in: packages/core/src/interactor/Interactor.ts:416
Get the HTML of an element
Parameters​
locator​
Returns​
Promise<string>
Inherited from​
isChecked()​
isChecked(
locator):Promise<boolean>
Defined in: packages/core/src/interactor/Interactor.ts:393
Parameters​
locator​
Returns​
Promise<boolean>
Inherited from​
isDisabled()​
isDisabled(
locator):Promise<boolean>
Defined in: packages/core/src/interactor/Interactor.ts:394
Parameters​
locator​
Returns​
Promise<boolean>
Inherited from​
isError()​
isError(
locator):Promise<boolean>
Defined in: packages/core/src/interactor/Interactor.ts:406
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​
Returns​
Promise<boolean>
Inherited from​
isReadonly()​
isReadonly(
locator):Promise<boolean>
Defined in: packages/core/src/interactor/Interactor.ts:395
Parameters​
locator​
Returns​
Promise<boolean>
Inherited from​
isRequired()​
isRequired(
locator):Promise<boolean>
Defined in: packages/core/src/interactor/Interactor.ts:400
Whether the element is marked required, via the native required property or
an aria-required="true" attribute.
Parameters​
locator​
Returns​
Promise<boolean>
Inherited from​
isVisible()​
isVisible(
locator):Promise<boolean>
Defined in: packages/core/src/interactor/Interactor.ts:407
Parameters​
locator​
Returns​
Promise<boolean>
Inherited from​
mouseDown()​
mouseDown(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:48
Parameters​
locator​
option?​
Partial<MouseDownOption>
Returns​
Promise<void>
Inherited from​
mouseEnter()​
mouseEnter(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:56
Parameters​
locator​
option?​
Partial<MouseEnterOption>
Returns​
Promise<void>
Inherited from​
mouseLeave()​
mouseLeave(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:58
Parameters​
locator​
option?​
Partial<MouseLeaveOption>
Returns​
Promise<void>
Inherited from​
mouseMove()​
mouseMove(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:46
Mouse move on the desired element
Parameters​
locator​
option?​
Partial<MouseMoveOption>
Returns​
Promise<void>
Inherited from​
mouseOut()​
mouseOut(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:54
Parameters​
locator​
option?​
Partial<MouseOutOption>
Returns​
Promise<void>
Inherited from​
mouseOver()​
mouseOver(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:52
Parameters​
locator​
option?​
Partial<HoverOption>
Returns​
Promise<void>
Inherited from​
mouseUp()​
mouseUp(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:50
Parameters​
locator​
option?​
Partial<MouseUpOption>
Returns​
Promise<void>
Inherited from​
pressKey()​
pressKey(
locator,key,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:168
Dispatch a keyboard key press on the desired element.
Unlike enterText, which fills a value, this
dispatches an actual key event so components that key off KeyboardEvent.key
are exercised — e.g. Dialog dismissal on Escape or Chip deletion on
Backspace/Delete. The element is focused first so the event originates
from the active element, matching a real key press. On a focused
contenteditable host the press additionally carries beforeinput/input
fidelity, so editing keys such as Backspace reach components that commit
changes from input events (e.g. the MUI X picker section field, see #903); on
every other target — including text <input>/<textarea> — it stays a plain
keydown/keyup on the element so keyboard handlers fire as they expect (a
text field is edited through enterText/typeText,
not this). No pointer event is involved, so behaviours unreachable by
click (geometry or not) become testable.
Cross-engine caveat: with shift and a PRINTABLE key the engines disagree on
the resulting KeyboardEvent.key — Playwright case-folds (Shift+a →
'A') while the jsdom path leaves key as 'a' (with shiftKey: true). The
modifier flags themselves are delivered consistently; only the printed
character differs. Prefer non-printable keys for cross-engine assertions on
key — see #924.
Parameters​
locator​
key​
string
A KeyboardEvent.key value, e.g. 'Escape', 'Backspace', 'Enter'
option?​
Partial<PressKeyOption>
Modifier flags (ctrl/shift/alt/meta) folded into the
dispatched key event, so a chord such as Ctrl+Enter is delivered with its
held modifiers — see PressKeyOption.
Returns​
Promise<void>
Inherited from​
scrollBy()​
scrollBy(
locator,delta):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:301
Scroll the desired element by the given delta (in pixels).
jsdom has no layout engine, so the scrolling effect is a no-op there: the element's scroll offset never changes. Behavioral assertions about the resulting scroll position are therefore E2E-only; the jsdom path only guarantees the call resolves without throwing once the element is found.
Parameters​
locator​
Locator of the scrollable element
delta​
Pixel offset to scroll by, where x is horizontal and y is vertical
Returns​
Promise<void>
Inherited from​
scrollIntoView()​
scrollIntoView(
locator):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:288
Scroll the desired element into the viewport.
jsdom has no layout engine, so the scrolling effect is a no-op there: the element's geometry never changes and nothing becomes "visible". Behavioral assertions about visibility or offset are therefore E2E-only; the jsdom path only guarantees the call resolves without throwing once the element is found.
Parameters​
locator​
Locator of the element to scroll into view
Returns​
Promise<void>
Inherited from​
selectOptionValue()​
selectOptionValue(
locator,values):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:252
Select option by value from a select element
Parameters​
locator​
values​
string[]
Returns​
Promise<void>
Inherited from​
setInputFiles()​
setInputFiles(
locator,files):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:269
Set the selected files on a <input type="file"> element.
A dedicated primitive exists because a file input's FileList cannot be
populated through enterText (or any
value-typing path): browsers block programmatic assignment to type=file
value for security, so the FileList must be set via the upload-specific
channel — userEvent.upload in the DOM/jsdom and locator.setInputFiles in
Playwright — which is the only way a change event with the chosen files fires.
Parameters​
locator​
Locator of the <input type="file"> element
files​
string | string[]
One or more filesystem paths to upload. Pass a single path for
a non-multiple input; pass an array to select several files on a
multiple input.
Returns​
Promise<void>
Inherited from​
setRangeValue()​
setRangeValue(
locator,value):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:245
Set the value of a range input (<input type="range">, the element behind a
slider) and fire its change so the host framework reacts.
A dedicated primitive exists because a range input cannot be driven through
enterText (it accepts no typed text) nor
reliably through click (a positional click on
the track sets a coordinate-derived, not an exact, value). The value is
assigned through the element's native value setter — so the browser sanitizes
it to the input's min/max/step, snapping an off-step target to the
nearest valid step — and an input/change event is dispatched so controlled
components (e.g. MUI Slider) update their state.
jsdom has no range sanitization, so it stores an off-step value verbatim
whereas a real browser snaps it; pass a step-aligned value for assertions
that must hold in both environments. See #73.
Parameters​
locator​
Locator of the <input type="range"> element
value​
number
The numeric value to set; sanitized to the input's step in-browser
Returns​
Promise<void>
Inherited from​
typeText()​
typeText(
locator,text):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:223
Type text into the desired element as a sequence of real per-character keystrokes.
Unlike enterText, which clears the target and
fills its value — a path invisible to widgets that ignore programmatic value
assignment — this focuses the element and dispatches the full key event
sequence per character (keydown → beforeinput → input → keyup),
inserting at the element's current caret with no clearing. That reaches
keystroke-driven editors such as the MUI X picker section field (a
contenteditable role="spinbutton" span that only commits digits arriving
as genuine key events) and grid cell editors entered via
pressKey — see #903/#905.
The text is typed literally: characters that carry special meaning in an
underlying dispatcher (user-event's {/[ descriptor syntax) are escaped,
so typeText(locator, '{a}') types the five characters {a} verbatim.
For non-printable keys or modifier chords use pressKey;
to clear before typing, combine with enterText
or key presses.
Parameters​
locator​
Locator of the element to type into
text​
string
The literal text to type, one keystroke per character
Returns​
Promise<void>
Inherited from​
waitUntil()​
waitUntil<
T>(option):Promise<T>
Defined in: packages/core/src/interactor/Interactor.ts:328
Keep running a probe function until it returns a value that matches the terminate condition or timeout
Type Parameters​
T​
T
Parameters​
option​
Returns​
Promise<T>
The last value returned by the probe function
Inherited from​
waitUntilComponentState()​
waitUntilComponentState(
locator,option?):Promise<void>
Defined in: packages/core/src/interactor/Interactor.ts:322
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​
The locator of the component to wait for
option?​
Partial<Readonly<WaitForOption>>
The option to configure the wait behavior
Returns​
Promise<void>