Lupa

Appearance

Lupa API Reference / commands / Keyboard

Class: Keyboard ​

Defined in: src/commands/keyboard.ts:76

Controls keyboard interactions natively within the browser context. It uses RPC calls to interact with Playwright's Keyboard object.

Use ​

when

  • Testing complex keyboard-driven user flows, native shortcuts, input events, or modifier-key combinations (e.g. Shift, Control, Alt).

Dont ​

use when

  • Filling simple forms or text fields. Instead, use locators (e.g., query().type(...) or query().fill(...)) which are much more resilient and perform auto-actionability checks.

Keyboard provides an api for managing a virtual keyboard. The high level api is keyboard.type(), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.

For finer control, you can use keyboard.down(), keyboard.up(), and keyboard.insertText() to manually fire events as if they were generated from a real keyboard.

An example of holding down Shift in order to select and delete some text:

Examples ​

typescript
import { keyboard } from '@pawel-up/lupa/commands'

await keyboard.type('Hello World!');
await keyboard.press('ArrowLeft');

await keyboard.down('Shift');
for (let i = 0; i < ' World'.length; i++) {
 await keyboard.press('ArrowLeft');
}
await keyboard.up('Shift')
await keyboard.press('Backspace')
// Result text will end up saying 'Hello!'

An example of pressing uppercase 'A' key:

typescript
import { keyboard } from '@pawel-up/lupa/commands'

await keyboard.press('Shift+KeyA');
// or
await keyboard.press('Shift+A');

An example to trigger select-all with the keyboard:

typescript
import { keyboard } from '@pawel-up/lupa/commands'

await keyboard.press('ControlOrMeta+A')

Constructors ​

Constructor ​

new Keyboard(): Keyboard

Returns ​

Keyboard

Methods ​

down() ​

down(key): Promise<void>

Defined in: src/commands/keyboard.ts:112

Dispatches a keydown event.

The key parameter can specify the intended KeyboardEvent.key value or a single character to generate the text for. A superset of the key values can be found here.

Examples of the keys are: F1 - F12, Digit0 - Digit9, KeyA - KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.

Following modification shortcuts are also supported: Shift, Control, Alt, Meta, ShiftLeft, ControlOrMeta. ControlOrMeta resolves to Control on Windows and Linux and to Meta on macOS.

Holding down Shift will type the text that corresponds to the key in the upper case.

If key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

If key is a modifier key, Shift, Meta, Control, or Alt, subsequent key presses will be sent with that modifier active. To release the modifier key, use keyboard.up().

After the key is pressed once, subsequent calls to keyboard.down() will have repeat set to true. To release the key, use keyboard.up().

Parameters ​

key ​

string

Name of the key to press down, such as Control or ArrowLeft.

Returns ​

Promise<void>

A promise that resolves when the keydown event is dispatched.

Example ​

typescript
import { keyboard } from '@pawel-up/lupa/commands'

await keyboard.down('Shift')

insertText() ​

insertText(text): Promise<void>

Defined in: src/commands/keyboard.ts:129

Dispatches only an input event, without emitting keydown, keypress or keyup events.

Parameters ​

text ​

string

The text to insert.

Returns ​

Promise<void>

A promise that resolves when the text is inserted.

Example ​

typescript
import { keyboard } from '@pawel-up/lupa/commands'

await keyboard.insertText('嗨')

press() ​

press(key, options?): Promise<void>

Defined in: src/commands/keyboard.ts:170

Dispatches keydown, keyup, and keypress/input events for a single key or modifier shortcut.

key can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the key values can be found at https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values.

Examples of the keys are: F1 - F12, Digit0 - Digit9, KeyA - KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.

Following modification shortcuts are also supported: Shift, Control, Alt, Meta, ShiftLeft, ControlOrMeta. ControlOrMeta resolves to Control on Windows and Linux and to Meta on macOS.

Holding down Shift will type the text that corresponds to the key in the upper case.

If key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

Shortcuts such as key: "Control+o", key: "Control++ or key: "Control+Shift+T" are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.

Parameters ​

key ​

string

Name of the key or shortcut to press, such as ArrowDown or Shift+a.

options? ​

KeyboardPressOptions

Additional settings to control the key press.

Returns ​

Promise<void>

A promise that resolves when the key press is completed.

Example ​

typescript
import { keyboard } from '@pawel-up/lupa/commands'

await keyboard.press('Backspace')
await keyboard.press('Control+A')

Remarks ​

Shortcut for keyboard.down() and keyboard.up().

type() ​

type(text, options?): Promise<void>

Defined in: src/commands/keyboard.ts:198

Types the text into the focused element, emitting keydown, keypress/input, and keyup events for each character.

Parameters ​

text ​

string

The text to type.

options? ​

KeyboardTypeOptions

Additional settings to control the typing speed.

Returns ​

Promise<void>

A promise that resolves when typing is completed.

Remarks ​

In most cases, you should use query(...).fill() instead. You only need to press keys one by one if there is special keyboard handling on the page - in this case use query(...).pressSequentially().

Modifier keys DO NOT effect keyboard.type. Holding down Shift will not type the text in upper case.

For characters that are not on a US keyboard, only an input event will be sent.

Example ​

typescript
import { keyboard } from '@pawel-up/lupa/commands'

await keyboard.type('Hello World', { delay: 50 })

up() ​

up(key): Promise<void>

Defined in: src/commands/keyboard.ts:215

Dispatches a keyup event.

Parameters ​

key ​

string

Name of the key to release, such as Shift or Control.

Returns ​

Promise<void>

A promise that resolves when the keyup event is dispatched.

Example ​

typescript
import { keyboard } from '@pawel-up/lupa/commands'

await keyboard.up('Shift')