Playwright.Keyboard (Playwright v1.65.0-rc.3)

Copy Markdown View Source

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

For finer control, you can use Playwright.Keyboard.down/2, Playwright.Keyboard.up/2, and Playwright.Keyboard.insert_text/2 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:

keyboard = Page.keyboard(page)
Keyboard.type!(keyboard, "Hello World!")
Keyboard.press!(keyboard, "ArrowLeft")

Keyboard.down!(keyboard, "Shift")
for _ <- 1..String.length(" World"), do: Keyboard.press!(keyboard, "ArrowLeft")
Keyboard.up!(keyboard, "Shift")

Keyboard.press!(keyboard, "Backspace")
# Result text will end up saying 'Hello!'

An example of pressing uppercase A

Page.keyboard(page) |> Keyboard.press!("Shift+KeyA")
# or
Page.keyboard(page) |> Keyboard.press!("Shift+A")

An example to trigger select-all with the keyboard

Page.keyboard(page) |> Keyboard.press!("ControlOrMeta+A")

Since Playwright 1.8.

The examples alias the modules they use (alias Playwright.{Locator, Page}).

Summary

Types

Options of press/3, see its docs.

t()

A Keyboard handle. Compare handles with ==, their fields are internal.

Options of type/3, see its docs.

Functions

Dispatches a keydown event.

Like down/2, but returns the value and raises on error.

Dispatches only input event, does not emit the keydown, keyup or keypress events.

Like insert_text/2, but returns the value and raises on error.

Like press/3, but returns the value and raises on error.

Like type/3, but returns the value and raises on error.

Dispatches a keyup event.

Like up/2, but returns the value and raises on error.

Types

press_options()

@type press_options() :: [{:delay, number()}] | %{optional(:delay) => number()}

Options of press/3, see its docs.

t()

@type t() :: %Playwright.Keyboard{_page: term()}

A Keyboard handle. Compare handles with ==, their fields are internal.

type_options()

@type type_options() :: [{:delay, number()}] | %{optional(:delay) => number()}

Options of type/3, see its docs.

Functions

down(keyboard, key)

@spec down(t(), String.t()) :: :ok | {:error, Playwright.error()}

Dispatches a keydown event.

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 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 Playwright.Keyboard.up/2.

After the key is pressed once, subsequent calls to Playwright.Keyboard.down/2 will have repeat set to true. To release the key, use Playwright.Keyboard.up/2.

Note

Modifier keys DO influence Playwright.Keyboard.down/2. Holding down Shift will type the text in upper case.

Since Playwright 1.8.

Arguments

  • key - Name of the key to press or a character to generate, such as ArrowLeft or a.

down!(keyboard, key)

@spec down!(t(), String.t()) :: :ok

Like down/2, but returns the value and raises on error.

insert_text(keyboard, text)

@spec insert_text(t(), String.t()) :: :ok | {:error, Playwright.error()}

Dispatches only input event, does not emit the keydown, keyup or keypress events.

Usage

Page.keyboard(page) |> Keyboard.insert_text!("嗨")

Note

Modifier keys DO NOT effect Playwright.Keyboard.insert_text/2. Holding down Shift will not type the text in upper case.

Since Playwright 1.8.

Arguments

  • text - Sets input to the specified text value.

insert_text!(keyboard, text)

@spec insert_text!(t(), String.t()) :: :ok

Like insert_text/2, but returns the value and raises on error.

press(keyboard, key, options \\ [])

@spec press(t(), String.t(), press_options()) :: :ok | {:error, Playwright.error()}

Tip

In most cases, you should use Playwright.Locator.press/3 instead.

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

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.

Usage

page = Browser.new_page!(browser)
Page.goto!(page, "https://keycode.info")
Page.keyboard(page) |> Keyboard.press!("A")
Page.screenshot!(page, path: "A.png")
Page.keyboard(page) |> Keyboard.press!("ArrowLeft")
Page.screenshot!(page, path: "ArrowLeft.png")
Page.keyboard(page) |> Keyboard.press!("Shift+O")
Page.screenshot!(page, path: "O.png")
Browser.close!(browser)

Shortcut for Playwright.Keyboard.down/2 and Playwright.Keyboard.up/2.

Since Playwright 1.8.

Arguments

  • key - Name of the key to press or a character to generate, such as ArrowLeft or a.

Options

  • :delay (number/0) - Time to wait between keydown and keyup in milliseconds. Defaults to 0.

press!(keyboard, key, options \\ [])

@spec press!(t(), String.t(), press_options()) :: :ok

Like press/3, but returns the value and raises on error.

type(keyboard, text, options \\ [])

@spec type(t(), String.t(), type_options()) :: :ok | {:error, Playwright.error()}

Caution

In most cases, you should use Playwright.Locator.fill/3 instead. You only need to press keys one by one if there is special keyboard handling on the page - in this case use Playwright.Locator.press_sequentially/3.

Sends a keydown, keypress/input, and keyup event for each character in the text.

To press a special key, like Control or ArrowDown, use Playwright.Keyboard.press/3.

Usage

# Types instantly
Page.keyboard(page) |> Keyboard.type!("Hello")
# Types slower, like a user
Page.keyboard(page) |> Keyboard.type!("World", delay: 100)

Note

Modifier keys DO NOT effect Playwright.Keyboard.type/3. Holding down Shift will not type the text in upper case.

Note

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

Since Playwright 1.8.

Arguments

  • text - A text to type into a focused element.

Options

  • :delay (number/0) - Time to wait between key presses in milliseconds. Defaults to 0.

type!(keyboard, text, options \\ [])

@spec type!(t(), String.t(), type_options()) :: :ok

Like type/3, but returns the value and raises on error.

up(keyboard, key)

@spec up(t(), String.t()) :: :ok | {:error, Playwright.error()}

Dispatches a keyup event.

Since Playwright 1.8.

Arguments

  • key - Name of the key to press or a character to generate, such as ArrowLeft or a.

up!(keyboard, key)

@spec up!(t(), String.t()) :: :ok

Like up/2, but returns the value and raises on error.