Class: PlaywrightInteractor
Defined in: PlaywrightInteractor.ts:35
Implementation of the Interactor interface using Playwright.
Implements​
Interactor
Constructors​
Constructor​
new PlaywrightInteractor(
page):PlaywrightInteractor
Defined in: PlaywrightInteractor.ts:39
Parameters​
page​
Page
Playwright page instance used to drive the browser.
Returns​
PlaywrightInteractor
Properties​
page​
readonlypage:Page
Defined in: PlaywrightInteractor.ts:39
Playwright page instance used to drive the browser.
Methods​
activate()​
activate(
locator):Promise<void>
Defined in: PlaywrightInteractor.ts:459
Activate the desired element without relying on pointer geometry — a coordinate-free, dispatch-based click.
This reaches elements an ordinary PointerActions.click | 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 PointerActions.click | click
for ordinary, visible targets.
Parameters​
locator​
PartLocator
Returns​
Promise<void>
Implementation of​
Interactor.activate
blur()​
blur(
locator,_option?):Promise<void>
Defined in: PlaywrightInteractor.ts:427
Remove focus from the desired element
Parameters​
locator​
PartLocator
_option?​
Partial<BlurOption>
Returns​
Promise<void>
Implementation of​
Interactor.blur
click()​
click(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:348
Click on the desired element
Parameters​
locator​
PartLocator
option?​
Partial<ClickOption>
Returns​
Promise<void>
Implementation of​
Interactor.click
contextMenu()​
contextMenu(
locator):Promise<void>
Defined in: PlaywrightInteractor.ts:362
Dispatch a right-click on the located element to open its context menu.
Delegates to Playwright's native right-button click, which fires a real
contextmenu event in the browser.
Parameters​
locator​
PartLocator
Locator of the element to right-click
Returns​
Promise<void>
Throws​
If the element is not found
Implementation of​
Interactor.contextMenu
drag()​
drag(
locator,delta):Promise<void>
Defined in: PlaywrightInteractor.ts:203
Drag the located element by the given pixel delta from its center.
The gesture is a single uninterrupted move → down → move → up sequence
computed from the element's center. It deliberately does NOT reuse
mouseMove/mouseDown — those are discrete hover-then-act
helpers that cannot compose one continuous pointer path (see ADR 0001,
option 5). The center comes from getBoundingRect,
which throws ElementNotFoundError when the element has no box, so this
shares that "element not found" contract instead of re-deriving the box +
guard here.
Parameters​
locator​
PartLocator
Locator of the element to drag
delta​
Point
Pixel offset to drag by
Returns​
Promise<void>
Throws​
If the element has no bounding box
Implementation of​
Interactor.drag
dragTo()​
dragTo(
source,target):Promise<void>
Defined in: PlaywrightInteractor.ts:171
Drag the source element and drop it onto the target element.
Delegates to Playwright's native Locator.dragTo, which performs a real,
layout-aware drag gesture in the browser.
Parameters​
source​
PartLocator
Locator of the element to drag
target​
PartLocator
Locator of the drop target
Returns​
Promise<void>
Throws​
If either the source or target is not found
Implementation of​
Interactor.dragTo
enterText()​
enterText(
locator,text,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:292
Type text into the desired element
Parameters​
locator​
PartLocator
text​
string
option?​
Optional<Partial<EnterTextOption>>
Returns​
Promise<void>
Implementation of​
Interactor.enterText
exists()​
exists(
locator):Promise<boolean>
Defined in: PlaywrightInteractor.ts:539
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.exists
focus()​
focus(
locator,_option?):Promise<void>
Defined in: PlaywrightInteractor.ts:422
Parameters​
locator​
PartLocator
_option?​
Partial<FocusOption>
Returns​
Promise<void>
Implementation of​
Interactor.focus
getAttribute()​
Call Signature​
getAttribute(
locator,name,isMultiple):Promise<readonlystring[]>
Defined in: PlaywrightInteractor.ts:480
Parameters​
locator​
PartLocator
name​
string
isMultiple​
true
Returns​
Promise<readonly string[]>
Implementation of​
Interactor.getAttribute
Call Signature​
getAttribute(
locator,name,isMultiple):Promise<Optional<string>>
Defined in: PlaywrightInteractor.ts:481
Parameters​
locator​
PartLocator
name​
string
isMultiple​
false
Returns​
Promise<Optional<string>>
Implementation of​
Interactor.getAttribute
Call Signature​
getAttribute(
locator,name):Promise<Optional<string>>
Defined in: PlaywrightInteractor.ts:482
Parameters​
locator​
PartLocator
name​
string
Returns​
Promise<Optional<string>>
Implementation of​
Interactor.getAttribute
getBoundingRect()​
getBoundingRect(
locator):Promise<BoundingRect>
Defined in: PlaywrightInteractor.ts:530
Get the located element's bounding rectangle.
boundingBox() returns null for a detached/invisible element rather than
auto-waiting, so this throws ElementNotFoundError directly (no auto-wait)
— matching the unified "element not found" contract (ADR-006).
Parameters​
locator​
PartLocator
Locator of the element to measure
Returns​
Promise<BoundingRect>
The element's bounding rectangle in CSS pixels
Throws​
If the element has no bounding box
Implementation of​
Interactor.getBoundingRect
getElementCount()​
getElementCount(
locator):Promise<number>
Defined in: PlaywrightInteractor.ts:550
Count every element matching the locator via Playwright's native
Locator.count() — one round-trip, in contrast to the index-by-index
exists() probing this primitive replaces in the list helpers.
Parameters​
locator​
PartLocator
Returns​
Promise<number>
Implementation of​
Interactor.getElementCount
getInputValue()​
getInputValue(
locator):Promise<Optional<string>>
Defined in: PlaywrightInteractor.ts:223
Get the value of an <input> or <textarea> element.
Mirrors DOMInteractor: a missing element, or one that is neither <input>
nor <textarea>, yields undefined rather than Playwright's auto-wait
timeout or its Node is not an <input> throw (#1047).
Parameters​
locator​
PartLocator
Locator pointing to the input element.
Returns​
Promise<Optional<string>>
The current value of the input, or undefined if not applicable.
Implementation of​
Interactor.getInputValue
getSelectLabels()​
getSelectLabels(
locator):Promise<Optional<readonlystring[]>>
Defined in: PlaywrightInteractor.ts:262
Get the select element's selected options' labels
Parameters​
locator​
PartLocator
Returns​
Promise<Optional<readonly string[]>>
Implementation of​
Interactor.getSelectLabels
getSelectValues()​
getSelectValues(
locator):Promise<Optional<readonlystring[]>>
Defined in: PlaywrightInteractor.ts:241
Retrieve the values of selected options within a <select> element.
Parameters​
locator​
PartLocator
Locator to the <select> element.
Returns​
Promise<Optional<readonly string[]>>
Array of selected option values or undefined when no option is selected.
Implementation of​
Interactor.getSelectValues
getStyleValue()​
getStyleValue(
locator,propertyName):Promise<Optional<string>>
Defined in: PlaywrightInteractor.ts:278
Get the value of a style property
Parameters​
locator​
PartLocator
propertyName​
CssProperty
Returns​
Promise<Optional<string>>
Implementation of​
Interactor.getStyleValue
getText()​
getText(
locator):Promise<Optional<string>>
Defined in: PlaywrightInteractor.ts:510
Parameters​
locator​
PartLocator
Returns​
Promise<Optional<string>>
Implementation of​
Interactor.getText
hasAttribute()​
hasAttribute(
locator,name):Promise<boolean>
Defined in: PlaywrightInteractor.ts:636
Parameters​
locator​
PartLocator
name​
string
Returns​
Promise<boolean>
Implementation of​
Interactor.hasAttribute
hasCssClass()​
hasCssClass(
locator,className):Promise<boolean>
Defined in: PlaywrightInteractor.ts:626
Parameters​
locator​
PartLocator
className​
string
Returns​
Promise<boolean>
Implementation of​
Interactor.hasCssClass
hover()​
hover(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:367
Perform a mouse hover on the desired element
Parameters​
locator​
PartLocator
option?​
Partial<HoverOption>
Returns​
Promise<void>
Implementation of​
Interactor.hover
innerHTML()​
innerHTML(
locator):Promise<string>
Defined in: PlaywrightInteractor.ts:642
Get the HTML of an element
Parameters​
locator​
PartLocator
Returns​
Promise<string>
Implementation of​
Interactor.innerHTML
isChecked()​
isChecked(
locator):Promise<boolean>
Defined in: PlaywrightInteractor.ts:555
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.isChecked
isDisabled()​
isDisabled(
locator):Promise<boolean>
Defined in: PlaywrightInteractor.ts:563
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.isDisabled
isError()​
isError(
locator):Promise<boolean>
Defined in: PlaywrightInteractor.ts:591
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>
Implementation of​
Interactor.isError
isReadonly()​
isReadonly(
locator):Promise<boolean>
Defined in: PlaywrightInteractor.ts:571
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.isReadonly
isRequired()​
isRequired(
locator):Promise<boolean>
Defined in: PlaywrightInteractor.ts:583
Whether the element is marked required, via the native required property or
an aria-required="true" attribute.
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.isRequired
isVisible()​
isVisible(
locator):Promise<boolean>
Defined in: PlaywrightInteractor.ts:595
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.isVisible
mouseDown()​
mouseDown(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:380
Parameters​
locator​
PartLocator
option?​
Partial<MouseDownOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseDown
mouseEnter()​
mouseEnter(
locator,_option?):Promise<void>
Defined in: PlaywrightInteractor.ts:408
Parameters​
locator​
PartLocator
_option?​
Partial<MouseEnterOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseEnter
mouseLeave()​
mouseLeave(
locator,_option?):Promise<void>
Defined in: PlaywrightInteractor.ts:412
Parameters​
locator​
PartLocator
_option?​
Partial<MouseLeaveOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseLeave
mouseMove()​
mouseMove(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:372
Mouse move on the desired element
Parameters​
locator​
PartLocator
option?​
Partial<MouseMoveOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseMove
mouseOut()​
mouseOut(
locator,_option?):Promise<void>
Defined in: PlaywrightInteractor.ts:398
Parameters​
locator​
PartLocator
_option?​
Partial<MouseOutOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseOut
mouseOver()​
mouseOver(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:394
Parameters​
locator​
PartLocator
option?​
Partial<HoverOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseOver
mouseUp()​
mouseUp(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:387
Parameters​
locator​
PartLocator
option?​
Partial<MouseUpOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseUp
pressKey()​
pressKey(
locator,key,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:432
Dispatch a keyboard key press on the desired element.
Unlike FormActions.enterText | 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 FormActions.enterText | enterText/FormActions.typeText | typeText,
not this). No pointer event is involved, so behaviours unreachable by
PointerActions.click | 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​
PartLocator
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>
Implementation of​
Interactor.pressKey
scrollBy()​
scrollBy(
locator,delta):Promise<void>
Defined in: PlaywrightInteractor.ts:154
Scroll the located element by the given pixel delta.
The scroll is performed by evaluating el.scrollBy(dx, dy) on the element
itself rather than page.mouse.wheel. A wheel event scrolls whatever sits
under the pointer and is non-deterministic across chromium/firefox/webkit,
whereas evaluating scrollBy on the resolved element scrolls exactly that
element. This is a deliberate deviation from ADR 0001's per-engine table
(which lists page.mouse.wheel), taking the alternative the step-5 prompt
permits ("or evaluate el.scrollBy") for cross-browser determinism.
Parameters​
locator​
PartLocator
Locator of the scrollable element
delta​
Point
Pixel offset to scroll by
Returns​
Promise<void>
Throws​
If the element is not found
Implementation of​
Interactor.scrollBy
scrollIntoView()​
scrollIntoView(
locator):Promise<void>
Defined in: PlaywrightInteractor.ts:134
Scroll the located element into view, no-op if already visible.
Delegates to Playwright's scrollIntoViewIfNeeded, which performs a real
layout-aware scroll in the browser.
Parameters​
locator​
PartLocator
Locator of the element to scroll into view
Returns​
Promise<void>
Throws​
If the element is not found
Implementation of​
Interactor.scrollIntoView
selectOptionValue()​
selectOptionValue(
locator,values):Promise<void>
Defined in: PlaywrightInteractor.ts:104
Select the given option values on a <select> element.
Parameters​
locator​
PartLocator
Locator to the <select> element.
values​
string[]
Values to select.
Returns​
Promise<void>
Throws​
If the element is not found
Implementation of​
Interactor.selectOptionValue
setInputFiles()​
setInputFiles(
locator,files):Promise<void>
Defined in: PlaywrightInteractor.ts:120
Set the selected files on a <input type="file"> element.
Playwright's native setInputFiles reads the given paths from disk and
populates the input's FileList, firing the change event — the only way to
fill a file input, whose value cannot be set programmatically.
Parameters​
locator​
PartLocator
Locator of the <input type="file"> element
files​
string | string[]
One or more filesystem paths to upload
Returns​
Promise<void>
Throws​
If the element is not found
Implementation of​
Interactor.setInputFiles
setRangeValue()​
setRangeValue(
locator,value):Promise<void>
Defined in: PlaywrightInteractor.ts:329
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
FormActions.enterText | enterText (it accepts no typed text) nor
reliably through PointerActions.click | 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​
PartLocator
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>
Implementation of​
Interactor.setRangeValue
typeText()​
typeText(
locator,text):Promise<void>
Defined in: PlaywrightInteractor.ts:324
Type text into the element as real per-character keystrokes.
pressSequentially focuses the element and dispatches a trusted
keydown/keypress/input/keyup sequence per character — the keystroke path
that enterText's fill() (a direct value replacement) never exercises,
and the only one keystroke-driven editors such as the MUI X picker section
field respond to. No pointer event and no clearing, mirroring the DOM
implementation's focus + keyboard dispatch. Playwright types the text
literally, so no escaping is needed here.
Parameters​
locator​
PartLocator
Locator used to find the target element
text​
string
The literal text to type, one keystroke per character
Returns​
Promise<void>
Throws​
If the element is not found
Implementation of​
Interactor.typeText
waitUntil()​
waitUntil<
T>(option):Promise<T>
Defined in: PlaywrightInteractor.ts:475
Keep running a probe function until it returns a value that matches the terminate condition or timeout
Type Parameters​
T​
T
Parameters​
option​
WaitUntilOption<T>
Returns​
Promise<T>
The last value returned by the probe function
Implementation of​
Interactor.waitUntil
waitUntilComponentState()​
waitUntilComponentState(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:468
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>> = defaultWaitForOption
The option to configure the wait behavior
Returns​
Promise<void>
Implementation of​
Interactor.waitUntilComponentState