Create packages/dom-event-testing-library (#17660)

Moves the unit testing library for events into the `packages` directory so it can more easily be used in tests for other react packages, and mirrored internally to help with testing of event hooks we prototype in www.

.eslintrc.js

@@ -141,6 +141,7 @@ module.exports = {
         '**/__tests__/**/*.js',
         'scripts/**/*.js',
         'packages/*/npm/**/*.js',
+        'packages/dom-event-testing-library/**/*.js',
         'packages/react-devtools*/**/*.js'
       ],
       rules: {

packages/dom-event-testing-library/README.md

@@ -0,0 +1,98 @@
+# `dom-event-testing-library`
+
+A library for unit testing events via high-level interactions, e.g., `pointerdown`,
+that produce realistic and complete DOM event sequences.
+
+There are number of challenges involved in unit testing modules that work with
+DOM events.
+
+1. Gesture recognizers may need to support environments with and without support for
+   the `PointerEvent` API.
+2. Gesture recognizers may need to support various user interaction modes including
+   mouse, touch, and pen use.
+3. Gesture recognizers must account for the actual event sequences browsers produce
+   (e.g., emulated touch and mouse events.)
+4. Gesture recognizers must work with "virtual" events produced by tools like
+   screen-readers.
+
+Writing unit tests to cover all these scenarios is tedious and error prone. This
+event testing library is designed to solve these issues by allowing developers to
+more easily dispatch events in unit tests, and to more reliably test pointer
+interactions using a high-level API based on `PointerEvent`. Here's a basic example:
+
+```js
+import {
+  describeWithPointerEvent,
+  testWithPointerType,
+  createEventTarget,
+  setPointerEvent,
+  resetActivePointers
+} from 'dom-event-testing-library';
+
+describeWithPointerEvent('useTap', hasPointerEvent => {
+  beforeEach(() => {
+    // basic PointerEvent mock
+    setPointerEvent(hasPointerEvent);
+  });
+
+  afterEach(() => {
+    // clear active pointers between test runs
+    resetActivePointers();
+  });
+
+  // test all the pointer types supported by the environment
+  testWithPointerType('pointer down', pointerType => {
+    const ref = createRef(null);
+    const onTapStart = jest.fn();
+    render(() => {
+      useTap(ref, { onTapStart });
+      return <div ref={ref} />
+    });
+
+    // create an event target
+    const target = createEventTarget(ref.current);
+    // dispatch high-level pointer event
+    target.pointerdown({ pointerType });
+
+    expect(onTapStart).toBeCalled();
+  });
+});
+```
+
+This tests the interaction in multiple scenarios. In each case, a realistic DOM
+event sequence–with complete mock events–is produced. When running in a mock
+environment without the `PointerEvent` API, the test runs for both `mouse` and
+`touch` pointer types. When `touch` is the pointer type it produces emulated mouse
+events. When running in a mock environment with the `PointerEvent` API, the test
+runs for `mouse`, `touch`, and `pen` pointer types.
+
+It's important to cover all these scenarios because it's very easy to introduce
+bugs – e.g., double calling of callbacks – if not accounting for emulated mouse
+events, differences in target capturing between `touch` and `mouse` pointers, and
+the different semantics of `button` across event APIs.
+
+Default values are provided for the expected native events properties. They can
+also be customized as needed in a test.
+
+```js
+target.pointerdown({
+  button: 0,
+  buttons: 1,
+  pageX: 10,
+  pageY: 10,
+  pointerType,
+  // NOTE: use x,y instead of clientX,clientY
+  x: 10,
+  y: 10
+});
+```
+
+Tests that dispatch multiple pointer events will dispatch multi-touch native events
+on the target.
+
+```js
+// first pointer is active
+target.pointerdown({pointerId: 1, pointerType});
+// second pointer is active
+target.pointerdown({pointerId: 2, pointerType});
+```

packages/dom-event-testing-library/package.json

@@ -0,0 +1,5 @@
+{
+  "private": true,
+  "name": "dom-event-testing-library",
+  "version": "0.0.0"
+}

packages/react-interactions/events/src/dom/event-testing-library/touchStore.js → packages/dom-event-testing-library/touchStore.js

@@ -25,7 +25,6 @@ export function addTouch(touch) {
   }
   if (activeTouches.get(target).get(identifier)) {
     // Do not allow existing touches to be overwritten
-    // eslint-disable-next-line react-internal/no-production-logging
     console.error(
       'Touch with identifier %s already exists. Did not record touch start.',
       identifier,
@@ -41,7 +40,6 @@ export function updateTouch(touch) {
   if (activeTouches.get(target) != null) {
     activeTouches.get(target).set(identifier, touch);
   } else {
-    // eslint-disable-next-line react-internal/no-production-logging
     console.error(
       'Touch with identifier %s does not exist. Cannot record touch move without a touch start.',
       identifier,
@@ -56,7 +54,6 @@ export function removeTouch(touch) {
     if (activeTouches.get(target).has(identifier)) {
       activeTouches.get(target).delete(identifier);
     } else {
-      // eslint-disable-next-line react-internal/no-production-logging
       console.error(
         'Touch with identifier %s does not exist. Cannot record touch end without a touch start.',
         identifier,

packages/react-interactions/accessibility/src/__tests__/FocusContain-test.internal.js

@@ -7,7 +7,7 @@
  * @flow
  */
 
-import {createEventTarget} from 'react-interactions/events/src/dom/event-testing-library';
+import {createEventTarget} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;

packages/react-interactions/accessibility/src/__tests__/FocusGroup-test.internal.js

@@ -7,7 +7,7 @@
  * @flow
  */
 
-import {createEventTarget} from 'react-interactions/events/src/dom/event-testing-library';
+import {createEventTarget} from 'dom-event-testing-library';
 import {emulateBrowserTab} from '../shared/emulateBrowserTab';
 
 let React;

packages/react-interactions/accessibility/src/__tests__/FocusTable-test.internal.js

@@ -7,7 +7,7 @@
  * @flow
  */
 
-import {createEventTarget} from 'react-interactions/events/src/dom/event-testing-library';
+import {createEventTarget} from 'dom-event-testing-library';
 import {emulateBrowserTab} from '../shared/emulateBrowserTab';
 
 let React;

packages/react-interactions/accessibility/src/shared/emulateBrowserTab.js

@@ -9,7 +9,7 @@
 
 'use strict';
 
-import {createEventTarget} from 'react-interactions/events/src/dom/event-testing-library';
+import {createEventTarget} from 'dom-event-testing-library';
 
 // This function is used by the a11y modules for testing
 export function emulateBrowserTab(backwards: boolean): void {

packages/react-interactions/events/src/dom/__tests__/ContextMenu-test.internal.js

@@ -14,7 +14,7 @@ import {
   createEventTarget,
   platform,
   setPointerEvent,
-} from '../event-testing-library';
+} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;

packages/react-interactions/events/src/dom/__tests__/Focus-test.internal.js

@@ -13,7 +13,7 @@ import {
   createEventTarget,
   setPointerEvent,
   platform,
-} from '../event-testing-library';
+} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;

packages/react-interactions/events/src/dom/__tests__/FocusWithin-test.internal.js

@@ -9,7 +9,7 @@
 
 'use strict';
 
-import {createEventTarget, setPointerEvent} from '../event-testing-library';
+import {createEventTarget, setPointerEvent} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;

packages/react-interactions/events/src/dom/__tests__/Hover-test.internal.js

@@ -9,7 +9,7 @@
 
 'use strict';
 
-import {createEventTarget, setPointerEvent} from '../event-testing-library';
+import {createEventTarget, setPointerEvent} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;

packages/react-interactions/events/src/dom/__tests__/Keyboard-test.internal.js

@@ -14,7 +14,7 @@ let ReactFeatureFlags;
 let ReactDOM;
 let useKeyboard;
 
-import {createEventTarget} from '../event-testing-library';
+import {createEventTarget} from 'dom-event-testing-library';
 
 function initializeModules(hasPointerEvents) {
   jest.resetModules();

packages/react-interactions/events/src/dom/__tests__/MixedResponders-test-internal.js

@@ -9,7 +9,7 @@
 
 'use strict';
 
-import {createEventTarget} from '../event-testing-library';
+import {createEventTarget} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;

packages/react-interactions/events/src/dom/__tests__/Press-test.internal.js

@@ -16,7 +16,7 @@ import {
   describeWithPointerEvent,
   resetActivePointers,
   setPointerEvent,
-} from '../event-testing-library';
+} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;

packages/react-interactions/events/src/dom/__tests__/PressLegacy-test.internal.js

@@ -15,7 +15,7 @@ import {
   createEventTarget,
   resetActivePointers,
   setPointerEvent,
-} from '../event-testing-library';
+} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;

packages/react-interactions/events/src/dom/__tests__/Scroll-test.internal.js

@@ -9,7 +9,7 @@
 
 'use strict';
 
-import {createEventTarget, setPointerEvent} from '../event-testing-library';
+import {createEventTarget, setPointerEvent} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;

packages/react-interactions/events/src/dom/__tests__/Tap-test.internal.js

@@ -17,7 +17,7 @@ import {
   setPointerEvent,
   testWithPointerType,
   resetActivePointers,
-} from '../event-testing-library';
+} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;

packages/react-reconciler/src/__tests__/ReactScope-test.internal.js

@@ -9,7 +9,7 @@
 
 'use strict';
 
-import {createEventTarget} from 'react-interactions/events/src/dom/event-testing-library';
+import {createEventTarget} from 'dom-event-testing-library';
 
 let React;
 let ReactFeatureFlags;