From a83ffa72157fe8d7f823347d3e9963e514d28d25 Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Tue, 8 Apr 2025 16:50:01 -0400 Subject: [PATCH 1/4] feat: documentation for the press() command (#6135) * docs for the press() command, including a callout in the accessibility guide * add press to TOC * Move some content around, mention accesiibility * remove 'focus' note * Document Keyboard.Keys * update reference to command * Update example to be a little more real case * Add another example of autocomplete with tab * Add link to keyboard api page * Fix version number for introduction * Fix broken link * alphabetize see also * Update package.json Co-authored-by: Mike McCready <66998419+MikeMcC399@users.noreply.github.com> * Fix broken link * lint --------- Co-authored-by: Jennifer Shehane Co-authored-by: Mike McCready <66998419+MikeMcC399@users.noreply.github.com> --- docs/api/commands/focus.mdx | 1 + docs/api/commands/press.mdx | 134 ++++++++++++++++++++++ docs/api/commands/type.mdx | 1 + docs/api/cypress-api/keyboard-api.mdx | 57 ++++++--- docs/api/table-of-contents.mdx | 1 + docs/app/guides/accessibility-testing.mdx | 7 ++ 6 files changed, 187 insertions(+), 14 deletions(-) create mode 100644 docs/api/commands/press.mdx diff --git a/docs/api/commands/focus.mdx b/docs/api/commands/focus.mdx index 36024d875a..bf1f67c959 100644 --- a/docs/api/commands/focus.mdx +++ b/docs/api/commands/focus.mdx @@ -159,4 +159,5 @@ the following: - [`.blur()`](/api/commands/blur) - [`.click()`](/api/commands/click) - [`cy.focused()`](/api/commands/focused) +- [`cy.press()`](/api/commands/press) - [`.type()`](/api/commands/type) diff --git a/docs/api/commands/press.mdx b/docs/api/commands/press.mdx new file mode 100644 index 0000000000..f0bef379fe --- /dev/null +++ b/docs/api/commands/press.mdx @@ -0,0 +1,134 @@ +--- +title: 'cy.press() | Cypress Documentation' +description: Trigger native key events in your application to simulate keyboard interactions. +sidebar_label: press +slug: /api/commands/press +componentSpecific: false +--- + + + +# press + +Trigger native key events in your application to simulate keyboard interactions. + +A `keydown`, `press`, and `keyup` event will be dispatched directly to the browser window. + +Unlike `cy.type()`, which is best for typing character keys, `cy.press()` will dispatch real keyboard events rather than simulated ones. This command is especially useful when testing focus management and keyboard navigation patterns which are critical for [accessibility testing](/app/guides/accessibility-testing) and great keyboard UX. + +Currently, the only key supported is `Tab`. + +:::caution + +Supported Browsers: +This command is supported in chromium browsers and Firefox versions >= v135. WebKit +is not supported. This command will fail if executed in a browser that does not support +it. + +::: + +## Syntax + +```javascript +cy.press(key) +cy.press(key, options) +``` + +## Signature + +```typescript +interface PressCommand { + ( + key: KeyPressSupportedKeys, + options?: Partial & Partial + ): void +} +``` + +## Usage + + **Correct Usage** + +```javascript +cy.get('input.first').focus() +cy.press(Cypress.Keyboard.Keys.TAB) +cy.get('input.second').should('have.focus') +``` + + **Incorrect Usage** + +```javascript +cy.get('input.first').focus() +cy.press(Cypress.Keyboard.Keys.TAB) + // Errors because press yields null + .should('have.focus') +``` + +### Arguments + + **key _(String)_** + +The key to press. The supported values are available on [`Cypress.Keyboard.Keys`](/api/cypress-api/keyboard-api), and may change from time to time. It's recomended that you reference these values from `Cypress.Keyboard.Keys` rather than passing in a string. + +### Supported Keys + +| Reference | Value | +| --------------------------- | ------- | +| `Cypress.Keyboard.Keys.TAB` | `"Tab"` | + + **options _(Object)_** + +Pass in an options object to change the default behavior of `.press()`. + +| Option | Default | Description | +| --------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `log` | `true` | Displays the command in the [Command log](/app/core-concepts/open-mode#Command-Log) | +| `timeout` | [`defaultCommandTimeout`](/app/references/configuration#Timeouts) | Time to wait for `cy.press()` to resolve before timing out | + + + +- `cy.press()` yields `null`. + +## Examples + +### Test focus order of tab + +```js +it('moves focus to the next form element when pressing Tab', () => { + cy.visit('/my-login') + cy.get('input.email').type('username') + cy.press(Cypress.Keyboard.Keys.TAB) + cy.get('input.password').should('have.focus') +}) +``` + +### Test autocomplete of search input with tab + +```js +it('autocompletes search input when pressing Tab', () => { + cy.get('[data-cy="search"]').type('cy') + cy.press(Cypress.Keyboard.Keys.TAB) + cy.get('[data-cy="search"]').should('have.value', 'cypress') +}) +``` + +## Notes + +### Transient activation + +By dispatching native keyboard events to the browser, this command will cause the browser to enter [Transient activation](https://developer.mozilla.org/en-US/docs/Glossary/Transient_activation) state. + +If your application prevents the default behavior of the `beforeunload` event, this may cause issues when navigating away from the current page. + +## History + +| Version | Changes | +| ----------------------------------- | ---------------------------- | +| [14.3.0](/app/references/changelog) | Added the `.press()` command | + +## See also + +- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api) +- [`.focus()`](/api/commands/focus) +- [`.focused()`](/api/commands/focused) +- [`.type()`](/api/commands/type) diff --git a/docs/api/commands/type.mdx b/docs/api/commands/type.mdx index 075919fa71..97f7030c87 100644 --- a/docs/api/commands/type.mdx +++ b/docs/api/commands/type.mdx @@ -664,5 +664,6 @@ following: - [`.clear()`](/api/commands/clear) - [`.click()`](/api/commands/click) - [`.focus()`](/api/commands/focus) +- [`cy.press()`](/api/commands/press) - [`.submit()`](/api/commands/submit) - [`Cypress.Keyboard`](/api/cypress-api/keyboard-api) diff --git a/docs/api/cypress-api/keyboard-api.mdx b/docs/api/cypress-api/keyboard-api.mdx index 8a8823e0c4..e01f3ab19f 100644 --- a/docs/api/cypress-api/keyboard-api.mdx +++ b/docs/api/cypress-api/keyboard-api.mdx @@ -9,16 +9,29 @@ sidebar_position: 150 # Cypress.Keyboard -The Keyboard API allows you set the default values for how the +The Keyboard API allows you to access available `Keys` for use with [`cy.press()`](/api/commands/press) or to set the default values for how the [.type()](/api/commands/type) command is executed. ## Syntax ```javascript +Cypress.Keyboard.Keys(key) Cypress.Keyboard.defaults(options) ``` -### Arguments +### Keys Arguments + + **key _(String)_** + +The key available for `cy.press()`. + +The following keys are supported: + +| Reference | Value | +| --------------------------- | ------- | +| `Cypress.Keyboard.Keys.TAB` | `"Tab"` | + +### defaults Arguments **options _(Object)_** @@ -30,6 +43,13 @@ An object containing the following: ## Examples +### Press tab key + +```javascript +cy.press(Cypress.Keyboard.Keys.TAB) +cy.get('input.second').should('have.focus') +``` + ### Slow down typing by increasing the keystroke delay ```javascript @@ -59,22 +79,31 @@ The keystroke delay can also be set via which can be useful when setting it for a single test or a subset of tests. ```javascript -it('removes keystroke delay for all typing in this test', { keystrokeDelay: 0 }, () => { - cy.get('input').eq(0).type('fast typing') - cy.get('input').eq(1).type('more fast typing') -}) - -describe('removes keystroke delay in all tests in this suite', { keystrokeDelay: 0 }, () => { - it('types fast in the first input', () => { +it( + 'removes keystroke delay for all typing in this test', + { keystrokeDelay: 0 }, + () => { cy.get('input').eq(0).type('fast typing') - }) - - it('types fast in the second input', () => { cy.get('input').eq(1).type('more fast typing') - }) -})) + } +) + +describe( + 'removes keystroke delay in all tests in this suite', + { keystrokeDelay: 0 }, + () => { + it('types fast in the first input', () => { + cy.get('input').eq(0).type('fast typing') + }) + + it('types fast in the second input', () => { + cy.get('input').eq(1).type('more fast typing') + }) + } +) ``` ## See also +- [`cy.press()`](/api/commands/press) - [`.type()`](/api/commands/type) diff --git a/docs/api/table-of-contents.mdx b/docs/api/table-of-contents.mdx index 693ea90714..01c2a7f43f 100644 --- a/docs/api/table-of-contents.mdx +++ b/docs/api/table-of-contents.mdx @@ -139,6 +139,7 @@ Cypress has a variety of additional commands to help write tests. | [`.mount()`](/api/commands/mount) | Mount a component for Cypress Component Testing. | | [`.origin()`](/api/commands/origin) | Visit multiple domains of different origin in a single test. | | [`.pause()`](/api/commands/pause) | Pause test execution, allowing interaction with the application under test before resuming. | +| [`.press()`](/api/commands/press) | Trigger native key events in your application to simulate real user keyboard interactions. | | [`.readFile()`](/api/commands/readfile) | Read a file from disk. | | [`.reload()`](/api/commands/reload) | Reload the page. | | [`.request()`](/api/commands/request) | Make an HTTP request. | diff --git a/docs/app/guides/accessibility-testing.mdx b/docs/app/guides/accessibility-testing.mdx index 827095944e..62d4e594cf 100644 --- a/docs/app/guides/accessibility-testing.mdx +++ b/docs/app/guides/accessibility-testing.mdx @@ -169,6 +169,13 @@ This means that, without some assertions about either the `button` element itsel Developers who are unfamiliar with accessibility may assume that if a Testing Library `ByRole` locator can be made to pass before and after a code change, there has been no functional or accessibility-related change in the underlying element. As we've seen, this is not actually the case, because of the extra behavior browsers only implement for native HTML elements. For more about this difference and why semantic HTML elements are preferred, see the [first rule of Accessible Rich Internet Applications (ARIA)](https://www.w3.org/TR/using-aria/#rule1). +### Keyboard navigation + +To test intra-page navigation with the keyboard, you can use the [`cy.press()`](/api/commands/press) to dispatch native tab events. + +Note that the application under test does not have focus by default. You must focus an element in your application before it will receive +this event. + ## Where to test accessibility So what should you do in your test automation to help confirm the UI is accessible? First of all, for known critical areas like forms or checkout flows, ensure that the accessibility behavior is tested explicitly in at least one place. The means verifying that form fields and buttons have the correct labels and use the expected HTML elements, and other aspects of the DOM that communicate necessary information. From 36edf4d17bc64de3ce1220db070fc17123850497 Mon Sep 17 00:00:00 2001 From: AtofStryker Date: Tue, 8 Apr 2025 16:51:58 -0400 Subject: [PATCH 2/4] chore: add 14.3.0 changelog to documentation --- docs/app/references/changelog.mdx | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index 5f926b69aa..e04a490cfa 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -8,6 +8,31 @@ sidebar_label: Changelog # Changelog +## 14.3.0 + +_Released 4/8/2025_ + +**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). +- Fixed an issue where Firefox BiDi was prematurely removing prerequests on pending requests. Fixes [#31376](https://github.com/cypress-io/cypress/issues/31376). +- Fixed an [issue](https://github.com/electron/electron/issues/45398) with Electron causing slow animations and increased test times by starting a CDP screencast with a noop configuration. Fixes [#30980](https://github.com/cypress-io/cypress/issues/30980). + +**Misc:** + +- Added an automation command for dispatching key press events to CDP and BiDi automated browsers. Addressed in [#31366](https://github.com/cypress-io/cypress/pull/31366). +- Updated error message around `injectDocumentDomain` removal to mention a future version of Cypress instead of Cypress 15. Addresses [#31373](https://github.com/cypress-io/cypress/issues/31373). Addressed in [#31375](https://github.com/cypress-io/cypress/pull/31375). + +**Dependency Updates:** + +- Upgraded `mocha` from `7.0.1` to `7.2.0`. Addressed in [#31423](https://github.com/cypress-io/cypress/pull/31423) and [#31432](https://github.com/cypress-io/cypress/pull/31432). +- Upgraded `webdriver` from `9.7.3` to `9.11.0`. Addressed in [#31315](https://github.com/cypress-io/cypress/pull/31315). +- Upgraded `win-version-info` from `5.0.1` to `6.0.1`. Addressed in [#31358](https://github.com/cypress-io/cypress/pull/31358). + ## 14.2.1 _Released 3/26/2025_ From 1c4cfee6f1de123c06422a1edba903a81f53ef9d Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Tue, 8 Apr 2025 16:58:29 -0400 Subject: [PATCH 3/4] Update docs/app/guides/accessibility-testing.mdx --- docs/app/guides/accessibility-testing.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/app/guides/accessibility-testing.mdx b/docs/app/guides/accessibility-testing.mdx index 62d4e594cf..f9d7a704d6 100644 --- a/docs/app/guides/accessibility-testing.mdx +++ b/docs/app/guides/accessibility-testing.mdx @@ -173,9 +173,6 @@ Developers who are unfamiliar with accessibility may assume that if a Testing Li To test intra-page navigation with the keyboard, you can use the [`cy.press()`](/api/commands/press) to dispatch native tab events. -Note that the application under test does not have focus by default. You must focus an element in your application before it will receive -this event. - ## Where to test accessibility So what should you do in your test automation to help confirm the UI is accessible? First of all, for known critical areas like forms or checkout flows, ensure that the accessibility behavior is tested explicitly in at least one place. The means verifying that form fields and buttons have the correct labels and use the expected HTML elements, and other aspects of the DOM that communicate necessary information. From 0e4700a10db29adf1b26c36ccd2e1e88a187e82a Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Tue, 8 Apr 2025 17:00:35 -0400 Subject: [PATCH 4/4] Update docs/app/references/changelog.mdx Co-authored-by: Bill Glesias --- docs/app/references/changelog.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index e04a490cfa..723d16b81e 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -14,7 +14,7 @@ _Released 4/8/2025_ **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). +- The [`cy.press()`](/api/commands/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:**