From 3a090863b644c13a38a47b82b564535a946d457d Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Fri, 22 Aug 2025 10:58:02 -0400 Subject: [PATCH 1/4] docs: updates cy.press() documentation to include expanded named keys, as well as utf-8 characters --- docs/api/commands/press.mdx | 63 ++++++++++++++++++++++++++++++++++--- 1 file changed, 59 insertions(+), 4 deletions(-) diff --git a/docs/api/commands/press.mdx b/docs/api/commands/press.mdx index f0bef379fe..7d2ac554b8 100644 --- a/docs/api/commands/press.mdx +++ b/docs/api/commands/press.mdx @@ -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 @@ -68,13 +66,69 @@ cy.press(Cypress.Keyboard.Keys.TAB) **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. +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 recommended that you reference these values from `Cypress.Keyboard.Keys` rather than passing in a string. ### Supported Keys | Reference | Value | | --------------------------- | ------- | +| `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"` | + +:::caution +Browser-Specific Functionality: +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). +::: + +## Supported Characters + +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') +``` + +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) +``` + +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). **options _(Object)_** @@ -125,6 +179,7 @@ If your application prevents the default behavior of the `beforeunload` event, t | 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 From d4b97595ce65a7dde3765d3060aa574b98be1b30 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Fri, 22 Aug 2025 11:14:24 -0400 Subject: [PATCH 2/4] lint --- docs/api/commands/press.mdx | 66 ++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/docs/api/commands/press.mdx b/docs/api/commands/press.mdx index 7d2ac554b8..1eb661b4d7 100644 --- a/docs/api/commands/press.mdx +++ b/docs/api/commands/press.mdx @@ -70,37 +70,41 @@ The key to press. The supported values are available on [`Cypress.Keyboard.Keys` ### Supported Keys -| Reference | Value | -| --------------------------- | ------- | -| `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"` | +| Reference | Value | +| --------------------------------- | -------------- | +| `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"` | :::caution + Browser-Specific Functionality: -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. +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). ::: @@ -176,9 +180,9 @@ If your application prevents the default behavior of the `beforeunload` event, t ## 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 From 95715b3af95f74319dacae08e42f9018fc44f3c6 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Fri, 22 Aug 2025 11:34:36 -0400 Subject: [PATCH 3/4] updates to structure --- docs/api/commands/press.mdx | 84 +++++++++++++++++++++---------------- 1 file changed, 47 insertions(+), 37 deletions(-) diff --git a/docs/api/commands/press.mdx b/docs/api/commands/press.mdx index 1eb661b4d7..b6d2f3a8cd 100644 --- a/docs/api/commands/press.mdx +++ b/docs/api/commands/press.mdx @@ -66,12 +66,15 @@ cy.press(Cypress.Keyboard.Keys.TAB) **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 recommended that you reference these values from `Cypress.Keyboard.Keys` rather than passing in a string. +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 +#### 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"` | @@ -98,41 +101,6 @@ The key to press. The supported values are available on [`Cypress.Keyboard.Keys` | `Cypress.Keyboard.Keys.F11` | `"F11"` | | `Cypress.Keyboard.Keys.F12` | `"F12"` | -:::caution - -Browser-Specific Functionality: -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). -::: - -## Supported Characters - -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') -``` - -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) -``` - -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). **options _(Object)_** @@ -170,14 +138,56 @@ 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 | From 1dbf3cee6f01a0c3ae2c62226199afecd02861ca Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Fri, 22 Aug 2025 11:40:26 -0400 Subject: [PATCH 4/4] lint --- docs/api/commands/press.mdx | 61 ++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 31 deletions(-) diff --git a/docs/api/commands/press.mdx b/docs/api/commands/press.mdx index b6d2f3a8cd..75ce817591 100644 --- a/docs/api/commands/press.mdx +++ b/docs/api/commands/press.mdx @@ -70,37 +70,36 @@ The key to press. Values for non single character keys are available on [`Cypres #### 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"` | - +| 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"` | **options _(Object)_**