feat: User Event core code (#1405)

* chore: extract user event common parts

* chore: stub press/type implementations

* chore: add sample tests

* refactor: tweaks

* chore: improve test coverage

* chore: more sample tests

* refactor: remove Date.now touch event timestamp

* chore: hide new docs from website

* feat: expose direct access

Author: mdjastrzebski

package.json

@@ -29,7 +29,8 @@
     "jest-preset/",
     "typings/index.flow.js",
     "pure.js",
-    "dont-cleanup-after-each.js"
+    "dont-cleanup-after-each.js",
+    "!**/test-utils"
   ],
   "devDependencies": {
     "@babel/cli": "^7.19.3",

src/fireEvent.ts

@@ -9,7 +9,7 @@ const isHostTextInput = (element?: ReactTestInstance) => {
   return element?.type === getHostComponentNames().textInput;
 };
 
-function isTouchResponder(element: ReactTestInstance) {
+export function isTouchResponder(element: ReactTestInstance) {
   if (!isHostElement(element)) {
     return false;
   }
@@ -19,7 +19,7 @@ function isTouchResponder(element: ReactTestInstance) {
   );
 }
 
-function isPointerEventEnabled(
+export function isPointerEventEnabled(
   element: ReactTestInstance,
   isParent?: boolean
 ): boolean {
@@ -63,7 +63,7 @@ const textInputEventsIgnoringEditableProp = new Set([
   'onScroll',
 ]);
 
-function isEventEnabled(
+export function isEventEnabled(
   element: ReactTestInstance,
   eventName: string,
   nearestTouchResponder?: ReactTestInstance

src/test-utils/events.ts

@@ -0,0 +1,20 @@
+interface EventEntry {
+  name: string;
+  payload: any;
+}
+
+export function createEventLogger() {
+  const events: EventEntry[] = [];
+  const logEvent = (name: string) => {
+    return (event: unknown) => {
+      const eventEntry: EventEntry = {
+        name,
+        payload: event,
+      };
+
+      events.push(eventEntry);
+    };
+  };
+
+  return { events, logEvent };
+}

src/test-utils/index.ts

@@ -0,0 +1 @@
+export * from './events';

src/user-event/event-builder/common.ts

@@ -0,0 +1,48 @@
+export const CommonEventBuilder = {
+  /**
+   * Experimental values:
+   * - iOS: `{"changedTouches": [[Circular]], "identifier": 1, "locationX": 253, "locationY": 30.333328247070312, "pageX": 273, "pageY": 141.3333282470703, "target": 75, "timestamp": 875928682.0450834, "touches": [[Circular]]}`
+   * - Android: `{"changedTouches": [[Circular]], "identifier": 0, "locationX": 160, "locationY": 40.3636360168457, "pageX": 180, "pageY": 140.36363220214844, "target": 53, "targetSurface": -1, "timestamp": 10290805, "touches": [[Circular]]}`
+   */
+  touch: () => {
+    return {
+      nativeEvent: {
+        changedTouches: [],
+        identifier: 0,
+        locationX: 0,
+        locationY: 0,
+        pageX: 0,
+        pageY: 0,
+        target: 0,
+        timestamp: 0,
+        touches: [],
+      },
+    };
+  },
+
+  /**
+   * Experimental values:
+   * - iOS: `{"eventCount": 0, "target": 75, "text": ""}`
+   * - Android: `{"target": 53}`
+   */
+  focus: () => {
+    return {
+      nativeEvent: {
+        target: 0,
+      },
+    };
+  },
+
+  /**
+   * Experimental values:
+   * - iOS: `{"eventCount": 0, "target": 75, "text": ""}`
+   * - Android: `{"target": 53}`
+   */
+  blur: () => {
+    return {
+      nativeEvent: {
+        target: 0,
+      },
+    };
+  },
+};

src/user-event/event-builder/index.ts

@@ -0,0 +1,5 @@
+import { CommonEventBuilder } from './common';
+
+export const EventBuilder = {
+  Common: CommonEventBuilder,
+};

src/user-event/index.ts

@@ -0,0 +1,11 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import { setup } from './setup';
+
+export const userEvent = {
+  setup,
+
+  // Direct access for User Event v13 compatibility
+  press: (element: ReactTestInstance) => setup().press(element),
+  type: (element: ReactTestInstance, text: string) =>
+    setup().type(element, text),
+};

src/user-event/press/__tests__/__snapshots__/press.test.tsx.snap

@@ -0,0 +1,54 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`user.press() dispatches required events on Text 1`] = `
+[
+  {
+    "name": "pressIn",
+    "payload": {
+      "nativeEvent": {
+        "changedTouches": [],
+        "identifier": 0,
+        "locationX": 0,
+        "locationY": 0,
+        "pageX": 0,
+        "pageY": 0,
+        "target": 0,
+        "timestamp": 0,
+        "touches": [],
+      },
+    },
+  },
+  {
+    "name": "press",
+    "payload": {
+      "nativeEvent": {
+        "changedTouches": [],
+        "identifier": 0,
+        "locationX": 0,
+        "locationY": 0,
+        "pageX": 0,
+        "pageY": 0,
+        "target": 0,
+        "timestamp": 0,
+        "touches": [],
+      },
+    },
+  },
+  {
+    "name": "pressOut",
+    "payload": {
+      "nativeEvent": {
+        "changedTouches": [],
+        "identifier": 0,
+        "locationX": 0,
+        "locationY": 0,
+        "pageX": 0,
+        "pageY": 0,
+        "target": 0,
+        "timestamp": 0,
+        "touches": [],
+      },
+    },
+  },
+]
+`;

src/user-event/press/__tests__/press.test.tsx

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import { Text } from 'react-native';
+import { createEventLogger } from '../../../test-utils';
+import { render } from '../../..';
+import { userEvent } from '../..';
+
+beforeEach(() => {
+  jest.resetAllMocks();
+});
+
+describe('user.press()', () => {
+  it('dispatches required events on Text', async () => {
+    const { events, logEvent } = createEventLogger();
+    const user = userEvent.setup();
+    const screen = render(
+      <Text
+        testID="view"
+        onPress={logEvent('press')}
+        onPressIn={logEvent('pressIn')}
+        onPressOut={logEvent('pressOut')}
+      />
+    );
+
+    await user.press(screen.getByTestId('view'));
+
+    const eventNames = events.map((event) => event.name);
+    expect(eventNames).toEqual(['pressIn', 'press', 'pressOut']);
+    expect(events).toMatchSnapshot();
+  });
+
+  it('supports direct access', async () => {
+    const { events, logEvent } = createEventLogger();
+    const screen = render(
+      <Text
+        testID="view"
+        onPress={logEvent('press')}
+        onPressIn={logEvent('pressIn')}
+        onPressOut={logEvent('pressOut')}
+      />
+    );
+
+    await userEvent.press(screen.getByTestId('view'));
+
+    const eventNames = events.map((event) => event.name);
+    expect(eventNames).toEqual(['pressIn', 'press', 'pressOut']);
+  });
+
+  it.each(['modern', 'legacy'])('works with fake %s timers', async (type) => {
+    jest.useFakeTimers({ legacyFakeTimers: type === 'legacy' });
+
+    const { events, logEvent } = createEventLogger();
+    const user = userEvent.setup();
+    const screen = render(
+      <Text
+        testID="view"
+        onPress={logEvent('press')}
+        onPressIn={logEvent('pressIn')}
+        onPressOut={logEvent('pressOut')}
+      />
+    );
+
+    await user.press(screen.getByTestId('view'));
+
+    const eventNames = events.map((event) => event.name);
+    expect(eventNames).toEqual(['pressIn', 'press', 'pressOut']);
+  });
+});

src/user-event/press/index.ts

@@ -0,0 +1 @@
+export { press } from './press';

src/user-event/press/press.ts

@@ -0,0 +1,16 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import { EventBuilder } from '../event-builder';
+import { UserEventInstance } from '../setup';
+import { dispatchHostEvent, wait } from '../utils';
+
+export async function press(
+  this: UserEventInstance,
+  element: ReactTestInstance
+) {
+  // TODO provide real implementation
+  dispatchHostEvent(element, 'pressIn', EventBuilder.Common.touch());
+
+  await wait(this.config);
+  dispatchHostEvent(element, 'press', EventBuilder.Common.touch());
+  dispatchHostEvent(element, 'pressOut', EventBuilder.Common.touch());
+}

src/user-event/setup/index.ts

@@ -0,0 +1,2 @@
+export type { UserEventConfig, UserEventInstance } from './setup';
+export { setup } from './setup';

src/user-event/setup/setup.ts

@@ -0,0 +1,87 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import { jestFakeTimersAreEnabled } from '../../helpers/timers';
+import { press } from '../press';
+import { type } from '../type';
+
+export interface UserEventSetupOptions {
+  /**
+   * Between some subsequent inputs like typing a series of characters
+   * the code execution is delayed per `setTimeout` for (at least) `delay` seconds.
+   * This moves the next changes at least to next macro task
+   * and allows other (asynchronous) code to run between events.
+   *
+   * `null` prevents `setTimeout` from being called.
+   *
+   * @default 0
+   */
+  delay?: number;
+
+  /**
+   * Function to be called to advance fake timers. Setting it is necessary for
+   * fake timers to work.
+   *
+   * @example jest.advanceTimersByTime
+   */
+  advanceTimers?: (delay: number) => Promise<void> | void;
+}
+
+/**
+ * This functions allow wait to work correctly under both real and fake Jest timers.
+ */
+function universalJestAdvanceTimersBy(ms: number) {
+  if (jestFakeTimersAreEnabled()) {
+    return jest.advanceTimersByTime(ms);
+  } else {
+    return Promise.resolve();
+  }
+}
+
+const defaultOptions: Required<UserEventSetupOptions> = {
+  delay: 0,
+  advanceTimers: universalJestAdvanceTimersBy,
+};
+
+/**
+ * Creates a new instance of user event instance with the given options.
+ *
+ * @param options
+ * @returns
+ */
+export function setup(options?: UserEventSetupOptions) {
+  const config = createConfig(options);
+  const instance = createInstance(config);
+  return instance;
+}
+
+export interface UserEventConfig {
+  delay: number;
+  advanceTimers: (delay: number) => Promise<void> | void;
+}
+
+function createConfig(options?: UserEventSetupOptions): UserEventConfig {
+  return {
+    ...defaultOptions,
+    ...options,
+  };
+}
+
+export interface UserEventInstance {
+  config: UserEventConfig;
+  press: (element: ReactTestInstance) => Promise<void>;
+  type: (element: ReactTestInstance, text: string) => Promise<void>;
+}
+
+function createInstance(config: UserEventConfig): UserEventInstance {
+  const instance = {
+    config,
+  } as UserEventInstance;
+
+  // We need to bind these functions, as they access the config through 'this.config'.
+  const api = {
+    press: press.bind(instance),
+    type: type.bind(instance),
+  };
+
+  Object.assign(instance, api);
+  return instance;
+}

src/user-event/type/__tests__/__snapshots__/type.test.tsx.snap

@@ -0,0 +1,26 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`user.type() dispatches required events 1`] = `
+[
+  {
+    "name": "focus",
+    "payload": {
+      "nativeEvent": {
+        "target": 0,
+      },
+    },
+  },
+  {
+    "name": "changeText",
+    "payload": "Hello World!",
+  },
+  {
+    "name": "blur",
+    "payload": {
+      "nativeEvent": {
+        "target": 0,
+      },
+    },
+  },
+]
+`;