diff --git a/cypress/support/commands.js b/cypress/support/commands.js index 796ad8435e3..bf637d62d16 100644 --- a/cypress/support/commands.js +++ b/cypress/support/commands.js @@ -1,4 +1,5 @@ import { mount as cypressMount } from '@cypress/react'; +import { React, Fragment } from 'react'; import { EuiProvider } from '../../src'; // Provide global cy.mount() shortcut that includes required providers @@ -6,3 +7,27 @@ import { EuiProvider } from '../../src'; Cypress.Commands.add('mount', (children) => { return cypressMount({children}); }); + +// This ensures the correct testing window has focus when using Cypress Real Events. +// @see https://github.com/dmtrKovalenko/cypress-real-events/issues/196 +Cypress.Commands.add('realMount', (children) => { + cy.mount( + +
+ {children} + + ).then(() => { + cy.get('[data-test-subj="cypress-real-event-target"]').realClick({ + position: 'topLeft', + }); + }); +}); + +Cypress.Commands.add('repeatRealPress', (keyToPress, count = 2) => { + for (let i = 0; i < count; i++) { + cy.realPress(keyToPress); + } +}); diff --git a/cypress/support/index.d.ts b/cypress/support/index.d.ts index f42a67f5b73..0d3952f90e5 100644 --- a/cypress/support/index.d.ts +++ b/cypress/support/index.d.ts @@ -3,5 +3,13 @@ declare namespace Cypress { interface Chainable { mount(children: React.ReactNode): Cypress.Chainable; + realMount(children: React.ReactNode): void; + /** + * Repeat the Real Events `realPress()` method 2 or more times + * + * @param keyToPress Any valid key or array of keys https://docs.cypress.io/api/commands/type#Arguments + * @param count Number of times to invoke `realPress()`. Defaults to 2. + */ + repeatRealPress(keyToPress: string | string[], count?: number): void; } } diff --git a/cypress/support/index.js b/cypress/support/index.js index 0a7a68b89c1..da19e9c4fef 100644 --- a/cypress/support/index.js +++ b/cypress/support/index.js @@ -17,6 +17,7 @@ import '@cypress/code-coverage/support'; import './commands.js'; require(THEME_IMPORT); // defined by DefinePlugin in the cypress webpack config require('cypress-plugin-tab'); // adds the `.tab()` command to cypress chains, see https://docs.cypress.io/api/commands/type#Typing-tab-key-does-not-work +require('cypress-real-events/support'); // uses the Chrome Devtools Protocol to replace simulated events, see https://github.com/dmtrKovalenko/cypress-real-events#why // @see https://github.com/quasarframework/quasar/issues/2233#issuecomment-492975745 Cypress.on('uncaught:exception', (err) => { diff --git a/package.json b/package.json index e1be475e164..710ccb32098 100644 --- a/package.json +++ b/package.json @@ -158,6 +158,7 @@ "cssnano": "^4.1.10", "cypress": "^9.1.1", "cypress-plugin-tab": "^1.0.5", + "cypress-real-events": "^1.6.0", "deasync": "^0.1.20", "dedent": "^0.7.0", "dts-generator": "^3.0.0", diff --git a/src/components/accordion/accordion.spec.tsx b/src/components/accordion/accordion.spec.tsx new file mode 100644 index 00000000000..0352cba3d11 --- /dev/null +++ b/src/components/accordion/accordion.spec.tsx @@ -0,0 +1,120 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +import React from 'react'; +import { EuiAccordion, EuiAccordionProps } from './index'; +import { EuiPanel } from '../../components/panel'; +import { htmlIdGenerator } from '../../services'; + +const baseProps: EuiAccordionProps = { + buttonContent: 'Click me to toggle', + id: htmlIdGenerator()(), + initialIsOpen: false, +}; + +const noArrow = { arrowDisplay: 'none' }; +const noArrowProps: EuiAccordionProps = Object.assign(baseProps, noArrow); + +describe('EuiAccordion', () => { + describe('Keyboard and screen reader accessibility', () => { + it('renders with required props', () => { + cy.realMount( + + + Any content inside of EuiAccordion will appear + here. + + + ); + cy.realPress('Tab'); + cy.focused().contains('Click me to toggle'); + }); + + it('opens and closes on ENTER keypress', () => { + cy.realMount( + + + Any content inside of EuiAccordion will appear + here. + + + ); + cy.realPress('Tab'); + cy.focused().contains('Click me to toggle').realPress('Enter'); + cy.realPress(['Shift', 'Tab']); + cy.focused().invoke('attr', 'aria-expanded').should('equal', 'true'); + cy.realPress('Enter'); + cy.focused().invoke('attr', 'aria-expanded').should('equal', 'false'); + }); + + it('opens and closes on SPACE keypress', () => { + cy.realMount( + + + Any content inside of EuiAccordion will appear + here. + + + ); + cy.realPress('Tab'); + cy.focused().contains('Click me to toggle').realPress('Space'); + cy.realPress(['Shift', 'Tab']); + cy.focused().invoke('attr', 'aria-expanded').should('equal', 'true'); + cy.realPress('Space'); + cy.focused().invoke('attr', 'aria-expanded').should('equal', 'false'); + }); + }); + + describe('Props and keyboard navigation', () => { + it('should not have an arrow', () => { + cy.realMount( + + + Any content inside of EuiAccordion will appear + here. + + + ); + cy.get('.euiAccordion__iconButton').should('not.exist'); + }); + + it('manages focus when panel is opened', () => { + cy.realMount( + + + Any content inside of EuiAccordion will appear + here. We will include a link to confirm focus. + + + ); + cy.realPress('Tab'); + cy.focused().contains('Click me to toggle').realPress('Enter'); + cy.focused().invoke('attr', 'tabindex').should('equal', '-1'); + cy.focused().contains('Any content inside of EuiAccordion'); + cy.realPress('Tab'); + cy.focused().contains('a link'); + }); + + it('manages focus when forceState is open', () => { + cy.realMount( + + + Any content inside of EuiAccordion will appear + here. We will include a link to confirm focus. + + + ); + cy.realPress('Tab'); + cy.focused().contains('Click me to toggle'); + cy.focused().invoke('attr', 'aria-expanded').should('equal', 'true'); + cy.focused().invoke('attr', 'tabindex').should('not.exist'); + cy.realPress('Tab'); + cy.focused().contains('a link'); + }); + }); +}); diff --git a/src/components/context_menu/context_menu_panel.spec.tsx b/src/components/context_menu/context_menu_panel.spec.tsx index 45bd94e5de1..3950b471483 100644 --- a/src/components/context_menu/context_menu_panel.spec.tsx +++ b/src/components/context_menu/context_menu_panel.spec.tsx @@ -19,7 +19,6 @@ describe('EuiContextMenuPanel', () => { ); - cy.focused().should('have.attr', 'data-test-subj', 'button'); }); @@ -29,7 +28,6 @@ describe('EuiContextMenuPanel', () => { ); - cy.focused().should('not.exist'); }); }); @@ -47,13 +45,9 @@ describe('EuiContextMenuPanel', () => { , ]; - // Intermittent flake workaround: without this, the first downarrow key does not always focus into the menu items as expected - const FLAKE_WAIT = 500; - describe('up/down keys', () => { beforeEach(() => { cy.mount(); - cy.wait(FLAKE_WAIT); }); it('focuses the panel by default', () => { @@ -61,35 +55,32 @@ describe('EuiContextMenuPanel', () => { }); it('down arrow key focuses the first menu item', () => { - cy.get('body').type('{downarrow}'); - + cy.focused().should('have.attr', 'class', 'euiContextMenuPanel'); + cy.realPress('{downarrow}'); cy.focused().should('have.attr', 'data-test-subj', 'itemA'); }); it('subsequently, down arrow key focuses the next menu item', () => { - cy.get('body').type('{downarrow}'); - cy.get('body').type('{downarrow}'); - + cy.focused().should('have.attr', 'class', 'euiContextMenuPanel'); + cy.repeatRealPress('{downarrow}'); cy.focused().should('have.attr', 'data-test-subj', 'itemB'); }); it('up arrow key wraps to last menu item', () => { - cy.get('body').type('{uparrow}'); - + cy.focused().should('have.attr', 'class', 'euiContextMenuPanel'); + cy.realPress('{uparrow}'); cy.focused().should('have.attr', 'data-test-subj', 'itemC'); }); it('down arrow key wraps to first menu item', () => { - cy.get('body').type('{uparrow}'); - cy.get('body').type('{downarrow}'); - + cy.focused().should('have.attr', 'class', 'euiContextMenuPanel'); + cy.repeatRealPress('{downarrow}', 4); cy.focused().should('have.attr', 'data-test-subj', 'itemA'); }); it('subsequently, up arrow key focuses the previous menu item', () => { - cy.get('body').type('{uparrow}'); - cy.get('body').type('{uparrow}'); - + cy.focused().should('have.attr', 'class', 'euiContextMenuPanel'); + cy.repeatRealPress('{uparrow}'); cy.focused().should('have.attr', 'data-test-subj', 'itemB'); }); }); @@ -103,14 +94,10 @@ describe('EuiContextMenuPanel', () => { showNextPanel={showNextPanelHandler} /> ); - cy.wait(FLAKE_WAIT); - - cy.get('body') - .type('{downarrow}') - .type('{rightarrow}') - .then(() => { - expect(showNextPanelHandler).to.be.called; - }); + cy.realPress('{downarrow}'); + cy.realPress('{rightarrow}').then(() => { + expect(showNextPanelHandler).to.be.called; + }); }); it('left arrow key shows previous panel', () => { @@ -121,14 +108,10 @@ describe('EuiContextMenuPanel', () => { showPreviousPanel={showPreviousPanelHandler} /> ); - cy.wait(FLAKE_WAIT); - - cy.get('body') - .type('{downarrow}') - .type('{leftarrow}') - .then(() => { - expect(showPreviousPanelHandler).to.be.called; - }); + cy.realPress('{downarrow}'); + cy.realPress('{leftarrow}').then(() => { + expect(showPreviousPanelHandler).to.be.called; + }); }); }); }); diff --git a/tsconfig-cypress.json b/tsconfig-cypress.json index 1478f5de3ab..9dc65460b68 100644 --- a/tsconfig-cypress.json +++ b/tsconfig-cypress.json @@ -3,5 +3,8 @@ "include": [ "./src/**/*.spec.tsx", ], - "exclude": ["node_modules"] + "compilerOptions": { + "types": ["cypress", "cypress-real-events"] + }, + "exclude": ["node_modules"], } diff --git a/wiki/cypress-testing.md b/wiki/cypress-testing.md index 47e79d1ae13..e3826a57144 100644 --- a/wiki/cypress-testing.md +++ b/wiki/cypress-testing.md @@ -81,6 +81,52 @@ contains `{component name}.tsx`. * DON'T depend upon class names or other implementation details for `find`ing nodes, if possible. * DON'T extend the `cy.` global namespace - instead prefer to import helper functions directly +### Cypress Real Events + +> Cypress default events are simulated. That means that all events like `cy.click` or `cy.type` are fired from JavaScript. That's why these events will be untrusted (`event.isTrusted` will be `false`) and they can behave a little different from real native events. But for some cases, it can be impossible to use simulated events, for example, to fill a native alert or copy to the clipboard. This plugin solves this problem. + +[Cypress Real Events](https://github.com/dmtrKovalenko/cypress-real-events#why) + +#### Why Cypress Real Events? + +Cypress Real Events uses the [Chrome Devtools Protocol](https://chromedevtools.github.io/devtools-protocol/) to handle behaviors like a real browser. This gives us a better way to test complex events like mouse hover and keyboard focus. By using real events and making assertions against them, we can test keyboard and screen reader accessibility as users change the local state. + +#### How to write Cypress (real event) tests + +The [Cypress Real Events API](https://github.com/dmtrKovalenko/cypress-real-events#api) works seamlessly with existing `cy()` methods. If you want to press a button using Cypress Real Events, you could use `realPress('Tab')` as a replacement for the `cy.tab()` synthetic method. All Cypress Real Events methods are prefixed with the string "real". Here's a small example test: + +```jsx +import TestComponent from './test_component'; + +describe('TestComponent', () => { + it('presses a button using the Enter key', () => { + /* Use the `realMount()` command to set focus in the test window */ + cy.realMount(); + + /* Activate a button with a real keypress event */ + cy.get('[data-test-subj="submitButton"]').realPress('Enter'); + + /* Assert the button has focus and the aria-expanded attribute has updated */ + cy.focused().invoke('attr', 'aria-expanded').should('equal', 'true'); + }); + + it('presses a button using the Space key', () => { + /* Assert the button also accepts the Spacebar keypress */ + cy.realMount(); + cy.get('[data-test-subj="submitButton"]').realPress('Space'); + cy.focused().invoke('attr', 'aria-expanded').should('equal', 'true'); + }); +}); +``` + +#### Do's and don'ts for Cypress Real Events + +* DO follow [all previous guidance](#dos-and-donts) for writing Cypress tests +* DO use the correct mounting method: + * Use `cy.realMount()` if your component doesn't receive focus automatically **OR** + * Use `cy.mount()` for components that receive focus on render +* DO be on the lookout for new features! + ## Debugging tests For debugging failures locally, use `yarn test-cypress-dev`, which allows you to run a single specific test suite and runs tests in a browser window, making dev tools available to you so you can pause and inspect DOM as needed. diff --git a/yarn.lock b/yarn.lock index 251155b0dc8..c33bf991219 100755 --- a/yarn.lock +++ b/yarn.lock @@ -5533,6 +5533,11 @@ cypress-plugin-tab@^1.0.5: dependencies: ally.js "^1.4.1" +cypress-real-events@^1.6.0: + version "1.6.0" + resolved "https://registry.yarnpkg.com/cypress-real-events/-/cypress-real-events-1.6.0.tgz#277024b62a324b6937760a700e831e795c021040" + integrity sha512-QxXm0JsQkCrb2uH+fMXNDQ5kNWTzX3OtndBafdsZmNV19j+6JuTK9n52B1YVxrDrr/qzPAojcHJc5PNoQvwp+w== + cypress@^9.1.1: version "9.1.1" resolved "https://registry.yarnpkg.com/cypress/-/cypress-9.1.1.tgz#26720ca5a22077cd85f49745616b7a08152a298f"