feat: cy.press() (#31398)

* wip - cy.press() command

* cy command for dispatching key press/down/up events

* unit tests and failure cases for cy.press()

* Cypress.Keyboard.Keys definition; fix command log message

* add keys to the internal keyboard type

* auto-focus in cdp

* ensure aut iframe is focused before dispatching key events in bidi browsers

* update tests for cdp focus

* fixed tests for bidi

* lint

* fix type ref in .d.ts

* linting

* skip press() driver test in ff below v135

* try all contexts for frame before failing due to missing/invalid context id

* ensure error is error before accessing props

* skip press driver test in webkit

* changelog

* debug automation middleware invocation for firefox flake

* debug

* cache update

* use bidi automation middleware from connectToNewSpec rather than constructor

* more comprehensive logging

* debug socket base, additional debug in automation

* install firefox automation middleware on setup as well as connectToNewSpec

* unit tests for firefox-utils

* proper calledWith

---------

Co-authored-by: Jennifer Shehane <[email protected]>

Author: cacieprins

cli/CHANGELOG.md

@@ -1,8 +1,12 @@
 <!-- See the ../guides/writing-the-cypress-changelog.md for details on writing the changelog. -->
-## 14.2.2
+## 14.3.0
 
 _Released 4/8/2025 (PENDING)_
 
+**Features:**
+
+- The [`cy.press()`](https://on.cypress.io/api/press) command is now available. It supports dispatching native Tab keyboard events to the browser. Addresses [#31050](https://github.com/cypress-io/cypress/issues/31050). Addresses [#299](https://github.com/cypress-io/cypress/issues/299). Addressed in [#31398](https://github.com/cypress-io/cypress/pull/31398).
+
 **Bugfixes:**
 
 - Allows for `babel-loader` version 10 to be a peer dependency of `@cypress/webpack-preprocessor`. Fixed in [#31218](https://github.com/cypress-io/cypress/pull/31218).

cli/types/cypress.d.ts

@@ -578,99 +578,7 @@ declare namespace Cypress {
      */
     stop(): void
 
-    Commands: {
-      /**
-       * Add a custom command
-       * @see https://on.cypress.io/api/commands
-       */
-      add<T extends keyof Chainable>(name: T, fn: CommandFn<T>): void
-
-      /**
-       * Add a custom parent command
-       * @see https://on.cypress.io/api/commands#Parent-Commands
-       */
-      add<T extends keyof Chainable>(name: T, options: CommandOptions & { prevSubject: false }, fn: CommandFn<T>): void
-
-      /**
-       * Add a custom child command
-       * @see https://on.cypress.io/api/commands#Child-Commands
-       */
-      add<T extends keyof Chainable, S = any>(name: T, options: CommandOptions & { prevSubject: true }, fn: CommandFnWithSubject<T, S>): void
-
-      /**
-       * Add a custom child or dual command
-       * @see https://on.cypress.io/api/commands#Validations
-       */
-      add<T extends keyof Chainable, S extends PrevSubject>(
-        name: T, options: CommandOptions & { prevSubject: S | ['optional'] }, fn: CommandFnWithSubject<T, PrevSubjectMap[S]>,
-      ): void
-
-      /**
-       * Add a custom command that allows multiple types as the prevSubject
-       * @see https://on.cypress.io/api/commands#Validations#Allow-Multiple-Types
-       */
-      add<T extends keyof Chainable, S extends PrevSubject>(
-        name: T, options: CommandOptions & { prevSubject: S[] }, fn: CommandFnWithSubject<T, PrevSubjectMap<void>[S]>,
-      ): void
-
-      /**
-       * Add one or more custom commands
-       * @see https://on.cypress.io/api/commands
-       */
-      addAll<T extends keyof Chainable>(fns: CommandFns): void
-
-      /**
-       * Add one or more custom parent commands
-       * @see https://on.cypress.io/api/commands#Parent-Commands
-       */
-      addAll<T extends keyof Chainable>(options: CommandOptions & { prevSubject: false }, fns: CommandFns): void
-
-      /**
-       * Add one or more custom child commands
-       * @see https://on.cypress.io/api/commands#Child-Commands
-       */
-      addAll<T extends keyof Chainable, S = any>(options: CommandOptions & { prevSubject: true }, fns: CommandFnsWithSubject<S>): void
-
-      /**
-       * Add one or more custom commands that validate their prevSubject
-       * @see https://on.cypress.io/api/commands#Validations
-       */
-      addAll<T extends keyof Chainable, S extends PrevSubject>(
-        options: CommandOptions & { prevSubject: S | ['optional'] }, fns: CommandFnsWithSubject<PrevSubjectMap[S]>,
-      ): void
-
-      /**
-       * Add one or more custom commands that allow multiple types as their prevSubject
-       * @see https://on.cypress.io/api/commands#Allow-Multiple-Types
-       */
-      addAll<T extends keyof Chainable, S extends PrevSubject>(
-        options: CommandOptions & { prevSubject: S[] }, fns: CommandFnsWithSubject<PrevSubjectMap<void>[S]>,
-      ): void
-
-      /**
-       * Overwrite an existing Cypress command with a new implementation
-       * @see https://on.cypress.io/api/commands#Overwrite-Existing-Commands
-       */
-      overwrite<T extends keyof Chainable>(name: T, fn: CommandFnWithOriginalFn<T>): void
-
-      /**
-       * Overwrite an existing Cypress command with a new implementation
-       * @see https://on.cypress.io/api/commands#Overwrite-Existing-Commands
-       */
-      overwrite<T extends keyof Chainable, S extends PrevSubject>(name: T, fn: CommandFnWithOriginalFnAndSubject<T, PrevSubjectMap[S]>): void
-
-      /**
-       * Add a custom query
-       * @see https://on.cypress.io/api/custom-queries
-       */
-      addQuery<T extends keyof Chainable>(name: T, fn: QueryFn<T>): void
-
-      /**
-       * Overwrite an existing Cypress query with a new implementation
-       * @see https://on.cypress.io/api/custom-queries
-       */
-      overwriteQuery<T extends keyof Chainable>(name: T, fn: QueryFnWithOriginalFn<T>): void
-    }
+    Commands: Commands
 
     /**
      * @see https://on.cypress.io/cookies
@@ -775,6 +683,9 @@ declare namespace Cypress {
      */
     Keyboard: {
       defaults(options: Partial<KeyboardDefaultsOptions>): void
+      Keys: {
+        TAB: 'Tab',
+      },
     }
 
     /**
@@ -829,6 +740,100 @@ declare namespace Cypress {
     onSpecWindow: (window: Window, specList: string[] | Array<() => Promise<void>>) => void
   }
 
+  interface Commands {
+      /**
+       * Add a custom command
+       * @see https://on.cypress.io/api/commands
+       */
+      add<T extends keyof Chainable>(name: T, fn: CommandFn<T>): void
+
+      /**
+       * Add a custom parent command
+       * @see https://on.cypress.io/api/commands#Parent-Commands
+       */
+      add<T extends keyof Chainable>(name: T, options: CommandOptions & { prevSubject: false }, fn: CommandFn<T>): void
+
+      /**
+       * Add a custom child command
+       * @see https://on.cypress.io/api/commands#Child-Commands
+       */
+      add<T extends keyof Chainable, S = any>(name: T, options: CommandOptions & { prevSubject: true }, fn: CommandFnWithSubject<T, S>): void
+
+      /**
+       * Add a custom child or dual command
+       * @see https://on.cypress.io/api/commands#Validations
+       */
+      add<T extends keyof Chainable, S extends PrevSubject>(
+        name: T, options: CommandOptions & { prevSubject: S | ['optional'] }, fn: CommandFnWithSubject<T, PrevSubjectMap[S]>,
+      ): void
+
+      /**
+       * Add a custom command that allows multiple types as the prevSubject
+       * @see https://on.cypress.io/api/commands#Validations#Allow-Multiple-Types
+       */
+      add<T extends keyof Chainable, S extends PrevSubject>(
+        name: T, options: CommandOptions & { prevSubject: S[] }, fn: CommandFnWithSubject<T, PrevSubjectMap<void>[S]>,
+      ): void
+
+      /**
+       * Add one or more custom commands
+       * @see https://on.cypress.io/api/commands
+       */
+      addAll<T extends keyof Chainable>(fns: CommandFns): void
+
+      /**
+       * Add one or more custom parent commands
+       * @see https://on.cypress.io/api/commands#Parent-Commands
+       */
+      addAll<T extends keyof Chainable>(options: CommandOptions & { prevSubject: false }, fns: CommandFns): void
+
+      /**
+       * Add one or more custom child commands
+       * @see https://on.cypress.io/api/commands#Child-Commands
+       */
+      addAll<T extends keyof Chainable, S = any>(options: CommandOptions & { prevSubject: true }, fns: CommandFnsWithSubject<S>): void
+
+      /**
+       * Add one or more custom commands that validate their prevSubject
+       * @see https://on.cypress.io/api/commands#Validations
+       */
+      addAll<T extends keyof Chainable, S extends PrevSubject>(
+        options: CommandOptions & { prevSubject: S | ['optional'] }, fns: CommandFnsWithSubject<PrevSubjectMap[S]>,
+      ): void
+
+      /**
+       * Add one or more custom commands that allow multiple types as their prevSubject
+       * @see https://on.cypress.io/api/commands#Allow-Multiple-Types
+       */
+      addAll<T extends keyof Chainable, S extends PrevSubject>(
+        options: CommandOptions & { prevSubject: S[] }, fns: CommandFnsWithSubject<PrevSubjectMap<void>[S]>,
+      ): void
+
+      /**
+       * Overwrite an existing Cypress command with a new implementation
+       * @see https://on.cypress.io/api/commands#Overwrite-Existing-Commands
+       */
+      overwrite<T extends keyof Chainable>(name: T, fn: CommandFnWithOriginalFn<T>): void
+
+      /**
+       * Overwrite an existing Cypress command with a new implementation
+       * @see https://on.cypress.io/api/commands#Overwrite-Existing-Commands
+       */
+      overwrite<T extends keyof Chainable, S extends PrevSubject>(name: T, fn: CommandFnWithOriginalFnAndSubject<T, PrevSubjectMap[S]>): void
+
+      /**
+       * Add a custom query
+       * @see https://on.cypress.io/api/custom-queries
+       */
+      addQuery<T extends keyof Chainable>(name: T, fn: QueryFn<T>): void
+
+      /**
+       * Overwrite an existing Cypress query with a new implementation
+       * @see https://on.cypress.io/api/custom-queries
+       */
+      overwriteQuery<T extends keyof Chainable>(name: T, fn: QueryFnWithOriginalFn<T>): void
+  }
+
   type CanReturnChainable = void | Chainable | Promise<unknown>
   type ThenReturn<S, R> =
     R extends void ? Chainable<S> :
@@ -1742,6 +1747,16 @@ declare namespace Cypress {
      */
     pause(options?: Partial<Loggable>): Chainable<Subject>
 
+    /**
+     * Send a native sequence of keyboard events: keydown & press, followed by keyup, for the provided key.
+     * Supported keys index the Cypress.Keyboard.Keys record.
+     *
+     * @example
+     *    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>): void
+
     /**
      * Get the immediately preceding sibling of each element in a set of the elements.
      *

cli/types/tslint.json

@@ -24,7 +24,9 @@
     "jsdoc-format": false,
     // for now keep the Cypress NPM module API
     // in its own file for simplicity
-    "no-single-declare-module": false
+    "no-single-declare-module": false,
+    // This is detecting necessary qualifiers as unnecessary
+    "no-unnecessary-qualifier": false
   },
   "linterOptions": {
     "exclude": [

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

@@ -1,23 +1,21 @@
-describe('__placeholder__/commands/actions/press', () => {
+describe('src/cy/commands/actions/press', () => {
   it('dispatches the tab keypress to the AUT', () => {
-    cy.visit('/fixtures/input_events.html')
+    // Non-BiDi firefox is not supported
+    if (Cypress.browser.family === 'firefox' && Cypress.browserMajorVersion() < 135) {
+      return
+    }
 
-    cy.get('#focus').focus().then(async () => {
-      try {
-        await Cypress.automation('key:press', { key: 'Tab' })
-      } catch (e) {
-        if (e.message && (e.message as string).includes('key:press')) {
-          cy.log(e.message)
+    // TODO: Webkit is not supported. https://github.com/cypress-io/cypress/issues/31054
+    if (Cypress.isBrowser('webkit')) {
+      return
+    }
 
-          return
-        }
+    cy.visit('/fixtures/input_events.html')
 
-        throw e
-      }
+    cy.press(Cypress.Keyboard.Keys.TAB)
 
-      cy.get('#keyup').should('have.value', 'Tab')
+    cy.get('#keydown').should('have.value', 'Tab')
 
-      cy.get('#keydown').should('have.value', 'Tab')
-    })
+    cy.get('#keyup').should('have.value', 'Tab')
   })
 })

packages/driver/cypress/e2e/e2e/origin/commands/misc.cy.ts

@@ -223,7 +223,7 @@ it('verifies number of cy commands', () => {
     'invoke', 'its', 'getCookie', 'getCookies', 'setCookie', 'clearCookie', 'clearCookies', 'pause', 'debug', 'exec', 'readFile',
     'writeFile', 'fixture', 'clearLocalStorage', 'url', 'hash', 'location', 'end', 'noop', 'log', 'wrap', 'reload', 'go', 'visit',
     'focused', 'get', 'contains', 'shadow', 'within', 'request', 'session', 'screenshot', 'task', 'find', 'filter', 'not',
-    'children', 'eq', 'closest', 'first', 'last', 'next', 'nextAll', 'nextUntil', 'parent', 'parents', 'parentsUntil', 'prev',
+    'children', 'eq', 'closest', 'first', 'last', 'next', 'nextAll', 'nextUntil', 'parent', 'parents', 'parentsUntil', 'prev', 'press',
     'prevAll', 'prevUntil', 'siblings', 'wait', 'title', 'window', 'document', 'viewport', 'server', 'route', 'intercept', 'origin',
     'mount', 'as', 'root', 'getAllLocalStorage', 'clearAllLocalStorage', 'getAllSessionStorage', 'clearAllSessionStorage',
     'getAllCookies', 'clearAllCookies',

packages/driver/cypress/fixtures/input_events.html

@@ -12,7 +12,6 @@
 </head>
 
 <body>
-  <input type="text" id="focus" />
   <input type="text" id="keyup" />
   <input type="text" id="keydown" />
 </body>

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

@@ -9,6 +9,7 @@ import * as Submit from './submit'
 import * as Type from './type'
 import * as Trigger from './trigger'
 import * as Mount from './mount'
+import Press from './press'
 
 export {
   Check,
@@ -22,4 +23,5 @@ export {
   Type,
   Trigger,
   Mount,
+  Press,
 }

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

@@ -0,0 +1,77 @@
+import type { $Cy } from '../../../cypress/cy'
+import type { StateFunc } from '../../../cypress/state'
+import type { KeyPressSupportedKeys, 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
+}
+
+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>) {
+    const options: Cypress.Loggable & Partial<Cypress.Timeoutable> = defaults({}, userOptions, {
+      log: true,
+    })
+    const deltaOptions = $utils.filterOutOptions(options)
+
+    const log = Cypress.log({
+      timeout: options.timeout,
+      hidden: options.log === false,
+      message: [key, deltaOptions],
+      consoleProps () {
+        return {
+          'Key': key,
+        }
+      },
+    })
+
+    if (!isSupportedKey(key)) {
+      $errUtils.throwErrByPath('press.invalid_key', {
+        onFail: log,
+        args: { key },
+      })
+
+      // throwErrByPath always throws, but there's no way to indicate that
+      // code beyond this point is unreachable to typescript / linters
+      return
+    }
+
+    if (Cypress.browser.family === 'webkit') {
+      $errUtils.throwErrByPath('press.unsupported_browser', {
+        onFail: log,
+        args: {
+          family: Cypress.browser.family,
+        },
+      })
+
+      return
+    }
+
+    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'] = {
+        key,
+      }
+
+      await Cypress.automation('key:press', args)
+    } catch (err) {
+      $errUtils.throwErr(err, { onFail: log })
+    }
+  }
+
+  return Commands.add('press', pressCommand)
+}