Skip to content

Commit a83ffa7

Browse files
cacieprinsjennifer-shehaneMikeMcC399
authored
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 <[email protected]> * Fix broken link * lint --------- Co-authored-by: Jennifer Shehane <[email protected]> Co-authored-by: Mike McCready <[email protected]>
1 parent ae3985c commit a83ffa7

File tree

6 files changed

+187
-14
lines changed

6 files changed

+187
-14
lines changed

‎docs/api/commands/focus.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,4 +159,5 @@ the following:
159159
- [`.blur()`](/api/commands/blur)
160160
- [`.click()`](/api/commands/click)
161161
- [`cy.focused()`](/api/commands/focused)
162+
- [`cy.press()`](/api/commands/press)
162163
- [`.type()`](/api/commands/type)

‎docs/api/commands/press.mdx

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: 'cy.press() | Cypress Documentation'
3+
description: Trigger native key events in your application to simulate keyboard interactions.
4+
sidebar_label: press
5+
slug: /api/commands/press
6+
componentSpecific: false
7+
---
8+
9+
<ProductHeading product="app" />
10+
11+
# press
12+
13+
Trigger native key events in your application to simulate keyboard interactions.
14+
15+
A `keydown`, `press`, and `keyup` event will be dispatched directly to the browser window.
16+
17+
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.
18+
19+
Currently, the only key supported is `Tab`.
20+
21+
:::caution
22+
23+
<strong>Supported Browsers:</strong>
24+
This command is supported in chromium browsers and Firefox versions >= v135. WebKit
25+
is not supported. This command will fail if executed in a browser that does not support
26+
it.
27+
28+
:::
29+
30+
## Syntax
31+
32+
```javascript
33+
cy.press(key)
34+
cy.press(key, options)
35+
```
36+
37+
## Signature
38+
39+
```typescript
40+
interface PressCommand {
41+
(
42+
key: KeyPressSupportedKeys,
43+
options?: Partial<Cypress.Loggable> & Partial<Cypress.Timeoutable>
44+
): void
45+
}
46+
```
47+
48+
## Usage
49+
50+
<Icon name="check-circle" color="green" /> **Correct Usage**
51+
52+
```javascript
53+
cy.get('input.first').focus()
54+
cy.press(Cypress.Keyboard.Keys.TAB)
55+
cy.get('input.second').should('have.focus')
56+
```
57+
58+
<Icon name="exclamation-triangle" color="red" /> **Incorrect Usage**
59+
60+
```javascript
61+
cy.get('input.first').focus()
62+
cy.press(Cypress.Keyboard.Keys.TAB)
63+
// Errors because press yields null
64+
.should('have.focus')
65+
```
66+
67+
### Arguments
68+
69+
<Icon name="angle-right" /> **key _(String)_**
70+
71+
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.
72+
73+
### Supported Keys
74+
75+
| Reference | Value |
76+
| --------------------------- | ------- |
77+
| `Cypress.Keyboard.Keys.TAB` | `"Tab"` |
78+
79+
<Icon name="angle-right" /> **options _(Object)_**
80+
81+
Pass in an options object to change the default behavior of `.press()`.
82+
83+
| Option | Default | Description |
84+
| --------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
85+
| `log` | `true` | Displays the command in the [Command log](/app/core-concepts/open-mode#Command-Log) |
86+
| `timeout` | [`defaultCommandTimeout`](/app/references/configuration#Timeouts) | Time to wait for `cy.press()` to resolve before timing out |
87+
88+
<HeaderYields />
89+
90+
- `cy.press()` yields `null`.
91+
92+
## Examples
93+
94+
### Test focus order of tab
95+
96+
```js
97+
it('moves focus to the next form element when pressing Tab', () => {
98+
cy.visit('/my-login')
99+
cy.get('input.email').type('username')
100+
cy.press(Cypress.Keyboard.Keys.TAB)
101+
cy.get('input.password').should('have.focus')
102+
})
103+
```
104+
105+
### Test autocomplete of search input with tab
106+
107+
```js
108+
it('autocompletes search input when pressing Tab', () => {
109+
cy.get('[data-cy="search"]').type('cy')
110+
cy.press(Cypress.Keyboard.Keys.TAB)
111+
cy.get('[data-cy="search"]').should('have.value', 'cypress')
112+
})
113+
```
114+
115+
## Notes
116+
117+
### Transient activation
118+
119+
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.
120+
121+
If your application prevents the default behavior of the `beforeunload` event, this may cause issues when navigating away from the current page.
122+
123+
## History
124+
125+
| Version | Changes |
126+
| ----------------------------------- | ---------------------------- |
127+
| [14.3.0](/app/references/changelog) | Added the `.press()` command |
128+
129+
## See also
130+
131+
- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api)
132+
- [`.focus()`](/api/commands/focus)
133+
- [`.focused()`](/api/commands/focused)
134+
- [`.type()`](/api/commands/type)

‎docs/api/commands/type.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -664,5 +664,6 @@ following:
664664
- [`.clear()`](/api/commands/clear)
665665
- [`.click()`](/api/commands/click)
666666
- [`.focus()`](/api/commands/focus)
667+
- [`cy.press()`](/api/commands/press)
667668
- [`.submit()`](/api/commands/submit)
668669
- [`Cypress.Keyboard`](/api/cypress-api/keyboard-api)

‎docs/api/cypress-api/keyboard-api.mdx

Lines changed: 43 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,29 @@ sidebar_position: 150
99

1010
# Cypress.Keyboard
1111

12-
The Keyboard API allows you set the default values for how the
12+
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
1313
[.type()](/api/commands/type) command is executed.
1414

1515
## Syntax
1616

1717
```javascript
18+
Cypress.Keyboard.Keys(key)
1819
Cypress.Keyboard.defaults(options)
1920
```
2021

21-
### Arguments
22+
### Keys Arguments
23+
24+
<Icon name="angle-right" /> **key _(String)_**
25+
26+
The key available for `cy.press()`.
27+
28+
The following keys are supported:
29+
30+
| Reference | Value |
31+
| --------------------------- | ------- |
32+
| `Cypress.Keyboard.Keys.TAB` | `"Tab"` |
33+
34+
### defaults Arguments
2235

2336
<Icon name="angle-right" /> **options _(Object)_**
2437

@@ -30,6 +43,13 @@ An object containing the following:
3043

3144
## Examples
3245

46+
### Press tab key
47+
48+
```javascript
49+
cy.press(Cypress.Keyboard.Keys.TAB)
50+
cy.get('input.second').should('have.focus')
51+
```
52+
3353
### Slow down typing by increasing the keystroke delay
3454

3555
```javascript
@@ -59,22 +79,31 @@ The keystroke delay can also be set via
5979
which can be useful when setting it for a single test or a subset of tests.
6080

6181
```javascript
62-
it('removes keystroke delay for all typing in this test', { keystrokeDelay: 0 }, () => {
63-
cy.get('input').eq(0).type('fast typing')
64-
cy.get('input').eq(1).type('more fast typing')
65-
})
66-
67-
describe('removes keystroke delay in all tests in this suite', { keystrokeDelay: 0 }, () => {
68-
it('types fast in the first input', () => {
82+
it(
83+
'removes keystroke delay for all typing in this test',
84+
{ keystrokeDelay: 0 },
85+
() => {
6986
cy.get('input').eq(0).type('fast typing')
70-
})
71-
72-
it('types fast in the second input', () => {
7387
cy.get('input').eq(1).type('more fast typing')
74-
})
75-
}))
88+
}
89+
)
90+
91+
describe(
92+
'removes keystroke delay in all tests in this suite',
93+
{ keystrokeDelay: 0 },
94+
() => {
95+
it('types fast in the first input', () => {
96+
cy.get('input').eq(0).type('fast typing')
97+
})
98+
99+
it('types fast in the second input', () => {
100+
cy.get('input').eq(1).type('more fast typing')
101+
})
102+
}
103+
)
76104
```
77105

78106
## See also
79107

108+
- [`cy.press()`](/api/commands/press)
80109
- [`.type()`](/api/commands/type)

‎docs/api/table-of-contents.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,7 @@ Cypress has a variety of additional commands to help write tests.
139139
| [`.mount()`](/api/commands/mount) | Mount a component for Cypress Component Testing. |
140140
| [`.origin()`](/api/commands/origin) | Visit multiple domains of different origin in a single test. |
141141
| [`.pause()`](/api/commands/pause) | Pause test execution, allowing interaction with the application under test before resuming. |
142+
| [`.press()`](/api/commands/press) | Trigger native key events in your application to simulate real user keyboard interactions. |
142143
| [`.readFile()`](/api/commands/readfile) | Read a file from disk. |
143144
| [`.reload()`](/api/commands/reload) | Reload the page. |
144145
| [`.request()`](/api/commands/request) | Make an HTTP request. |

‎docs/app/guides/accessibility-testing.mdx

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,13 @@ This means that, without some assertions about either the `button` element itsel
169169

170170
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).
171171

172+
### Keyboard navigation
173+
174+
To test intra-page navigation with the keyboard, you can use the [`cy.press()`](/api/commands/press) to dispatch native tab events.
175+
176+
Note that the application under test does not have focus by default. You must focus an element in your application before it will receive
177+
this event.
178+
172179
## Where to test accessibility
173180

174181
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.

0 commit comments

Comments
 (0)