Skip to content

docs: updates cy.press() documentation to include expanded named keys, as well as utf-8 characters #6256

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: release/15.1.0
Choose a base branch
from
Open

docs: updates cy.press() documentation to include expanded named keys, as well as utf-8 characters #6256

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3a09086
docs: updates cy.press() documentation to include expanded named keys…
cacieprins Aug 22, 2025
d4b9759
lint
jennifer-shehane Aug 22, 2025
95715b3
updates to structure
jennifer-shehane Aug 22, 2025
1dbf3ce
lint
jennifer-shehane Aug 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 81 additions & 13 deletions docs/api/commands/press.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,7 @@ Trigger native key events in your application to simulate keyboard interactions.

A `keydown`, `press`, and `keyup` event will be dispatched directly to the browser window.

Unlike `cy.type()`, which is best for typing character keys, `cy.press()` will dispatch real keyboard events rather than simulated ones. This command is especially useful when testing focus management and keyboard navigation patterns which are critical for [accessibility testing](/app/guides/accessibility-testing) and great keyboard UX.

Currently, the only key supported is `Tab`.
Unlike `cy.type()`, which is best for typing multiple character keys, `cy.press()` will dispatch real keyboard events rather than simulated ones. This command is especially useful when testing focus management and keyboard navigation patterns which are critical for [accessibility testing](/app/guides/accessibility-testing) and great keyboard UX.

:::caution

Expand Down Expand Up @@ -68,13 +66,40 @@ cy.press(Cypress.Keyboard.Keys.TAB)

<Icon name="angle-right" /> **key _(String)_**

The key to press. The supported values are available on [`Cypress.Keyboard.Keys`](/api/cypress-api/keyboard-api), and may change from time to time. It's recomended that you reference these values from `Cypress.Keyboard.Keys` rather than passing in a string.

### Supported Keys

| Reference | Value |
| --------------------------- | ------- |
| `Cypress.Keyboard.Keys.TAB` | `"Tab"` |
The key to press. Values for non single character keys are available on [`Cypress.Keyboard.Keys`](/api/cypress-api/keyboard-api), and may change from time to time. It's recommended that you reference these values from `Cypress.Keyboard.Keys` rather than passing in a string when available.

#### Supported Keys

| Reference | Value |
| --------------------------------- | -------------------------------------------------------------------- |
| Letters | `"a"` through `"z"`, `"A"` through `"Z"` |
| Numbers | `"0"`, `"1"`, `"2"`, `"3"`, `"4"`, `"5"`, `"6"`, `"7"`, `"8"`, `"9"` |
| Special Characters | `"!"`, `"@"`, `"#"`, `'+'`, `"€"`, `"é"`, etc. |
| `Cypress.Keyboard.Keys.DOWN` | `"ArrowDown"` |
| `Cypress.Keyboard.Keys.LEFT` | `"ArrowLeft"` |
| `Cypress.Keyboard.Keys.RIGHT` | `"ArrowRight"` |
| `Cypress.Keyboard.Keys.UP` | `"ArrowUp"` |
| `Cypress.Keyboard.Keys.END` | `"End"` |
| `Cypress.Keyboard.Keys.HOME` | `"Home"` |
| `Cypress.Keyboard.Keys.PAGEDOWN` | `"PageDown"` |
| `Cypress.Keyboard.Keys.PAGEUP` | `"PageUp"` |
| `Cypress.Keyboard.Keys.ENTER` | `"Enter"` |
| `Cypress.Keyboard.Keys.TAB` | `"Tab"` |
| `Cypress.Keyboard.Keys.BACKSPACE` | `"Backspace"` |
| `Cypress.Keyboard.Keys.DELETE` | `"Delete"` |
| `Cypress.Keyboard.Keys.INSERT` | `"Insert"` |
| `Cypress.Keyboard.Keys.F1` | `"F1"` |
| `Cypress.Keyboard.Keys.F2` | `"F2"` |
| `Cypress.Keyboard.Keys.F3` | `"F3"` |
| `Cypress.Keyboard.Keys.F4` | `"F4"` |
| `Cypress.Keyboard.Keys.F5` | `"F5"` |
| `Cypress.Keyboard.Keys.F6` | `"F6"` |
| `Cypress.Keyboard.Keys.F7` | `"F7"` |
| `Cypress.Keyboard.Keys.F8` | `"F8"` |
| `Cypress.Keyboard.Keys.F9` | `"F9"` |
| `Cypress.Keyboard.Keys.F10` | `"F10"` |
| `Cypress.Keyboard.Keys.F11` | `"F11"` |
| `Cypress.Keyboard.Keys.F12` | `"F12"` |

<Icon name="angle-right" /> **options _(Object)_**

Expand Down Expand Up @@ -112,19 +137,62 @@ it('autocompletes search input when pressing Tab', () => {
})
```

### Type a single character

Single character keys are supported, like `a`, `b`, `c`, etc. There is no need to reference `Cypress.Keyboard.Keys` record for these keys, just type them normally as a string:

```javascript
cy.get('input').focus()
cy.press('a')
```

### Type a multi-codepoint UTF-8 character

Multi-codepoint UTF-8 characters are also supported and do not need to be entered as individual codepoints. For example, `é` can be either one single codepoint or two separate codepoints when the accent is pressed as a subsequent modifier key. You do not need to press each codepoint separately; just type the entire character as a string.

```javascript
// works
cy.get('input').focus()
cy.press('é') // \u00e9 (composed é)
cy.press('é') // \u0065\u0301 (e + combining acute accent)

// also fine, but not necessary
cy.get('input').focus()
cy.press('e') // \u0065
cy.press('́') // \u0301 (combining acute accent)
```

## Notes

### Strings with multiple characters

Strings with multiple characters are not supported. If you need to input longer strings into a text input or similar, use [`cy.type()`](/api/commands/type).

```js
cy.get('input').type('Hello, World') // Type 'Hello, World' into the 'input'
```

### Transient activation

By dispatching native keyboard events to the browser, this command will cause the browser to enter [Transient activation](https://developer.mozilla.org/en-US/docs/Glossary/Transient_activation) state.

If your application prevents the default behavior of the `beforeunload` event, this may cause issues when navigating away from the current page.

### Firefox F6 key

In Firefox, [the F6 key is used to change focus to the next frame](https://support.mozilla.org/en-US/kb/keyboard-shortcuts-perform-firefox-tasks-quickly#w_current-page).
Pressing F6 via `cy.press()` will dispatch the initial `keydown` appropriately, but
due to the focus change, the `keyup` event will not be dispatched to the iframe containing
the application under test.

To re-focus the iframe after pressing F6, use [`cy.focus()`](/api/commands/focus).

## History

| Version | Changes |
| ----------------------------------- | ---------------------------- |
| [14.3.0](/app/references/changelog) | Added the `.press()` command |
| Version | Changes |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| [14.3.0](/app/references/changelog) | Added the `.press()` command |
| [15.1.0](/app/references/changelog) | Expanded support to include named keys and single+multi-codepoint UTF-8 characters. |

## See also

Expand Down