Keyboard Steps

The keyboard steps simulate real key presses through Playwright's keyboard API - single keys against whatever currently has focus, single keys against a specific element, and multi-key combinations like Control+a or Shift+Tab. Because they generate genuine keydown/keyup events, they exercise keyboard shortcuts, form submission on Enter, focus traversal with Tab, combobox navigation with the arrow keys, and Escape-to-close behavior exactly the way a user's keyboard would.

Key names are forgiving. Feature files can use short lowercase aliases - enter, tab, esc, space, backspace, delete, up, down, left, right, home, end, pageup, pagedown - and webship-js normalizes them to Playwright's canonical names (Enter, Escape, ArrowDown, and so on) before pressing. Anything not in the alias table is passed through unchanged, so any valid Playwright key name works too. If a key name is invalid, the step fails with a friendly error that suggests real key names to try.

The "on the element" variants first resolve the CSS selector with a Playwright locator (taking the first match) and press the key while that element is focused - no separate focus step needed. For page-level presses, pair the step with a focus action such as When I focus on the element "#search" so the key lands where you expect.

Quick reference

Steps in detail

When I press the key "Enter"

Presses a single key against the page - the event goes to whatever element currently has focus. Aliases like enter, esc, tab, up, down, left, right, and space are normalized to their canonical Playwright names, so "esc" and "Escape" behave identically.

Given I am on "/keyboard.html"
 When I focus on the element "#inp"
  And I press the key "Enter"
 Then I should see "Enter"

When I press the key "Enter" on the element "#search"

Presses a single key while a specific element is focused. The selector is any CSS selector; the first match is used. This is the concise form when you do not want a separate focus step - ideal for triggering search on Enter, clearing a field with Backspace, or closing a dialog with Escape from within it. If the selector matches nothing focusable, the step fails with a hint to check the selector.

When I press the key "tab" on the element "#inp"
 And I press the key "ArrowDown" on the element ".combobox"
 And I press the key "Escape" on the element "[role=dialog]"

When I press the keys "Control+a"

Presses a key combination against the page. Combos join modifiers and the final key with + - Control+a, Meta+s, Shift+Tab, Alt+ArrowLeft, or chains like Control+Shift+P. The combo string is passed to Playwright as-is (no alias normalization inside combos), so use canonical modifier names: Control, Shift, Alt, Meta.

When I press the keys "Control+a"
 And I press the keys "Shift+Tab"
 And I press the keys "Control+Shift+P"

When I press the keys "Control+a" on the element "#editor"

Same combination handling, but focused on the element matched by the CSS selector first. Use it for editor shortcuts (Control+a to select all in a rich-text field, Control+Enter to submit a message box) that must reach a specific widget rather than the page.

When I press the keys "Control+a" on the element "#editor"
 And I press the keys "Control+Enter" on the element "#message"

Complete example

Adapted from tests/features/keyboard.feature, running against the examples/keyboard.html fixture:

Feature: Keyboard step definitions

  Scenario: Keyboard input
    Given I am on "/keyboard.html"
     When I focus on the element "#inp"
      And I press the key "Enter"
     Then I should see "Enter"
     When I press the key "tab" on the element "#inp"
      And I press the keys "Control+a"
      And I press the keys "Control+a" on the element "#inp"

Tips

• Keyboard-only navigation is also an accessibility check: chain Tab presses and then assert focus with the element steps to verify a usable tab order.
• These steps press and release. To type text into a field, use the form-field steps (When I fill in ...) instead - they handle clearing and input events for you.
• On macOS-style shortcuts remember Playwright's Meta is the Command key; Control is Ctrl on all platforms.

Back to all step groups