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

jennifer-shehane · 2025-04-11T20:25:06Z

Close Additional key support for cy.press #31051
Close Space key support for cy.press #31488

Additional details

Include additional key support to cy.press. See https://github.com/cypress-io/cypress-documentation/blob/release/15.1.0/docs/api/commands/press.mdx for full list of keys

Steps to test

How has the user experience changed?

PR Tasks

Have tests been added/updated?
Has a PR for user-facing changes been opened in cypress-documentation? docs: updates cy.press() documentation to include expanded named keys, as well as utf-8 characters cypress-documentation#6256
Have API changes been updated in the type definitions?

…rd keys

Copilot

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/server/lib/automation/commands/key_press.ts:134

The code mapping for 'ArrowUp' uses 'U+0010', which is also used for 'Shift' in this mapping. Please verify against the CDP specification and assign a unique key code for 'ArrowUp'.

'ArrowUp': 'U+0010',

packages/server/lib/automation/commands/key_press.ts

cli/types/cypress.d.ts

cypress · 2025-04-11T20:55:24Z

cypress Run #65076

Run Properties: Passed #65076 • fd8fd803b5: more updates

Project	`cypress`
Branch Review	`feat-all-keys`
Run status	`Passed #65076`
Run duration	`12m 55s`
Commit	`fd8fd803b5: more updates`
Committer	`Cacie Prins`
View all properties for this run ↗︎

Test results
Failures	`0`
Flaky	`0`
Pending	`694`
Skipped	`0`
Passing	`130`
View all changes introduced in this branch ↗︎

brian-mann · 2025-05-21T18:13:02Z

it seems like we aren't normalizing cy.press() to the same options/behavior/mechanics as cy.type() ... namely I can see in the code that we're always issuing the keydown + up events, instead of giving you the ability to "press and hold" a particular key down before releasing it later. Maybe that was intentional when we first supported only TAB but upon supporting other keys, you can see the need arise.

cacieprins · 2025-08-06T15:03:29Z

it seems like we aren't normalizing cy.press() to the same options/behavior/mechanics as cy.type() ... namely I can see in the code that we're always issuing the keydown + up events, instead of giving you the ability to "press and hold" a particular key down before releasing it later. Maybe that was intentional when we first supported only TAB but upon supporting other keys, you can see the need arise.

We have this functionality mapped out! #31052

adamalston · 2025-08-06T15:14:01Z

packages/server/lib/automation/commands/key_press.ts

 export function isSupportedKey (key: string): key is KeyPressSupportedKeys {
-  return CDP_KEYCODE[key] && BIDI_VALUE[key]
-}
-
-export const CDP_KEYCODE: KeyCodeLookup = {
-  'Tab': 'U+000009',
+  return KEY_HEX_TABLE[key as KeyPressSupportedKeys] !== undefined


Is there a reason not to narrow the parameter type to KeyPressSupportedKeys? That change would remove the need for the type assertion inside the function.

export function isSupportedKey (key: KeyPressSupportedKeys): key is KeyPressSupportedKeys { return typeof KEY_HEX_TABLE[key] !== 'undefined' }

I've since changed how this works, but-- this is a type guard function, which casts the parameter of type T to the predicate type U.

function isCat (creature: Animal): creature is Cat { return creature.family === 'Felidae` }

For the function isCat to be useful, its argument (Animal) must be a supertype of the guarded type (Cat). Otherwise you already know it's a Cat, so why invoke the function? :)

adamalston · 2025-08-06T15:25:05Z

packages/server/test/unit/automation/commands/key_press.spec.ts

+        for (const [key, code] of Object.entries(CDP_KEYCODE)) {
+          it(`dispatches a keydown followed by a keyup event to the provided send fn with the ${key} keycode`, async () => {
+            await cdpKeyPress({ key: key as KeyPressSupportedKeys }, sendFn, executionContexts, frameTree)


You might benefit from adding utils that return typed keys, values, and entries for objects. With these utils, you shouldn't need to use type assertions when working with Object.keys, Object.values, or Object.entries.

I've added these utils in other projects, and they've improved the TypeScript experience while also helping catch potential issues.

type ObjectKey<T> = keyof T; type ObjectKeys<T> = ObjectKey<T>[]; type ObjectValue<T> = T[ObjectKey<T>]; type ObjectValues<T> = ObjectValue<T>[]; type ObjectEntries<T> = [ObjectKey<T>, ObjectValue<T>][]; export const getTypedObjectKeys = <T extends object>(obj: T): ObjectKeys<T> => { return Object.keys(obj) as ObjectKeys<T>; }; export const getTypedObjectValues = <T extends object>(obj: T): ObjectValues<T> => { return Object.values(obj) as ObjectValues<T>; }; export const getTypedObjectEntries = <T extends object>(obj: T): ObjectEntries<T> => { return Object.entries(obj) as ObjectEntries<T>; };

adamalston · 2025-08-06T15:25:37Z

packages/types/src/index.ts

@@ -4,6 +4,8 @@ export * from './constants'

 export * from './preferences'

+export { KeyPressSupportedKeys } from './automation'


Suggested change

export { KeyPressSupportedKeys } from './automation'

export type { KeyPressSupportedKeys } from './automation'

This has since been updated to export * from './automation', obviating the need to declare it as a type export.

adamalston · 2025-08-06T15:27:50Z

packages/server/test/unit/automation/commands/key_press.spec.ts

+      for (const [key, value] of Object.entries(BIDI_VALUE)) {
+        // special formatting for value; otherwise test output will show the rendered unicode character
+        it(`dispatches a keydown and keyup action with the value '\\u${(value as string).charCodeAt(0).toString(16).toUpperCase()}' for key '${key}'`, async () => {
+          await bidiKeyPress({ key: key as KeyPressSupportedKeys }, client as WebdriverClient, autContext, 'idSuffix')


Why is the WebdriverClient type assertion necessary? client appears to satisfy the type constraint of the second parameter in the bidiKeyPress function without it.

It was at a previous point to this, but is no longer. Thanks, it's been removed!

cacieprins · 2025-08-06T17:28:07Z

Converting to draft for now - there are major cross-browser issues with using the unicode codepoints as they are; this implementation (not the public signature) needs to be rethought.

…, support any single character even if multiple codepoints

…assert in that special case

adamalston · 2025-08-26T09:09:52Z

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

    cy.visit('/fixtures/input_events.html')
+  })
+
+  const testKeyDownUp = (key) => {


Should key be typed?

It really doesn't matter here.

adamalston · 2025-08-26T09:10:24Z

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

 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


Is the | string redundant given SupportedKey includes it?

No, because SupportedKey always resolves to never unless the value is cast with toSupportedKey.

adamalston · 2025-08-26T09:10:51Z

packages/types/src/automation.ts

+
+/**
+ * Union type representing all keys supported by cy.press().
+ * Includes single-character strings (inluding unicode characters with multiple code points)


Suggested change

* Includes single-character strings (inluding unicode characters with multiple code points)

* Includes single-character strings (including unicode characters with multiple code points)

adamalston · 2025-08-26T09:12:00Z

packages/types/src/automation.ts

+ * Must be cast to via `toSupportedKey` or guarded with `isSupportedKey`
+ * to ensure it is a valid key.
+ */
+export type SupportedKey = SupportedKeyType & string


Is there a reason the type of SupportedKey here doesn't match the type in cypress-automation.d.ts?

cypress/cli/types/cypress-automation.d.ts

Line 28 in f63b212

type SupportedKey = SupportedNamedKey | string

It's so users won't have to .toSupportedKey() whatever value they pass in.

adamalston · 2025-08-26T09:13:41Z

packages/server/test/unit/automation/commands/key_press.spec.ts

@@ -149,38 +151,94 @@ describe('key:press automation command', () => {
      })

      it('dispaches a keydown followed by a keyup event to the provided send fn with the tab keycode', async () => {


Suggested change

it('dispaches a keydown followed by a keyup event to the provided send fn with the tab keycode', async () => {

it('dispatches a keydown followed by a keyup event to the provided send fn with the tab keycode', async () => {

adamalston · 2025-08-26T09:16:24Z

packages/server/test/unit/automation/commands/key_press.spec.ts

+      })
+
+      it('dispatches one keydown followed by a keyup event for each codepoint', async () => {
+        await bidiKeyPress(key, client, autContext, 'idSuffix')


I’ve noticed that the fourth parameter in all bidiKeyPress calls in this file is the same. Should there be some variation?

i'd prefer the duplication for readability but maybe just me

adamalston · 2025-08-26T09:17:05Z

packages/server/lib/automation/commands/key_press.ts

+        .map((value): InputKeySourceAction[] => {
+          return [
+            { type: 'keyDown', value },
+            { type: 'keyUp', value },
+          ]
+        })
+        .reduce((arr, el) => [...arr, ...el], []),


Can the map and reduce be combined to improve performance?

The longest the value can be, for the sake of single-pair combination utf-8 characters, is 2. Legibility is more important than performance when n<=2.

adamalston · 2025-08-26T09:19:36Z

packages/server/lib/automation/commands/key_press.ts

  const activeWindow = await getActiveWindow(client)
  const { contexts: [{ context: topLevelContext }] } = await client.browsingContextGetTree({})

+  const key: string = BidiOverrideCodepoints[inKey] ?? inKey


I was going to suggest removing the string type, since it should be inferred. However, I noticed that the type of inKey is being resolved as never. Could that be an issue?

I also see that variables typed as SupportedKey in packages/server/lib/automation/commands/key_press.ts are being resolved to never as well. I’m wondering if any type errors would appear if these variables were not resolving to never.

SupportedKey is a bit of a weird type here. It needs to include:

Named Keys

Single-codepoint utf-8 characters

Multi-codepoint utf-8 characters

but exclude:

Multiple characters

Given TS does not have a "character" type, this is a bit of a hack to ensure that the value of the string is programmatically ensured to be either a named key or a single character (allowing for multiple utf-8 codepoints).

Unless toSupportedKey is called (to ensure the check), SupportedKey will always resolve to never.

adamalston · 2025-08-26T09:30:12Z

packages/server/lib/automation/commands/key_press.ts

+    // multi-codepoint characters must be dispatched as individual codepoints
+    const isNamedKey = NamedKeys.includes(key)
+
+    const chars = [...key].length === 1 || isNamedKey ? [key] : [...key]


Can this code be simplified to improve performance?

Suggested change

const chars = [...key].length === 1 || isNamedKey ? [key] : [...key]

const chars = isNamedKey ? [key] : [...key];

I doubt there would be any measurable performance here. The suggestion also doesn't have the same effect

adamalston · 2025-08-26T09:36:04Z

packages/server/lib/automation/commands/key_press.ts

-          { type: 'keyDown', value },
-          { type: 'keyUp', value },
-        ],
+        id: `${autContext}-${inKey}-${idSuffix || Date.now()}`,


The logical OR encourages the use of '' as a suffix. Also, will Date.now() collide if multiple calls are made in the same millisecond?

Suggested change

id: `${autContext}-${inKey}-${idSuffix || Date.now()}`,

id: `${autContext}-${inKey}-${idSuffix ?? crypto.randomUUID()}`,

Logical OR results in there always being a suffix, even if '' is passed in - an empty string is falsey. A nullish coalescing operator will result in context-key-, which is not quite what we want here.

TBH, the BiDi spec is very vague on what this id needs to be, and given the nature of how Cypress' server works, it's very unlikely to collide. I'm okay with switching it over to a random uuid. However, Date.now() is what was there previously, so that kind of refactor (including test updates) should probably be covered in a separate PR.

AtofStryker · 2025-08-26T16:38:13Z

cli/CHANGELOG.md

@@ -3,6 +3,10 @@

 _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).


likely need to bump the version to 15.1.0 in the changelog. I can do that in the release PR if needed

AtofStryker · 2025-08-26T16:38:55Z

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

-      return
-    }
+  // Non-BiDi firefox is not supported
+  if (Cypress.browser.family === 'firefox' && Cypress.browserMajorVersion() < 135) {


I think now that we are on 15 Cypress fails before this because we support bidi only? Likely don't need this check

AtofStryker · 2025-08-26T16:46:21Z

packages/server/lib/automation/commands/key_press.ts

+    // multi-codepoint characters must be dispatched as individual codepoints
+    const isNamedKey = NamedKeys.includes(key)
+
+    const chars = [...key].length === 1 || isNamedKey ? [key] : [...key]


I doubt there would be any measurable performance here. The suggestion also doesn't have the same effect

AtofStryker · 2025-08-26T16:50:47Z

packages/server/test/unit/automation/commands/key_press.spec.ts

+      })
+
+      it('dispatches one keydown followed by a keyup event for each codepoint', async () => {
+        await bidiKeyPress(key, client, autContext, 'idSuffix')


i'd prefer the duplication for readability but maybe just me

jennifer-shehane

@cacieprins It would be nice to have a docs link here to on.cypress.io/press

jennifer-shehane

@cacieprins Is this how a press of the SPACE key is meant to be handled?

cy.press(' ')

jennifer-shehane

This actually works, the output is a bit weird though since it prints nothing. Not saying this has to be addressed, just commenting.

      // Test tab character
      cy.press('\t')
      cy.get('#lastKey').should('contain', 'Tab')

jennifer-shehane

@cacieprins Oh, this seems like it should be handled better

cy.press(123)

This also happens on the below, which I think SHOULD work.

      cy.press(0)

cypress-bot · 2025-09-02T21:15:24Z

Released in 15.1.0.

This comment thread has been locked. If you are still experiencing this issue after upgrading to
Cypress v15.1.0, please open a new issue.

feat: extend Cypress.Keyboard.Keys and cy.press to support all keyboa…

efabb5a

…rd keys

jennifer-shehane requested a review from Copilot April 11, 2025 20:25

Copilot AI reviewed Apr 11, 2025

View reviewed changes

packages/server/lib/automation/commands/key_press.ts Outdated Show resolved Hide resolved

jennifer-shehane commented Apr 11, 2025

View reviewed changes

cli/types/cypress.d.ts Outdated Show resolved Hide resolved

Update cli/types/cypress.d.ts

88b8f76

jennifer-shehane marked this pull request as draft April 15, 2025 02:52

jennifer-shehane self-assigned this Apr 22, 2025

reference urls for codepoints

c4af6b6

cacieprins and others added 2 commits August 6, 2025 09:54

type defs for expanded keys; tests

70ecad0

Merge branch 'develop' into feat-all-keys

4a84ff3

cacieprins self-assigned this Aug 6, 2025

cacieprins added 4 commits August 6, 2025 10:31

changelog

2485043

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

935d766

Add pr link to changelog

6df79a8

reduce repetition with key codes; remove unsupported capslock keycode

bb031ba

cacieprins marked this pull request as ready for review August 6, 2025 15:02

cacieprins changed the title ~~feat: extend Cypress.Keyboard.Keys and cy.press to support all keyboard keys~~ feat: extend Cypress.Keyboard.Keys and cy.press to support (almost) all keyboard keys Aug 6, 2025

This comment was marked as outdated.

Sign in to view

adamalston reviewed Aug 6, 2025

View reviewed changes

cacieprins marked this pull request as draft August 6, 2025 17:27

cacieprins and others added 6 commits August 6, 2025 17:04

only "key" special function keys in Cypress.Keyboard.Keys - otherwise…

e9abde8

…, support any single character even if multiple codepoints

do not refocus on f6 - f6 behavior keyup is indeterminate, so do not …

bde74b4

…assert in that special case

Merge branch 'develop' into feat-all-keys

eddde62

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

6109992

various cleanup - wip - need multi-codepoint fix

385ecc9

support multi-codepoint characters

54f4f26

consistent debug

707adf0

This comment was marked as outdated.

Sign in to view

cacieprins and others added 2 commits August 25, 2025 13:32

rm debug logging from input fixture

869912a

Merge branch 'develop' into feat-all-keys

f63b212

cacieprins requested a review from AtofStryker August 25, 2025 17:35

adamalston reviewed Aug 26, 2025

View reviewed changes

AtofStryker approved these changes Aug 26, 2025

View reviewed changes

jennifer-shehane commented Aug 26, 2025

View reviewed changes

some typos, changelog version

cb9d042

jennifer-shehane commented Aug 26, 2025

View reviewed changes

cacieprins added 2 commits August 26, 2025 13:31

fix toSupportedKey guard fn to properly reject non-strings

d43600b

add Space as named key, remove warnings re legacy firefox

d9085ff

This comment was marked as outdated.

Sign in to view

cacieprins added 3 commits August 26, 2025 15:34

fix space

47ed81f

support single-digit number keys

311dc66

remove support for F-keys

03a840e

This comment was marked as outdated.

Sign in to view

cacieprins added 2 commits August 27, 2025 12:33

add test cmd to types pkg

3878191

rm failing vitest project config

58d7804

This comment was marked as outdated.

Sign in to view

fix changelog

e413eda

This comment was marked as outdated.

Sign in to view

cacieprins added 2 commits August 27, 2025 13:41

clean up types a bit for single digit numbers

764a438

more updates

fd8fd80

cacieprins merged commit 90310ae into develop Aug 28, 2025
89 of 91 checks passed

cacieprins deleted the feat-all-keys branch August 28, 2025 14:31

cypress-bot bot locked as resolved and limited conversation to collaborators Sep 2, 2025

		@@ -4,6 +4,8 @@ export * from './constants'

		export * from './preferences'

		export { KeyPressSupportedKeys } from './automation'

	export { KeyPressSupportedKeys } from './automation'
	export type { KeyPressSupportedKeys } from './automation'

	* Includes single-character strings (inluding unicode characters with multiple code points)
	* Includes single-character strings (including unicode characters with multiple code points)

		@@ -149,38 +151,94 @@ describe('key:press automation command', () => {
		})

		it('dispaches a keydown followed by a keyup event to the provided send fn with the tab keycode', async () => {

	it('dispaches a keydown followed by a keyup event to the provided send fn with the tab keycode', async () => {
	it('dispatches a keydown followed by a keyup event to the provided send fn with the tab keycode', async () => {

	const chars = [...key].length === 1 \|\| isNamedKey ? [key] : [...key]
	const chars = isNamedKey ? [key] : [...key];

	id: `${autContext}-${inKey}-${idSuffix \|\| Date.now()}`,
	id: `${autContext}-${inKey}-${idSuffix ?? crypto.randomUUID()}`,

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 (almost) all keyboard keys #31496

Uh oh!

Conversation

jennifer-shehane commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Additional details

Steps to test

How has the user experience changed?

PR Tasks

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cypress bot commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brian-mann commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cacieprins commented Aug 6, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cacieprins commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

adamalston Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AtofStryker Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

jennifer-shehane commented Apr 11, 2025 •

edited

Loading

cypress bot commented Apr 11, 2025 •

edited

Loading

brian-mann commented May 21, 2025 •

edited

Loading

cacieprins commented Aug 6, 2025 •

edited

Loading

adamalston Aug 26, 2025 •

edited

Loading

AtofStryker Aug 26, 2025 •

edited

Loading

AtofStryker Aug 26, 2025 •

edited

Loading

jennifer-shehane left a comment •

edited

Loading