feat: cy.press()

.circleci/cache-version.txt

@@ -1,3 +1,3 @@
 # Bump this version to force CI to re-create the cache from scratch.
 
-3-18-2024:4:25
+4-3-2025

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,
 }