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

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). Addressed in [#31496](https://github.com/cypress-io/cypress/pull/31496).
+
 **Bugfixes:**
 
 - Fixed an issue where the open Studio button would incorrectly show for component tests. Addressed in [#32315](https://github.com/cypress-io/cypress/pull/32315).

cli/types/cypress-automation.d.ts

@@ -0,0 +1,29 @@
+declare namespace Cypress {
+  type SupportedNamedKey = 'ArrowDown' |
+  'ArrowLeft' |
+  'ArrowRight' |
+  'ArrowUp' |
+  'End' |
+  'Home' |
+  'PageDown' |
+  'PageUp' |
+  'Enter' |
+  'Tab' |
+  'Backspace' |
+  'Delete' |
+  'Insert' |
+  'F1' |
+  'F2' |
+  'F3' |
+  'F4' |
+  'F5' |
+  'F6' |
+  'F7' |
+  'F8' |
+  'F9' |
+  'F10' |
+  'F11' |
+  'F12'
+
+  type SupportedKey = SupportedNamedKey | string
+}

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,31 @@ 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',
+        DELETE: 'Delete',
+        INSERT: 'Insert',
+        F1: 'F1',
+        F2: 'F2',
+        F3: 'F3',
+        F4: 'F4',
+        F5: 'F5',
+        F6: 'F6',
+        F7: 'F7',
+        F8: 'F8',
+        F9: 'F9',
+        F10: 'F10',
+        F11: 'F11',
+        F12: 'F12',
       },
     }
 
@@ -1765,7 +1789,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.

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

@@ -1,21 +1,53 @@
 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
-    }
+  // 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')
+  })
+
+  const testKeyDownUp = (key) => {
+    it(`dispatches ${key} keypress to the AUT`, () => {
+      cy.press(key)
+      cy.get('#keydown').should('have.value', key)
+
+      // in some browsers, F6 will cause the frame to lose focus, so the keyup will not be triggered
+      if (key !== 'F6') {
+        cy.get('#keyup').should('have.value', key)
+      }
+
+      // named keys are not dispatched as keypress events
+      if (!Object.values(Cypress.Keyboard.Keys).includes(key)) {
+        cy.get('#keypress').should('have.value', key)
+      }
+    })
+  }
+
+  // // Numbers
+  ;['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'].forEach(testKeyDownUp)
+
+  // // Letters
+  ;['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm',
+    'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'].forEach(testKeyDownUp)
 
-    cy.press(Cypress.Keyboard.Keys.TAB)
+  // // Special characters
+  ;['!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '-', '_', '=',
+    '+', '[', ']', '{', '}', '\\', '|', ';', ':', '\'', '"', ',', '.',
+    '<', '>', '/', '?', '`', '~', ' ', '€', 'é'].forEach(testKeyDownUp)
 
-    cy.get('#keydown').should('have.value', 'Tab')
+  Object.values(Cypress.Keyboard.Keys).forEach(testKeyDownUp)
 
-    cy.get('#keyup').should('have.value', 'Tab')
+  it('dispatches the input event when an input is modified via cy.press', () => {
+    cy.get('#input_source').focus()
+    cy.press('a')
+    cy.get('#input_source').should('have.value', 'a')
+    cy.get('#input').should('have.value', 'a')
   })
 })

packages/driver/cypress/fixtures/input_events.html

@@ -3,15 +3,19 @@
 <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
+        document.getElementById(ev).value += data.key ?? data.data
       })
     })
   </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" />
 </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, userOptions?: Partial<Cypress.Loggable> & Partial<Cypress.Timeoutable>) {
     const options: Cypress.Loggable & Partial<Cypress.Timeoutable> = defaults({}, userOptions, {
       log: true,
     })

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,32 @@ 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',
+  DELETE: 'Delete',
+  INSERT: 'Insert',
+  F1: 'F1',
+  F2: 'F2',
+  F3: 'F3',
+  F4: 'F4',
+  F5: 'F5',
+  F6: 'F6',
+  F7: 'F7',
+  F8: 'F8',
+  F9: 'F9',
+  F10: 'F10',
+  F11: 'F11',
+  F12: 'F12',
 }
 
 export default {

packages/driver/test/unit/cy/commands/actions/press.spec.ts

@@ -2,7 +2,7 @@
  * @vitest-environment jsdom
  */
 import { vi, describe, it, expect, beforeEach, Mock, MockedObject } from 'vitest'
-import type { KeyPressSupportedKeys } from '@packages/types'
+
 import addCommand, { PressCommand } from '../../../../../src/cy/commands/actions/press'
 import type { $Cy } from '../../../../../src/cypress/cy'
 import type { StateFunc } from '../../../../../src/cypress/state'
@@ -25,7 +25,6 @@ vi.mock('../../../../../src/cypress/error_utils', async () => {
 })
 
 describe('cy/commands/actions/press', () => {
-  let log: Mock<typeof Cypress['log']>
   let automation: Mock<typeof Cypress['automation']>
   let press: PressCommand
   let Cypress: MockedObject<Cypress.Cypress>
@@ -36,13 +35,11 @@ describe('cy/commands/actions/press', () => {
   let logReturnValue: Cypress.Log
 
   beforeEach(() => {
-    log = vi.fn<typeof Cypress['log']>()
     automation = vi.fn<typeof Cypress['automation']>()
 
     Cypress = {
-      // The overloads for `log` don't get applied correctly here
-      // @ts-expect-error
-      log,
+      // @ts-expect-error - <Cypress['log']> has a type conflict between Driver and CLI d.ts
+      log: vi.fn(),
       automation,
       // @ts-expect-error
       browser: {
@@ -95,14 +92,15 @@ describe('cy/commands/actions/press', () => {
   })
 
   describe('with a valid key', () => {
-    const key: KeyPressSupportedKeys = Keyboard.Keys.TAB
-
-    it('dispatches a key:press automation command', async () => {
-      await press(key)
-      expect(automation).toHaveBeenCalledWith('key:press', { key })
-    })
+    for (const key of Object.values(Keyboard.Keys)) {
+      it(`dispatches a key:press automation command for key: ${key}`, async () => {
+        await press(key)
+        expect(automation).toHaveBeenCalledWith('key:press', { key })
+      })
+    }
 
     describe('with options', () => {
+      const key = 'Tab'
       let options: Cypress.Loggable & Cypress.Timeoutable
 
       beforeEach(() => {