Interface: KeyboardActions

Defined in: packages/core/src/interactor/Interactor.ts:149

Keyboard-driven interactions: dispatch of real key events, distinct from the value-filling FormActions path. A capability facet of Interactor (ADR-007).

Extended by

• Interactor

Methods

pressKey()

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

Defined in: packages/core/src/interactor/Interactor.ts:183

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