Class: PlaywrightInteractor

Defined in: PlaywrightInteractor.ts:45

Implementation of the Interactor interface using Playwright.

Implements

• Interactor

Constructors

Constructor

new PlaywrightInteractor(page): PlaywrightInteractor

Defined in: PlaywrightInteractor.ts:49

Parameters

page

Page

Playwright page instance used to drive the browser.

Returns

PlaywrightInteractor

Properties

page

readonly page: Page

Defined in: PlaywrightInteractor.ts:49

Playwright page instance used to drive the browser.

Methods

activate()

activate(locator): Promise<void>

Defined in: PlaywrightInteractor.ts:577

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:544

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:462

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:479

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:306

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.

As with dragTo, this real pointer gesture drives native HTML5 drag-and-drop too when the element is draggable — verified (#922) that the browser's own gesture recognition fires the full dragstart → dragover → drop (onto itself; there is no separate target for a delta drag) → dragend sequence with a real DataTransfer, with no additional dispatch required.

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:246

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

A real, layout-aware pointer gesture the browser's own engine processes, unlike jsdom's synthesized events (see DOMInteractor.dragTo). It drives pointer-based DnD libraries (dnd-kit, react-beautiful-dnd) AND native HTML5 drag-and-drop (draggable + ondragstart/ondragover/ ondrop): verified empirically (#922) that the browser recognizes and runs its own native DnD gesture from pointer input alone — dragstart → dragenter/dragover → drop → dragend fire with a real, populated DataTransfer, no extra dispatch needed. (This contradicts an earlier assumption that Playwright's pointer gesture does NOT drive native HTML5 DnD — re-verify if this ever regresses, since nothing pins it beyond the E2E suite below.)

The pointer travels to the target in dragStepCount steps rather than jumping, which is what Locator.dragTo does. The intermediate motion is load-bearing, not cosmetic: a drop target may infer direction by comparing consecutive dragover coordinates, and a single jump gives it one sample against whatever it initialized from. MUI's DataGrid column reorder is exactly that — it seeds its cursor reference at the origin, so a jump always reads as "moved right" and a leftward reorder is silently dropped. Stepping matches what a real drag looks like, so direction-sensing targets see the truth.

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:395

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:666

Parameters

locator

PartLocator

Returns

Promise<boolean>

Implementation of

Interactor.exists

---

focus()

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

Defined in: PlaywrightInteractor.ts:539

Parameters

locator

PartLocator

_option?

Partial<FocusOption>

Returns

Promise<void>

Implementation of

Interactor.focus

---

getAttribute()

Call Signature

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

Defined in: PlaywrightInteractor.ts:598

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:599

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:600

Parameters

locator

PartLocator

name

string

Returns

Promise<Optional<string>>

Implementation of

Interactor.getAttribute

---

getBoundingRect()

getBoundingRect(locator): Promise<BoundingRect>

Defined in: PlaywrightInteractor.ts:648

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:677

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:326

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<readonly string[]>>

Defined in: PlaywrightInteractor.ts:365

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<readonly string[]>>

Defined in: PlaywrightInteractor.ts:344

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:381

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:628

Parameters

locator

PartLocator

Returns

Promise<Optional<string>>

Implementation of

Interactor.getText

---

hasAttribute()

hasAttribute(locator, name): Promise<boolean>

Defined in: PlaywrightInteractor.ts:770

Parameters

locator

PartLocator

name

string

Returns

Promise<boolean>

Implementation of

Interactor.hasAttribute

---

hasCssClass()

hasCssClass(locator, className): Promise<boolean>

Defined in: PlaywrightInteractor.ts:760

Parameters

locator

PartLocator

className

string

Returns

Promise<boolean>

Implementation of

Interactor.hasCssClass

---

hover()

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

Defined in: PlaywrightInteractor.ts:484

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:776

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:682

Whether the element is checked, via the native checked property of an <input type="checkbox">/<input type="radio"> or aria-checked="true" on an element carrying an explicit checkable role. aria-checked="mixed" and a native indeterminate control both report false — the contract is two-state. The locator must address the control itself; a <label> is not retargeted.

Parameters

locator

PartLocator

Returns

Promise<boolean>

Implementation of

Interactor.isChecked

---

isDisabled()

isDisabled(locator): Promise<boolean>

Defined in: PlaywrightInteractor.ts:694

Whether the element is disabled, via the native disabled state — including the <fieldset disabled>/<optgroup disabled> cascades — or the nearest aria-disabled on the element or an ancestor being "true", so a re-enabled descendant of a disabled container reports false. The locator must address the control itself; a <label> is not retargeted.

Parameters

locator

PartLocator

Returns

Promise<boolean>

Implementation of

Interactor.isDisabled

---

isError()

isError(locator): Promise<boolean>

Defined in: PlaywrightInteractor.ts:725

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:705

Parameters

locator

PartLocator

Returns

Promise<boolean>

Implementation of

Interactor.isReadonly

---

isRequired()

isRequired(locator): Promise<boolean>

Defined in: PlaywrightInteractor.ts:717

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:729

Parameters

locator

PartLocator

Returns

Promise<boolean>

Implementation of

Interactor.isVisible

---

mouseDown()

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

Defined in: PlaywrightInteractor.ts:497

Parameters

locator

PartLocator

option?

Partial<MouseDownOption>

Returns

Promise<void>

Implementation of

Interactor.mouseDown

---

mouseEnter()

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

Defined in: PlaywrightInteractor.ts:525

Parameters

locator

PartLocator

_option?

Partial<MouseEnterOption>

Returns

Promise<void>

Implementation of

Interactor.mouseEnter

---

mouseLeave()

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

Defined in: PlaywrightInteractor.ts:529

Parameters

locator

PartLocator

_option?

Partial<MouseLeaveOption>

Returns

Promise<void>

Implementation of

Interactor.mouseLeave

---

mouseMove()

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

Defined in: PlaywrightInteractor.ts:489

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:515

Parameters

locator

PartLocator

_option?

Partial<MouseOutOption>

Returns

Promise<void>

Implementation of

Interactor.mouseOut

---

mouseOver()

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

Defined in: PlaywrightInteractor.ts:511

Parameters

locator

PartLocator

option?

Partial<HoverOption>

Returns

Promise<void>

Implementation of

Interactor.mouseOver

---

mouseUp()

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

Defined in: PlaywrightInteractor.ts:504

Parameters

locator

PartLocator

option?

Partial<MouseUpOption>

Returns

Promise<void>

Implementation of

Interactor.mouseUp

---

pressKey()

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

Defined in: PlaywrightInteractor.ts:549

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 note: with shift and a PRINTABLE key, KeyboardEvent.key is delivered as the literal key passed in — NOT case-folded to a shifted variant (Shift+'a' stays 'a', not 'A') — with shiftKey: true carrying the modifier. This was verified to hold identically in both jsdom (DOMInteractor) and Playwright (PlaywrightInteractor) against this repo's pinned toolchain; a caller that needs an actual shifted character (e.g. 'A', '!') passes it as key directly rather than relying on shift to transform a lowercase/ unshifted one — 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:210

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:190

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:160

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:176

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:443

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:438

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:593

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:586

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