Cypress App

press

Trigger native key events in your application to simulate keyboard interactions.

A keydown and keyup event will be dispatched directly to the browser window.

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 and great keyboard UX.

Syntax

cy.press(key)
cy.press(key, options)

Signature

interface PressCommand {
  (
    key: KeyPressSupportedKeys,
    options?: Partial<Cypress.Loggable> & Partial<Cypress.Timeoutable>
  ): void
}

Usage

Correct Usage

cy.get('input.first').focus()
cy.press(Cypress.Keyboard.Keys.TAB)
cy.get('input.second').should('have.focus')

Incorrect Usage

cy.get('input.first').focus()
cy.press(Cypress.Keyboard.Keys.TAB)
  // Errors because press yields null
  .should('have.focus')

Arguments

key (String)

The key to press. Values for non single character keys are available on Cypress.Keyboard.Keys, 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.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)

Pass in an options object to change the default behavior of .press().

Option	Default	Description
log	true	Displays the command in the Command log
timeout	defaultCommandTimeout	Time to wait for cy.press() to resolve before timing out

Yields

• cy.press() yields null.

Examples

Test focus order of tab

it('moves focus to the next form element when pressing Tab', () => {
  cy.visit('/my-login')
  cy.get('input.email').type('username')
  cy.press(Cypress.Keyboard.Keys.TAB)
  cy.get('input.password').should('have.focus')
})

Test autocomplete of search input with tab

it('autocompletes search input when pressing Tab', () => {
  cy.get('[data-cy="search"]').type('cy')
  cy.press(Cypress.Keyboard.Keys.TAB)
  cy.get('[data-cy="search"]').should('have.value', 'cypress')
})

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:

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.

// 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().

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

If your application prevents the default behavior of the beforeunload event, this may cause issues when navigating away from the current page.

History

Version	Changes
14.3.0	Added the .press() command
15.1.0	Expanded support to include named keys and single+multi-codepoint UTF-8 characters.

See also

• Cypress.Keyboard
• .focus()
• .focused()
• .type()