feat: extend Cypress.Keyboard.Keys and cy.press to support (almost) all keyboard keys (#31496)

* feat: extend Cypress.Keyboard.Keys and cy.press to support all keyboard keys

* Update cli/types/cypress.d.ts

* reference urls for codepoints

* type defs for expanded keys; tests

* changelog

* rm modifier keys temporarily - see WIP @ feat/key-press-modifier-keys

* Add pr link to changelog

* reduce repetition with key codes; remove unsupported capslock keycode

* only "key" special function keys in Cypress.Keyboard.Keys - otherwise, support any single character even if multiple codepoints

* do not refocus on f6 - f6 behavior keyup is indeterminate, so do not assert in that special case

* clean up keyboard key types, clean up duplicate def from merge

* various cleanup - wip - need multi-codepoint fix

* support multi-codepoint characters

* properly dispatch each part of a multipart utf-8 character

* fix import

* fix dtslint

* tscheck

* fix spacing

* Apply suggestions from code review

* changelog

* changelog

* ensure input actions are released in bidi; add test for keypress and input events for firefox

* fix keypress & input events in chrome

* consistent debug

* rm debug logging from input fixture

* some typos, changelog version

* fix toSupportedKey guard fn to properly reject non-strings

* add Space as named key, remove warnings re legacy firefox

* fix space

* support single-digit number keys

* remove support for F-keys

* add test cmd to types pkg

* rm failing vitest project config

* fix changelog

* clean up types a bit for single digit numbers

* more updates

---------

Co-authored-by: Cacie Prins <[email protected]>
Co-authored-by: Cacie Prins <[email protected]>

Author: jennifer-shehane

cli/CHANGELOG.md

@@ -1,8 +1,12 @@
 <!-- See the ../guides/writing-the-cypress-changelog.md for details on writing the changelog. -->
-## 15.0.1
+## 15.1.0
 
 _Released 08/26/2025 (PENDING)_
 
+**Features:**
+
+- Expanded `cy.press()` to support more key types. Addresses [#31051](https://github.com/cypress-io/cypress/issues/31051) and [#31488](https://github.com/cypress-io/cypress/issues/31488). Addressed in [#31496](https://github.com/cypress-io/cypress/pull/31496).
+
 **Bugfixes:**
 
 - Fixed an issue where OS distributions and releases were sometimes not properly populated for Module API results and Cloud recordings. Fixes [#30533](https://github.com/cypress-io/cypress/issues/30533). Addressed in [#32283](https://github.com/cypress-io/cypress/pull/32283).

cli/types/cypress-automation.d.ts

@@ -0,0 +1,18 @@
+declare namespace Cypress {
+  type SupportedNamedKey = 'ArrowDown' |
+  'ArrowLeft' |
+  'ArrowRight' |
+  'ArrowUp' |
+  'End' |
+  'Home' |
+  'PageDown' |
+  'PageUp' |
+  'Space' |
+  'Enter' |
+  'Tab' |
+  'Backspace' |
+  'Delete' |
+  'Insert'
+
+  type SupportedKey = SupportedNamedKey | string | number
+}

cli/types/cypress.d.ts

@@ -2,7 +2,7 @@
 /// <reference path="./cypress-npm-api.d.ts" />
 /// <reference path="./cypress-eventemitter.d.ts" />
 /// <reference path="./cypress-type-helpers.d.ts" />
-
+/// <reference path="./cypress-automation.d.ts" />
 declare namespace Cypress {
   type FileContents = string | any[] | object
   type HistoryDirection = 'back' | 'forward'
@@ -684,7 +684,20 @@ declare namespace Cypress {
     Keyboard: {
       defaults(options: Partial<KeyboardDefaultsOptions>): void
       Keys: {
+        DOWN: 'ArrowDown',
+        LEFT: 'ArrowLeft',
+        RIGHT: 'ArrowRight',
+        UP: 'ArrowUp',
+        END: 'End',
+        HOME: 'Home',
+        PAGEDOWN: 'PageDown',
+        PAGEUP: 'PageUp',
+        ENTER: 'Enter',
         TAB: 'Tab',
+        BACKSPACE: 'Backspace',
+        SPACE: 'Space',
+        DELETE: 'Delete',
+        INSERT: 'Insert',
       },
     }
 
@@ -1765,7 +1778,7 @@ declare namespace Cypress {
      *    cy.press(Cypress.Keyboard.Keys.TAB) // dispatches a keydown and press event to the browser, followed by a keyup event.
      * @see https://on.cypress.io/press
      */
-    press(key: typeof Cypress.Keyboard.Keys[keyof typeof Cypress.Keyboard.Keys], options?: Partial<Loggable & Timeoutable>): Chainable<null>
+    press(key: SupportedKey, options?: Partial<Loggable & Timeoutable>): Chainable<null>
 
     /**
      * Get the immediately preceding sibling of each element in a set of the elements.

package.json

@@ -57,7 +57,7 @@
     "stop-only": "npx stop-only --skip .cy,.publish,.projects,node_modules,dist,dist-test,fixtures,lib,bower_components,src,__snapshots__,patches --exclude cypress-tests.ts,*only.cy.js",
     "stop-only-all": "yarn stop-only --folder packages",
     "pretest": "yarn ensure-deps",
-    "test": "yarn lerna exec yarn test --scope=cypress --scope=@packages/{config,data-context,driver,electron,errors,extension,https-proxy,launcher,net-stubbing,network,packherd-require,proxy,rewriter,scaffold-config,socket,v8-snapshot-require,telemetry,stderr-filtering} --scope=@tooling/{electron-mksnapshot,v8-snapshot}",
+    "test": "yarn lerna exec yarn test --scope=cypress --scope=@packages/{config,data-context,driver,electron,errors,extension,https-proxy,launcher,net-stubbing,network,packherd-require,proxy,rewriter,scaffold-config,socket,v8-snapshot-require,telemetry,stderr-filtering,types} --scope=@tooling/{electron-mksnapshot,v8-snapshot}",
     "test-debug": "lerna exec yarn test-debug --ignore=@packages/{driver,root,static,web-config}",
     "test-integration": "lerna exec yarn test-integration --ignore=@packages/{driver,root,static,web-config}",
     "test-mocha": "mocha --reporter spec scripts/spec.js",

packages/driver/cypress/e2e/commands/actions/press.cy.ts

@@ -1,21 +1,49 @@
 describe('src/cy/commands/actions/press', () => {
-  it('dispatches the tab keypress to the AUT', () => {
-    // Non-BiDi firefox is not supported
-    if (Cypress.browser.family === 'firefox' && Cypress.browserMajorVersion() < 135) {
-      return
-    }
-
-    // TODO: Webkit is not supported. https://github.com/cypress-io/cypress/issues/31054
-    if (Cypress.isBrowser('webkit')) {
-      return
-    }
+  // TODO: Webkit is not supported. https://github.com/cypress-io/cypress/issues/31054
+  if (Cypress.isBrowser('webkit')) {
+    return
+  }
 
+  beforeEach(() => {
     cy.visit('/fixtures/input_events.html')
+  })
 
-    cy.press(Cypress.Keyboard.Keys.TAB)
-
-    cy.get('#keydown').should('have.value', 'Tab')
+  it('fires the click event on the button when the named key is sent', () => {
+    cy.get('#button').focus()
+    cy.get('#button').should('be.focused')
+    cy.press(Cypress.Keyboard.Keys.SPACE)
+    cy.get('#checkbox').should('be.checked')
+  })
 
-    cy.get('#keyup').should('have.value', 'Tab')
+  it('fires the click event on the button when a space is sent', () => {
+    cy.get('#button').focus()
+    cy.get('#button').should('be.focused')
+    cy.press(' ')
+    cy.get('#checkbox').should('be.checked')
   })
+
+  const testKeyDownUp = (key) => {
+    it(`dispatches ${key} keypress to the AUT`, () => {
+      cy.press(key)
+      // spacebar is a special case - it's both a named key and a single character,
+      // but when we dispatch the named key (via codepoint in bidi, via `Space` in CDP)
+      // we get the space character, not the name of the key.
+      cy.get('#keydown').should('have.value', key === 'Space' ? ' ' : key)
+    })
+  }
+
+  Object.values(Cypress.Keyboard.Keys).forEach(testKeyDownUp)
+
+  // sets truncated for speed
+
+  // // Numbers
+  ;['0', '1'].forEach(testKeyDownUp)
+
+  ;[0, 1].forEach(testKeyDownUp)
+
+  // // Letters
+  ;['a', 'z'].forEach(testKeyDownUp)
+
+  // // Special characters
+  ;['!', ' ', '€', 'é'].forEach(testKeyDownUp)
 })

packages/driver/cypress/fixtures/input_events.html

@@ -3,15 +3,29 @@
 <head>
   <title>Input Event Monitor</title>
   <script defer>
-    ['keydown', 'keyup'].forEach((ev) => {
+    ['keydown', 'keyup', 'keypress', 'input'].forEach((ev) => {
       document.addEventListener(ev, (data) => {
-        document.getElementById(ev).value = data.key
+        console.log(ev, data)
+        document.getElementById(ev).value += data.key ?? data.data
+      })
+    })
+    document.addEventListener('DOMContentLoaded', () => {
+      document.getElementById('button').addEventListener('click', (data) => {
+        console.log('button click', data)
+        document.getElementById('checkbox').checked = !document.getElementById('checkbox').checked
       })
     })
   </script>
 </head>
 
 <body>
-  <input type="text" id="keyup" />
   <input type="text" id="keydown" />
+  <input type="text" id="keyup" />
+
+  <input type="text" id="keypress" />
+  <input type="text" id="input_source" />
+  <input type="text" id="input" />
+
+  <input type="button" id="button" onClick=""/>
+  <input type="checkbox" id="checkbox" />
 </body>

packages/driver/cypress/tsconfig.json

@@ -9,7 +9,8 @@
     // We are setting sourceMap=true in order to have full codeFrame support within the driver package.
     // We need to do this because we are using the standalone @cypress/webpack-preprocessor, which doesn't
     // default the sourceMap option for us
-    "sourceMap": true
+    "sourceMap": true,
+    "moduleResolution": "node"
   },
   "include": ["**/*.ts"]
 }

packages/driver/src/cy/commands/actions/press.ts

@@ -1,17 +1,16 @@
 import type { $Cy } from '../../../cypress/cy'
 import type { StateFunc } from '../../../cypress/state'
-import type { KeyPressSupportedKeys, AutomationCommands } from '@packages/types'
+import { isSupportedKey, SupportedKey, AutomationCommands } from '@packages/types'
 import { defaults } from 'lodash'
-import { isSupportedKey } from '@packages/server/lib/automation/commands/key_press'
 import $errUtils from '../../../cypress/error_utils'
 import $utils from '../../../cypress/utils'
 
 export interface PressCommand {
-  (key: KeyPressSupportedKeys, userOptions?: Partial<Cypress.Loggable> & Partial<Cypress.Timeoutable>): void
+  (key: SupportedKey | string, userOptions?: Partial<Cypress.Loggable> & Partial<Cypress.Timeoutable>): void
 }
 
 export default function (Commands: Cypress.Commands, Cypress: Cypress.Cypress, cy: $Cy, state: StateFunc, config: any) {
-  async function pressCommand (key: KeyPressSupportedKeys, userOptions?: Partial<Cypress.Loggable> & Partial<Cypress.Timeoutable>) {
+  async function pressCommand (key: SupportedKey | string | number, userOptions?: Partial<Cypress.Loggable> & Partial<Cypress.Timeoutable>) {
     const options: Cypress.Loggable & Partial<Cypress.Timeoutable> = defaults({}, userOptions, {
       log: true,
     })
@@ -50,17 +49,6 @@ export default function (Commands: Cypress.Commands, Cypress: Cypress.Cypress, c
       return null
     }
 
-    if (Cypress.browser.name === 'firefox' && Number(Cypress.browser.majorVersion) < 135) {
-      $errUtils.throwErrByPath('press.unsupported_browser_version', {
-        onFail: log,
-        args: {
-          browser: Cypress.browser.name,
-          version: Cypress.browser.majorVersion,
-          minimumVersion: 135,
-        },
-      })
-    }
-
     try {
       const command: 'key:press' = 'key:press'
       const args: AutomationCommands[typeof command]['dataType'] = {

packages/driver/src/cy/keyboard.ts

@@ -14,7 +14,6 @@ import $utils from '../cypress/utils'
 import $window from '../dom/window'
 import type { Log } from '../cypress/log'
 import type { StateFunc } from '../cypress/state'
-import type { KeyPressSupportedKeys } from '@packages/types'
 
 const debug = Debug('cypress:driver:keyboard')
 
@@ -1398,8 +1397,21 @@ const defaults = (props: Partial<Cypress.KeyboardDefaultsOptions>) => {
   return getConfig()
 }
 
-const Keys: Record<string, KeyPressSupportedKeys> = {
+const Keys: Record<string, Cypress.SupportedNamedKey> = {
+  DOWN: 'ArrowDown',
+  LEFT: 'ArrowLeft',
+  RIGHT: 'ArrowRight',
+  UP: 'ArrowUp',
+  END: 'End',
+  HOME: 'Home',
+  PAGEDOWN: 'PageDown',
+  PAGEUP: 'PageUp',
+  ENTER: 'Enter',
   TAB: 'Tab',
+  BACKSPACE: 'Backspace',
+  SPACE: 'Space',
+  DELETE: 'Delete',
+  INSERT: 'Insert',
 }
 
 export default {

packages/driver/src/cypress/error_messages.ts

@@ -1311,15 +1311,24 @@ export default {
   },
 
   press: {
-    invalid_key: stripIndent`\
-      \`{{key}}\` is not supported by ${cmd('press')}. See \`Cypress.Keyboard.Keys\` for keys that are supported.
-    `,
-    unsupported_browser_version: stripIndent`\
-      ${cmd('press')} is not supported in {{browser}} version {{version}}. Upgrade to version {{minimumVersion}} to use \`cy.press()\`.
-    `,
-    unsupported_browser: stripIndent`\
+    invalid_key: {
+      message: stripIndent`\
+        \`{{key}}\` is not supported by ${cmd('press')}.
+      `,
+      docsUrl: 'https://on.cypress.io/press',
+    },
+    unsupported_browser_version: {
+      message: stripIndent`\
+        ${cmd('press')} is not supported in {{browser}} version {{version}}. Upgrade to version {{minimumVersion}} to use \`cy.press()\`.
+      `,
+      docsUrl: 'https://on.cypress.io/press',
+    },
+    unsupported_browser: {
+      message: stripIndent`\
       ${cmd('press')} is not supported in {{family}} browsers.
-    `,
+      `,
+      docsUrl: 'https://on.cypress.io/press',
+    },
   },
 
   proxy: {