From 72f19176cda8153b0016be4451437e4fa1d1fa51 Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Mon, 25 Aug 2025 10:08:05 -0400 Subject: [PATCH 1/4] docs: updates cy.press() documentation to include expanded named keys, as well as utf-8 characters (#6256) * docs: updates cy.press() documentation to include expanded named keys, as well as utf-8 characters * lint * updates to structure * lint --------- Co-authored-by: Jennifer Shehane --- docs/api/commands/press.mdx | 94 ++++++++++++++++++++++++++++++++----- 1 file changed, 81 insertions(+), 13 deletions(-) diff --git a/docs/api/commands/press.mdx b/docs/api/commands/press.mdx index f0bef379fe..75ce817591 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,40 @@ 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. - -### 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"` | **options _(Object)_** @@ -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 From 7c90f67fc5323d14c659208ca7d1608d1bdc5ce3 Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Thu, 28 Aug 2025 10:31:39 -0400 Subject: [PATCH 2/4] docs: remove F-keys from cy.press() documentation (#6261) * docs: remove f keys from cy.press doc * prettier --- docs/api/commands/press.mdx | 37 +++++++------------------------------ 1 file changed, 7 insertions(+), 30 deletions(-) diff --git a/docs/api/commands/press.mdx b/docs/api/commands/press.mdx index 75ce817591..03e2db8901 100644 --- a/docs/api/commands/press.mdx +++ b/docs/api/commands/press.mdx @@ -16,15 +16,6 @@ A `keydown`, `press`, and `keyup` event will be dispatched directly to the brows 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 - -Supported Browsers: -This command is supported in chromium browsers and Firefox versions >= v135. WebKit -is not supported. This command will fail if executed in a browser that does not support -it. - -::: - ## Syntax ```javascript @@ -88,18 +79,13 @@ The key to press. Values for non single character keys are available on [`Cypres | `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"` | +| `Cypress.Keyboard.Keys.SPACE` | `"Space"` | + +:::info + +F1-F12 keys are not supported. These keys are used for browser shortcuts, and can prevent the test suite from executing properly after they are pressed. + +::: **options _(Object)_** @@ -178,15 +164,6 @@ By dispatching native keyboard events to the browser, this command will cause th 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 7db7978b30a5ced3759f33e6efae25139805b793 Mon Sep 17 00:00:00 2001 From: Bill Glesias Date: Tue, 2 Sep 2025 16:55:37 -0400 Subject: [PATCH 3/4] chore: add the 15.1.0 changelog (#6265) --- docs/app/references/changelog.mdx | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index 468f819ba2..4bb74f78b6 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -8,6 +8,33 @@ sidebar_label: Changelog # Changelog +## 15.1.0 + +_Released 09/02/2025_ + +**Features:** + +- Expanded `cy.press()` to support more key types. Addresses [#31051](https://github.com/cypress-io/cypress/issues/31051) and [#31488](https://github.com/cypress-io/cypress/issues/31488). Addressed in [#31496](https://github.com/cypress-io/cypress/pull/31496). + +**Bugfixes:** + +- Fixed an issue where OS distributions and releases were sometimes not properly populated for Module API results and Cloud recordings. Fixes [#30533](https://github.com/cypress-io/cypress/issues/30533). Addressed in [#32283](https://github.com/cypress-io/cypress/pull/32283). +- Fixed an issue where Cypress would fail to run on GNOME if GTK 4 and GTK 2/3 were detected in the Electron process. Addresses [#32361](https://github.com/cypress-io/cypress/issues/32361). +- Fixed an issue where the open Studio button would incorrectly show for component tests. Addressed in [#32315](https://github.com/cypress-io/cypress/pull/32315). +- Fixed an issue where the TypeScript compiler wasn't being resolved correctly when `@cypress/webpack-batteries-included-preprocessor` was used as a standalone package. Fixes [#32338](https://github.com/cypress-io/cypress/issues/32338). +- Fixed an issue where `tsx` was not being loaded correctly into the Cypress configuration process due to spaces being present in the path. Fixes [#32398](https://github.com/cypress-io/cypress/issues/32398). + +**Misc:** + +- Updated the Cypress Studio panel to have a darker gray background. Addressed in [#32333](https://github.com/cypress-io/cypress/pull/32333). + +**Dependency Updates:** + +- Upgraded `esbuild` from `0.15.3` to `0.25.2`. Addressed in [#32231](https://github.com/cypress-io/cypress/pull/32231). +- Upgraded `image-size` from `1.1.1` to `1.2.1`. Addressed in [#32232](https://github.com/cypress-io/cypress/pull/32232). +- Upgraded `tar` from `6.1.5` to `6.2.1`. Addressed in [#32229](https://github.com/cypress-io/cypress/pull/32229). +- Upgraded `axios` from `1.8.3` to `1.11.0`. Addresses [#32347](https://github.com/cypress-io/cypress/issues/32347). + ## 15.0.0 _Released 08/20/2025_ From 55a42a58fff08252901ab1454d030d97f0368793 Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Tue, 23 Sep 2025 12:20:39 -0400 Subject: [PATCH 4/4] docs: correct & clarify how ancillary events are dispatched during keyDown/Up patterns (#6259) * clarify behavior of keypress/input events * clarify --- docs/api/commands/press.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/commands/press.mdx b/docs/api/commands/press.mdx index 03e2db8901..8ba9f37b87 100644 --- a/docs/api/commands/press.mdx +++ b/docs/api/commands/press.mdx @@ -12,7 +12,7 @@ componentSpecific: false 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. +A `keydown` and `keyup` event will be dispatched directly to the browser window. If an input changes due to these events, the proper `input` event will be dispatched. 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.