Interface: FormActions
Defined in: packages/core/src/interactor/Interactor.ts:191
Form-control value entry: typing into text fields, driving range/select/file inputs. A capability facet of Interactor (ADR-007); an environment that supports forms but not, say, drag gestures can declare this facet on its own.
Extended by​
Methods​
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>
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>
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>
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>
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>