Skip to content

Commit 8400e52

Browse files
type/press improvements (#6289)
* type/press improvements * lint fix
1 parent 447c421 commit 8400e52

File tree

2 files changed

+84
-16
lines changed

2 files changed

+84
-16
lines changed

docs/api/commands/press.mdx

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,23 @@ cy.press('́') // \u0301 (combining acute accent)
152152

153153
## Notes
154154

155+
### When to use cy.type()
156+
157+
While `.press()` dispatches native keyboard events, use [`cy.type()`](/api/commands/type) for:
158+
159+
- **Text input**: Typing multiple characters or words
160+
- **Special character sequences**: `{backspace}`, `{selectAll}`, `{moveToEnd}`
161+
- **Modifier combinations**: `{ctrl}c`, `{shift}b`
162+
- **Form filling**: When you need to simulate specific timing of typing behavior
163+
164+
```javascript
165+
// Use .press() for single key events
166+
cy.press(Cypress.Keyboard.Keys.TAB)
167+
168+
// Use .type() for text and complex sequences
169+
cy.get('input').type('Hello{backspace}World')
170+
```
171+
155172
### Strings with multiple characters
156173

157174
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).
@@ -176,7 +193,9 @@ If your application prevents the default behavior of the `beforeunload` event, t
176193

177194
## See also
178195

179-
- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api)
180-
- [`.focus()`](/api/commands/focus)
181-
- [`.focused()`](/api/commands/focused)
182-
- [`.type()`](/api/commands/type)
196+
- [`cy.type()`](/api/commands/type) - For typing text and special sequences
197+
- [`.focus()`](/api/commands/focus) - Focus elements before pressing keys
198+
- [`.focused()`](/api/commands/focused) - Assert focused elements
199+
- [`.click()`](/api/commands/click) - Click elements
200+
- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api) - Keyboard constants
201+
- [Accessibility Testing Guide](/app/guides/accessibility-testing) - Keyboard navigation patterns

docs/api/commands/type.mdx

Lines changed: 61 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,12 @@ To disable parsing special characters sequences, set the
7575
| `{selectAll}` | Selects all text by creating a `selection range` |
7676
| `{upArrow}` | Moves cursor up |
7777

78+
:::info
79+
80+
**Note**: For navigation keys like `Tab`, `Arrow` keys, and `Enter` in non-form contexts, consider using [`cy.press()`](/api/commands/press) for more accurate native keyboard event simulation.
81+
82+
:::
83+
7884
Text passed to `.type()` may also include any of these modifier character
7985
sequences:
8086

@@ -381,6 +387,23 @@ cy.get('body').type(
381387
cy.get('body').type('{shift}', { release: false }).get('li:first').click()
382388
```
383389

390+
### Combined Usage with cy.press()
391+
392+
For comprehensive keyboard testing, combine `.type()` and `.press()`:
393+
394+
#### Form navigation with keyboard
395+
396+
```javascript
397+
it('navigates form using keyboard only', () => {
398+
cy.get('input[name="firstName"]').type('Marcus')
399+
cy.press(Cypress.Keyboard.Keys.TAB)
400+
cy.get('input[name="lastName"]').should('have.focus').type('Baker')
401+
cy.press(Cypress.Keyboard.Keys.TAB)
402+
cy.get('input[name="email"]').should('have.focus').type('[email protected]')
403+
cy.press(Cypress.Keyboard.Keys.ENTER)
404+
})
405+
```
406+
384407
### Options
385408

386409
#### Force typing regardless of its actionable state
@@ -509,13 +532,39 @@ Any modifiers activated for the event are also listed in a `modifiers` column.
509532
alt="Cypress .type() key events table"
510533
/>
511534

512-
### Tabbing
535+
### When to use cy.press()
513536

514-
#### Typing `tab` key does not work
537+
While `.type()` is excellent for typing text content, use [`cy.press()`](/api/commands/press) for:
515538

516-
In the meantime, you can use the experimental
517-
[cypress-plugin-tab](https://github.com/Bkucera/cypress-plugin-tab) and can
518-
thumbs up [this issue](https://github.com/cypress-io/cypress/issues/299).
539+
- **Navigation keys**: `Tab`, `Arrow` keys, `Enter`, `Escape`
540+
- **Accessibility testing**: Focus management and keyboard navigation
541+
- **Single key events**: When you need native keyboard events rather than simulated ones
542+
- **Keys not supported by .type()**: Such as `{tab}`
543+
544+
```javascript
545+
// Use .type() for text input
546+
cy.get('input').type('Hello World')
547+
548+
// Use .press() for navigation and special keys
549+
cy.press(Cypress.Keyboard.Keys.TAB)
550+
cy.press(Cypress.Keyboard.Keys.ENTER)
551+
```
552+
553+
:::info
554+
555+
**Combining .type() and .press()**: You can use both commands together for comprehensive keyboard testing:
556+
557+
```javascript
558+
// Type text content
559+
cy.get('input.email').type('[email protected]')
560+
// Navigate with keyboard
561+
cy.press(Cypress.Keyboard.Keys.TAB)
562+
cy.get('input.password').type('password123')
563+
// Submit with keyboard
564+
cy.press(Cypress.Keyboard.Keys.ENTER)
565+
```
566+
567+
:::
519568

520569
### Modifiers
521570

@@ -660,10 +709,10 @@ following:
660709

661710
## See also
662711

663-
- [`.blur()`](/api/commands/blur)
664-
- [`.clear()`](/api/commands/clear)
665-
- [`.click()`](/api/commands/click)
666-
- [`.focus()`](/api/commands/focus)
667-
- [`cy.press()`](/api/commands/press)
668-
- [`.submit()`](/api/commands/submit)
669-
- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api)
712+
- [`cy.press()`](/api/commands/press) - For single key events and navigation
713+
- [`.focus()`](/api/commands/focus) - Focus elements before typing
714+
- [`.clear()`](/api/commands/clear) - Clear input values
715+
- [`.blur()`](/api/commands/blur) - Remove focus from elements
716+
- [`.click()`](/api/commands/click) - Click elements
717+
- [`.submit()`](/api/commands/submit) - Submit forms
718+
- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api) - Keyboard constants

0 commit comments

Comments
 (0)