Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
27 changes: 23 additions & 4 deletions docs/api/commands/press.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,23 @@ cy.press('́') // \u0301 (combining acute accent)

## Notes

### When to use cy.type()

While `.press()` dispatches native keyboard events, use [`cy.type()`](/api/commands/type) for:

- **Text input**: Typing multiple characters or words
- **Special character sequences**: `{backspace}`, `{selectAll}`, `{moveToEnd}`
- **Modifier combinations**: `{ctrl}c`, `{shift}b`
- **Form filling**: When you need to simulate specific timing of typing behavior

```javascript
// Use .press() for single key events
cy.press(Cypress.Keyboard.Keys.TAB)

// Use .type() for text and complex sequences
cy.get('input').type('Hello{backspace}World')
```

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

## See also

- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api)
- [`.focus()`](/api/commands/focus)
- [`.focused()`](/api/commands/focused)
- [`.type()`](/api/commands/type)
- [`cy.type()`](/api/commands/type) - For typing text and special sequences
- [`.focus()`](/api/commands/focus) - Focus elements before pressing keys
- [`.focused()`](/api/commands/focused) - Assert focused elements
- [`.click()`](/api/commands/click) - Click elements
- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api) - Keyboard constants
- [Accessibility Testing Guide](/app/guides/accessibility-testing) - Keyboard navigation patterns
73 changes: 61 additions & 12 deletions docs/api/commands/type.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,12 @@ To disable parsing special characters sequences, set the
| `{selectAll}` | Selects all text by creating a `selection range` |
| `{upArrow}` | Moves cursor up |

:::info

**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.

:::

Text passed to `.type()` may also include any of these modifier character
sequences:

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

### Combined Usage with cy.press()

For comprehensive keyboard testing, combine `.type()` and `.press()`:

#### Form navigation with keyboard

```javascript
it('navigates form using keyboard only', () => {
cy.get('input[name="firstName"]').type('Marcus')
cy.press(Cypress.Keyboard.Keys.TAB)
cy.get('input[name="lastName"]').should('have.focus').type('Baker')
cy.press(Cypress.Keyboard.Keys.TAB)
cy.get('input[name="email"]').should('have.focus').type('[email protected]')
cy.press(Cypress.Keyboard.Keys.ENTER)
})
```

### Options

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

### Tabbing
### When to use cy.press()

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

In the meantime, you can use the experimental
[cypress-plugin-tab](https://github.com/Bkucera/cypress-plugin-tab) and can
thumbs up [this issue](https://github.com/cypress-io/cypress/issues/299).
- **Navigation keys**: `Tab`, `Arrow` keys, `Enter`, `Escape`
- **Accessibility testing**: Focus management and keyboard navigation
- **Single key events**: When you need native keyboard events rather than simulated ones
- **Keys not supported by .type()**: Such as `{tab}`

```javascript
// Use .type() for text input
cy.get('input').type('Hello World')

// Use .press() for navigation and special keys
cy.press(Cypress.Keyboard.Keys.TAB)
cy.press(Cypress.Keyboard.Keys.ENTER)
```

:::info

**Combining .type() and .press()**: You can use both commands together for comprehensive keyboard testing:

```javascript
// Type text content
cy.get('input.email').type('[email protected]')
// Navigate with keyboard
cy.press(Cypress.Keyboard.Keys.TAB)
cy.get('input.password').type('password123')
// Submit with keyboard
cy.press(Cypress.Keyboard.Keys.ENTER)
```

:::

### Modifiers

Expand Down Expand Up @@ -660,10 +709,10 @@ following:

## See also

- [`.blur()`](/api/commands/blur)
- [`.clear()`](/api/commands/clear)
- [`.click()`](/api/commands/click)
- [`.focus()`](/api/commands/focus)
- [`cy.press()`](/api/commands/press)
- [`.submit()`](/api/commands/submit)
- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api)
- [`cy.press()`](/api/commands/press) - For single key events and navigation
- [`.focus()`](/api/commands/focus) - Focus elements before typing
- [`.clear()`](/api/commands/clear) - Clear input values
- [`.blur()`](/api/commands/blur) - Remove focus from elements
- [`.click()`](/api/commands/click) - Click elements
- [`.submit()`](/api/commands/submit) - Submit forms
- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api) - Keyboard constants