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:393
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​
PartLocator
Returns​
Promise<void>
Implementation of​
Interactor.activate
blur()​
blur(
locator,_option?):Promise<void>
Defined in: PlaywrightInteractor.ts:361
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:283
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:297
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:177
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 — mouseMove resets the pointer with
page.mouse.move(0, 0) after hovering, which would corrupt the drag 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:145
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:243
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:465
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.exists
focus()​
focus(
locator,_option?):Promise<void>
Defined in: PlaywrightInteractor.ts:356
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:414
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:415
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:416
Parameters​
locator​
PartLocator
name​
string
Returns​
Promise<Optional<string>>
Implementation of​
Interactor.getAttribute
getBoundingRect()​
getBoundingRect(
locator):Promise<BoundingRect>
Defined in: PlaywrightInteractor.ts:456
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
getInputValue()​
getInputValue(
locator):Promise<Optional<string>>
Defined in: PlaywrightInteractor.ts:193
Get the value of an <input> element.
Parameters​
locator​
PartLocator
Locator pointing to the input element.
Returns​
Promise<Optional<string>>
The current value of the input or undefined if not present.
Implementation of​
Interactor.getInputValue
getSelectLabels()​
getSelectLabels(
locator):Promise<Optional<readonlystring[]>>
Defined in: PlaywrightInteractor.ts:219
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:204
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:234
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:439
Parameters​
locator​
PartLocator
Returns​
Promise<Optional<string>>
Implementation of​
Interactor.getText
hasAttribute()​
hasAttribute(
locator,name):Promise<boolean>
Defined in: PlaywrightInteractor.ts:550
Parameters​
locator​
PartLocator
name​
string
Returns​
Promise<boolean>
Implementation of​
Interactor.hasAttribute
hasCssClass()​
hasCssClass(
locator,className):Promise<boolean>
Defined in: PlaywrightInteractor.ts:540
Parameters​
locator​
PartLocator
className​
string
Returns​
Promise<boolean>
Implementation of​
Interactor.hasCssClass
hover()​
hover(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:302
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:556
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:471
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.isChecked
isDisabled()​
isDisabled(
locator):Promise<boolean>
Defined in: PlaywrightInteractor.ts:477
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.isDisabled
isError()​
isError(
locator):Promise<boolean>
Defined in: PlaywrightInteractor.ts:496
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:483
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.isReadonly
isRequired()​
isRequired(
locator):Promise<boolean>
Defined in: PlaywrightInteractor.ts:488
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:500
Parameters​
locator​
PartLocator
Returns​
Promise<boolean>
Implementation of​
Interactor.isVisible
mouseDown()​
mouseDown(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:314
Parameters​
locator​
PartLocator
option?​
Partial<MouseDownOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseDown
mouseEnter()​
mouseEnter(
locator,_option?):Promise<void>
Defined in: PlaywrightInteractor.ts:342
Parameters​
locator​
PartLocator
_option?​
Partial<MouseEnterOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseEnter
mouseLeave()​
mouseLeave(
locator,_option?):Promise<void>
Defined in: PlaywrightInteractor.ts:346
Parameters​
locator​
PartLocator
_option?​
Partial<MouseLeaveOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseLeave
mouseMove()​
mouseMove(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:307
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:332
Parameters​
locator​
PartLocator
_option?​
Partial<MouseOutOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseOut
mouseOver()​
mouseOver(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:328
Parameters​
locator​
PartLocator
option?​
Partial<HoverOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseOver
mouseUp()​
mouseUp(
locator,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:321
Parameters​
locator​
PartLocator
option?​
Partial<MouseUpOption>
Returns​
Promise<void>
Implementation of​
Interactor.mouseUp
pressKey()​
pressKey(
locator,key,option?):Promise<void>
Defined in: PlaywrightInteractor.ts:366
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. 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​
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:128
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:108
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:78
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:94
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:264
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​
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
waitUntil()​
waitUntil<
T>(option):Promise<T>
Defined in: PlaywrightInteractor.ts:409
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:402
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