diff --git a/docs/api/commands/press.mdx b/docs/api/commands/press.mdx index 7221a48671..6ca16c24e0 100644 --- a/docs/api/commands/press.mdx +++ b/docs/api/commands/press.mdx @@ -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). @@ -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 diff --git a/docs/api/commands/type.mdx b/docs/api/commands/type.mdx index 97f7030c87..c637e6c53c 100644 --- a/docs/api/commands/type.mdx +++ b/docs/api/commands/type.mdx @@ -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: @@ -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('marcus@example.com') + cy.press(Cypress.Keyboard.Keys.ENTER) +}) +``` + ### Options #### Force typing regardless of its actionable state @@ -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('user@example.com') +// 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 @@ -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