You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 <[email protected]>
Copy file name to clipboardExpand all lines: docs/api/commands/press.mdx
+81-13Lines changed: 81 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,9 +14,7 @@ Trigger native key events in your application to simulate keyboard interactions.
14
14
15
15
A `keydown`, `press`, and `keyup` event will be dispatched directly to the browser window.
16
16
17
-
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.
18
-
19
-
Currently, the only key supported is `Tab`.
17
+
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.
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.
72
-
73
-
### Supported Keys
74
-
75
-
| Reference | Value |
76
-
| --------------------------- | ------- |
77
-
|`Cypress.Keyboard.Keys.TAB`|`"Tab"`|
69
+
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.
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:
143
+
144
+
```javascript
145
+
cy.get('input').focus()
146
+
cy.press('a')
147
+
```
148
+
149
+
### Type a multi-codepoint UTF-8 character
150
+
151
+
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.
152
+
153
+
```javascript
154
+
// works
155
+
cy.get('input').focus()
156
+
cy.press('é') // \u00e9 (composed é)
157
+
cy.press('é') // \u0065\u0301 (e + combining acute accent)
158
+
159
+
// also fine, but not necessary
160
+
cy.get('input').focus()
161
+
cy.press('e') // \u0065
162
+
cy.press('́') // \u0301 (combining acute accent)
163
+
```
164
+
115
165
## Notes
116
166
167
+
### Strings with multiple characters
168
+
169
+
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).
170
+
171
+
```js
172
+
cy.get('input').type('Hello, World') // Type 'Hello, World' into the 'input'
173
+
```
174
+
117
175
### Transient activation
118
176
119
177
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.
120
178
121
179
If your application prevents the default behavior of the `beforeunload` event, this may cause issues when navigating away from the current page.
122
180
181
+
### Firefox F6 key
182
+
183
+
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).
184
+
Pressing F6 via `cy.press()` will dispatch the initial `keydown` appropriately, but
185
+
due to the focus change, the `keyup` event will not be dispatched to the iframe containing
186
+
the application under test.
187
+
188
+
To re-focus the iframe after pressing F6, use [`cy.focus()`](/api/commands/focus).
0 commit comments