[TESTING] Add Cypress Real Events for a11y UI testing

cypress/support/commands.js

@@ -1,8 +1,33 @@
 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
 // @see https://github.com/cypress-io/cypress/blob/develop/npm/react/docs/providers-and-composition.md
 Cypress.Commands.add('mount', (children) => {
   return cypressMount(<EuiProvider>{children}</EuiProvider>);
 });
+
+// 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(
+    <Fragment>
+      <div
+        data-test-subj="cypress-real-event-target"
+        style={{ height: '1px', width: '1px' }}
+      />
+      {children}
+    </Fragment>
+  ).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);
+  }
+});

cypress/support/index.d.ts

@@ -3,5 +3,13 @@ declare namespace Cypress {
 
   interface Chainable<Subject> {
     mount(children: React.ReactNode): Cypress.Chainable<MountReturn>;
+    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 repeat `realPress()`. Defaults to 2.
+     */
+    repeatRealPress(keyToPress: string | string[], count?: number): void;
   }
 }

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) => {

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

src/components/accordion/accordion.spec.tsx

@@ -0,0 +1,126 @@
+/*
+ * 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(
+        <EuiAccordion {...baseProps}>
+          <EuiPanel color="subdued">
+            Any content inside of <strong>EuiAccordion</strong> will appear
+            here.
+          </EuiPanel>
+        </EuiAccordion>
+      );
+      cy.realPress('Tab');
+      cy.focused().contains('Click me to toggle');
+      cy.end();
+    });
+
+    it('opens and closes on ENTER keypress', () => {
+      cy.realMount(
+        <EuiAccordion {...baseProps}>
+          <EuiPanel color="subdued">
+            Any content inside of <strong>EuiAccordion</strong> will appear
+            here.
+          </EuiPanel>
+        </EuiAccordion>
+      );
+      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');
+      cy.end();
+    });
+
+    it('opens and closes on SPACE keypress', () => {
+      cy.realMount(
+        <EuiAccordion {...baseProps}>
+          <EuiPanel color="subdued">
+            Any content inside of <strong>EuiAccordion</strong> will appear
+            here.
+          </EuiPanel>
+        </EuiAccordion>
+      );
+      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');
+      cy.end();
+    });
+  });
+
+  describe('Props and keyboard navigation', () => {
+    it('should not have an arrow', () => {
+      cy.realMount(
+        <EuiAccordion {...noArrowProps}>
+          <EuiPanel color="subdued">
+            Any content inside of <strong>EuiAccordion</strong> will appear
+            here.
+          </EuiPanel>
+        </EuiAccordion>
+      );
+      cy.get('.euiAccordion__iconButton').should('not.exist');
+      cy.end();
+    });
+
+    it('manages focus when panel is opened', () => {
+      cy.realMount(
+        <EuiAccordion {...noArrowProps}>
+          <EuiPanel color="subdued">
+            Any content inside of <strong>EuiAccordion</strong> will appear
+            here. We will include <a href="#">a link</a> to confirm focus.
+          </EuiPanel>
+        </EuiAccordion>
+      );
+      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');
+      cy.end();
+    });
+
+    it('manages focus when forceState is open', () => {
+      cy.realMount(
+        <EuiAccordion {...noArrowProps} forceState="open">
+          <EuiPanel color="subdued">
+            Any content inside of <strong>EuiAccordion</strong> will appear
+            here. We will include <a href="#">a link</a> to confirm focus.
+          </EuiPanel>
+        </EuiAccordion>
+      );
+      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');
+      cy.end();
+    });
+  });
+});

src/components/context_menu/context_menu_panel.spec.tsx

@@ -19,7 +19,6 @@ describe('EuiContextMenuPanel', () => {
           <button data-test-subj="button">Hello world</button>
         </EuiContextMenuPanel>
       );
-
       cy.focused().should('have.attr', 'data-test-subj', 'button');
     });
 
@@ -29,7 +28,6 @@ describe('EuiContextMenuPanel', () => {
           <button data-test-subj="button">Hello world</button>
         </EuiContextMenuPanel>
       );
-
       cy.focused().should('not.exist');
     });
   });
@@ -47,49 +45,42 @@ describe('EuiContextMenuPanel', () => {
       </EuiContextMenuItem>,
     ];
 
-    // 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(<EuiContextMenuPanel items={items} />);
-        cy.wait(FLAKE_WAIT);
       });
 
       it('focuses the panel by default', () => {
         cy.focused().should('have.attr', 'class', '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;
+        });
       });
     });
   });

tsconfig-cypress.json

@@ -3,5 +3,8 @@
   "include": [
     "./src/**/*.spec.tsx",
   ],
-  "exclude": ["node_modules"]
+  "compilerOptions": {
+    "types": ["cypress", "cypress-real-events"]
+  },
+  "exclude": ["node_modules"],
 }

wiki/cypress-testing.md

@@ -81,6 +81,53 @@ 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 { mount } from '@cypress/react';
+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(<TestComponent />);
+
+    /* 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(<TestComponent />);
+    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.

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"