Interface: KeyboardActions

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

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

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